Documentation du serveur MCP Patriboum

Patriboum est un serveur MCP (Model Context Protocol) qui expose un moteur de simulation patrimoniale française à un agent IA : construire le bilan d'un client, le simuler année par année, le stress-tester — et faire visualiser le résultat au client dans son navigateur via une simple URL qui ouvre l'application avec la session chargée.

• Endpoint : https://patriboum.com/mcp (transport streamable HTTP, stateless)
• Compatibilité : tout client MCP HTTP — Claude Desktop, Claude Code, Cursor, ZCode, Windsurf, VS Code, Gemini CLI… (voir le guide d'installation)
• Gratuit, sans inscription. Voir l'avertissement légal.

Vue d'ensemble

Un agent connecté à Patriboum peut :

1. Découvrir le domaine : catalogue des types de nœuds, règles de connexion, fiches produit par type (info_node : plafonds légaux, fiscalité sourcée, formules du moteur).
2. Construire le patrimoine d'un client : comptes, stratégies d'épargne, prêts, détenteurs, événements — sous forme de graphe orienté.
3. Simuler : projection déterministe ou Monte Carlo (jusqu'à 10 000 trajectoires), stress tests de krach, lecture en euros constants.
4. Analyser : patrimoine net (dette déduite), impôts latents, revenus, allocation par classe d'actifs, liquidité en mois d'autonomie.
5. Optimiser : répartition de l'épargne par recuit simulé, exploration de variantes du graphe.
6. Partager : chaque session possède une URL qui ouvre l'application (éditeur de graphe) avec la session déjà chargée.

Architecture : l'agent parle au serveur en JSON-RPC sur POST /mcp ; le navigateur du client ouvre le viewUrl sur l'app GET /app?load=<id> (session chargée dans l'éditeur) ou la page read-only GET /session/<id> (auto-refresh 3 s). Sessions persistées en JSON côté serveur.

Agent IA (Claude/Cursor/ZCode…)          Navigateur du client
      │                                        │
      │ POST /mcp (JSON-RPC, stateless)        │ viewUrl → /app?load=<id>
      ▼                                        ▼   (ou /session/<id>, refresh 3 s)
┌──────────────────────────────────────────────────────┐
│  Serveur Patriboum                                   │
│  /mcp ← tools MCP     /app, /session/<id> ← navigateur│
│  moteur de simulation (fiscalité FR, Monte Carlo)     │
│  sessions : data/sessions/<uuid>.json                 │
└──────────────────────────────────────────────────────┘

Démarrage rapide

1. Connecter l'agent

Ajoutez l'URL https://patriboum.com/mcp à votre client MCP préféré — les snippets par client sont sur la page installation.

2. Créer une session

create_session(name="Patrimoine SCPI de Paul")
→ { "sessionId": "…", "viewUrl": "https://patriboum.com/app?load=…" }

Donnez le viewUrl au client : le lien ouvre l'application (éditeur de graphe) avec la session chargée — recharger la page pour voir les modifications ultérieures de l'agent.

3. Construire et connecter les nœuds

add_node(type="dca",    label="Épargne SCPI", params={money: 6000, end: 20})
add_node(type="scpi",   label="SCPI Européenne",
         params={capitalValue: 20000, revenueRate: 6, frenchShare: 0})
add_node(type="holder", label="Paul",
         params={avgTaxRate: 13, taxRate: 30, part: 2.5})
add_node(type="scenario", label="Patrimoine Paul")
connect(source="<dca>", target="<scpi>")
connect(source="<holder>", target="<scpi>")
connect(source="<scpi>", target="<scenario>")

Les nodeId sont renvoyés par chaque add_node. list_node_types et info_node donnent les paramètres et défauts de chaque type.

4. Simuler et analyser

run_simulation(sessionId, years=20)
→ capital final, performance, dividendes, impôts
run_monte_carlo(sessionId, years=30, runs=3000)
→ médiane, fourchettes p10–p90, taux de réussite
get_net_worth(sessionId, spending=18000, inflation=2)
→ patrimoine net, revenu requis, en euros constants

Référence des 22 tools

Découverte

Sessions

Construction

Simulation & analyse

Optimisation

Paramètres transverses

crashes (stress test) — disponible sur run_simulation et run_monte_carlo. Chaque crash : {year, market, drawdown, recovery?, recoveryYears?, underperformance?}. Marchés : actions (CTO/PEA), crypto, av, scpi, immobilier. Après le choc à l'année year, deux formes de reprise : sous-performance (défaut — N ans sous le taux de N points, forme « L ») ou rebond (surtaxé pour refaire la perte, forme « V »).

{ year: 8, market: "actions", drawdown: -35, recoveryYears: 5 }

distribution — lognormal (défaut : tirages gaussiens avec la volatilité historique de chaque classe) ou bootstrap (rejoue de vraies années historiques — S&P 500 dividendes réinvestis 1995-2024, Bitcoin 2016-2024 — recalées sur les taux configurés). Les comptes à taux fixe (livrets, PEL, compte à terme) restent déterministes.

seed — rejoue une simulation identique : comparez deux allocations à aléa fixe.

inflation — sur get_simulation_years et get_net_worth (%, ex. 2) : convertit tous les montants de l'année N en euros constants (divisés par (1+i)^N) pour une lecture en pouvoir d'achat d'aujourd'hui. Filtre d'affichage : la simulation n'est pas recalculée.

Les 25 types de nœuds

Comptes d'investissement

Comptes d'épargne réglementée

Stratégies

Aiguillage, détenteurs, événements

Règles de connexion

• Stratégies (dca, lumpsum, loan) → comptes ou dispatcher
• Comptes → scenario ou dispatcher (le pea peut déborder vers un cto, le per vers av/cto, selon les règles de cascade)
• dispatcher → comptes uniquement ; holder → comptes (fiscalité) ; close/lock → comptes
• scenario = sortie : jamais source. Un flow sans scénario ne produit aucun résultat.

Les connexions invalides sont rejetées par connect avec un message explicatif.

Profils de prêt

Le nœud loan calcule au pas annuel selon loanType :

• amortissable (défaut) : mensualité constante ; la part de capital remboursée progresse chaque année.
• inFine : intérêts seuls chaque année, capital remboursé en totalité à l'échéance (duration obligatoire).
• capitalConstant : même capital remboursé chaque année, mensualité décroissante (duration obligatoire).

Le capital emprunté est injecté dans le compte cible à l'année start ; les mensualités sont déduites des revenus du compte.

Métadonnées descriptives (`meta`)

Chaque nœud accepte un champ meta : objet libre ignoré par le moteur, restitué aux agents LLM et affiché dans l'UI. Convention recommandée :

{
  "profile": {
    "age": 38,
    "profession": "Dirigeant de PME",
    "maritalStatus": "marié",
    "children": 2
  },
  "lifeGoals": [{ "goal": "Arrêt de l'activité à 45 ans", "targetAge": 45 }]
}

Pour une SCPI : fiche de santé alignée sur les fiches publiques (identity, health : TOF, endettement, SRI ; performance, fees, diversification…). update_node fusionne le meta en profondeur : mettre à jour {profile: {age: 39}} conserve profession et objectifs.

Déroulé type — cas « patrimoine SCPI »

1. create_session(name="Patrimoine SCPI de Paul")   → sessionId, viewUrl
2. add_node(type="dca", label="Épargne SCPI", params={money: 6000, end: 20})
3. add_node(type="scpi", label="SCPI Européenne",
            params={capitalValue: 20000, revenueRate: 6, frenchShare: 0})
4. add_node(type="holder", label="Paul",
            params={avgTaxRate: 13, taxRate: 30, part: 2.5})
5. add_node(type="scenario", label="Patrimoine Paul")
6. connect(dca → scpi), connect(holder → scpi), connect(scpi → scenario)
7. run_simulation(sessionId, years=20)
8. get_portfolio_allocation(sessionId, year=20)  → 100 % immobilier

Bonnes pratiques de présentation

• Montrez la médiane Monte Carlo au client (une chance sur deux de faire mieux), la moyenne restant un simple comparateur optimiste.
• Présentez les deux lectures : euros courants (montants bruts) et euros constants (pouvoir d'achat, inflation: 2).
• Stress-testez : un crash actions −35 % l'an 8 avec reprise « L » en 5 ans change souvent la conversation.
• Comparez à effort égal : même flux d'épargne, deux allocations, même seed.

Auto-hébergement

Patriboum est une application Nuxt auto-hébergeable ; le serveur MCP vit dans l'application.

• Endpoint local : http://localhost:3001/mcp (npm run dev)
• NUXT_PUBLIC_BASE_URL : URL publique des viewUrls
• PATRIMOINE_SESSIONS_DIR : dossier des sessions (défaut data/sessions/)
• Transport stateless : aucun handshake persistant, compatible Nitro et tous les clients MCP.

Avertissement

Patriboum est un outil de simulation à vocation pédagogique : il ne fournit pas de conseil en investissement personnalisé et ne tient pas lieu d'analyse personnalisée. Les projections reposent sur des hypothèses saisies par l'utilisateur (taux, fiscalité en vigueur, susceptibles d'évolution) et ne préjugent pas des performances futures. Investir comporte un risque de perte en capital et des risques de liquidité. L'output d'un agent IA branché sur Patriboum doit être vérifié par un professionnel avant toute décision. Voir les mentions légales.