# Documentation du serveur MCP Patriboum {#doc-mcp}

> 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](/installation))
- **Gratuit**, sans inscription. Voir l'[avertissement légal](/mentions-legales).

## Vue d'ensemble {#vue-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 {#demarrage}

### 1. Connecter l'agent {#demarrage-connecter}

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

### 2. Créer une session {#demarrage-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 {#demarrage-construire}

```
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 {#demarrage-simuler}

```
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 {#tools}

### Découverte {#tools-decouverte}

| Tool | Paramètres | Rôle |
|---|---|---|
| `list_node_types` | — | Catalogue : types de nœuds, paramètres (unités, défauts) et règles de connexion |
| `get_schema` | — | Même catalogue en JSON structuré (machine-readable) |
| `list_templates` | — | Flows d'exemple prêts à l'emploi |
| `info_node` | `type` | Fiche complète d'UN type : documentation produit (plafonds, fiscalité sourcée, positionnement conseil) + mécanique du simulateur (formules, pièges) |

### Sessions {#tools-sessions}

| Tool | Paramètres | Rôle |
|---|---|---|
| `create_session` | `name`, `template?` | Crée un patrimoine → `{sessionId, viewUrl}` |
| `list_sessions` | — | Sessions existantes, plus récentes d'abord |
| `get_session` | `sessionId` | Flow complet + dernière simulation + viewUrl |
| `get_node` | `sessionId`, `node` | Fiche d'un nœud : paramètres résolus, méta, connexions, série annuelle |

### Construction {#tools-construction}

| Tool | Paramètres | Rôle |
|---|---|---|
| `add_node` | `sessionId`, `type`, `label?`, `params?`, `meta?`, `position?` | Ajoute un nœud avec les défauts de l'UI |
| `update_node` | `sessionId`, `nodeId`, `label?`, `params?`, `meta?` | Modifie un nœud (fusion des paramètres, `meta` fusionné en profondeur) |
| `remove_node` | `sessionId`, `nodeId` | Supprime un nœud et ses connexions |
| `connect` | `sessionId`, `source`, `target`, `percentage?` | Connecte source → target (règles validées ; `percentage` pour un dispatcher) |
| `disconnect` | `sessionId`, `source`, `target` | Supprime une connexion |
| `set_flow` | `sessionId`, `nodes`, `edges` | Remplace tout le flow (équivalent import JSON) |

### Simulation & analyse {#tools-simulation}

| Tool | Paramètres | Rôle |
|---|---|---|
| `run_simulation` | `sessionId`, `years?` (défaut 10), `crashes?` | Déterministe : applique les taux configurés chaque année, retourne le résumé (capital, performance, dividendes, impôts) |
| `run_monte_carlo` | `sessionId`, `years?`, `runs?` (défaut 3000, max 10000), `distribution?`, `seed?`, `crashes?` | Stochastique : médiane par année + fourchettes p10/p25/p75/p90 + distribution finale + taux de réussite |
| `get_simulation_years` | `sessionId`, `years?`, `byAccount?`, `accounts?`, `mode?`, `inflation?` | Détail année par année : capital brut/net, revenus, impôts, frais, encaissé, impôt latent |
| `get_net_worth` | `sessionId`, `spending?`, `inflation?` | Patrimoine net consolidé ; avec `spending`, courbe du revenu requis (barista) et année d'autonomie passive |
| `get_portfolio_allocation` | `sessionId`, `year?` | Répartition par classe d'actifs (immobilier/actions/crypto/épargne) |
| `get_liquidity` | `sessionId`, `year?`, `monthlySpending?` | Répartition liquide/semi-liquide/illiquide ; avec `monthlySpending`, mois d'autonomie |

### Optimisation {#tools-optimisation}

| Tool | Paramètres | Rôle |
|---|---|---|
| `optimize_allocation` | `sessionId`, `years?` (défaut 25) | Recuit simulé : répartit le montant des DCA entre les comptes pour maximiser le capital final |
| `optimize_graph` | `sessionId`, `iterations?`, `years?` | ⚠️ Expérimental : exploration MCTS de variations du graphe |

### Paramètres transverses {#tools-transverse}

**`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 {#noeuds}

### Comptes d'investissement {#noeuds-investissement}

| Type | Description | Points clés |
|---|---|---|
| `pea` | Plan d'Épargne en Actions | Plafond 150 000 € de versements ; PFU 30,1 % avant 5 ans, exonération d'IR après ; débord possible vers CTO/PEA-PME |
| `peaPme` | PEA-PME | Plafond 225 000 € partagé avec le PEA (75 000 € dédiés PME) |
| `cto` | Compte-titres ordinaire | Pas de plafond, PFU 30,1 % sur les plus-values |
| `av` | Assurance-vie | Seuil 150 000 € de primes, abattement annuel 4 600/9 200 €, PFU 7,3/12,8 % + PS ; fiscalité du rachat avec prorata des gains |
| `per` | Plan d'Épargne Retraite | Déduction à l'entrée (10 % du revenu, plafonné ~8×PASS), capital bloqué jusqu'à la retraite, sortie rente ou capital |
| `scpi` | SCPI | Rendement + revalorisation, `frenchShare` (fiscalité française proportionnelle), démembrement NP/UF possible |
| `realEstate` | Immobilier locatif | Loyers indexés, plus-value immobilière (abattements 6–30 ans + surtaxe 50–250 k€), fiscalité au taux marginal |
| `residence` | Résidence principale / secondaire | Exonération de plus-value pour la résidence principale ; anti-double-comptage des flux |
| `crypto` | Actifs numériques | PFU 30 % (12,8 % + PS) |
| `compteTerm` | Compte à terme | Taux fixe contractuel, fiscalité PFU |

### Comptes d'épargne réglementée {#noeuds-epargne}

| Type | Description | Points clés |
|---|---|---|
| `livretA` | Livret A | Taux réglementé net d'impôt, plafond 22 950 € |
| `ldds` | Livret de Développement Durable et Solidaire | Taux réglementé, plafond 12 000 € |
| `lep` | Livret d'Épargne Populaire | Taux réglementé majoré, sous condition de revenus |
| `pel` | Plan d'Épargne Logement | Taux garanti ; PEL ouverts depuis 2018 : PFU annuel (pas d'exonération après 12 ans) |
| `currentAccount` | Compte courant | Trésorerie, aucun rendement |

### Stratégies {#noeuds-strategies}

| Type | Description | Paramètres clés |
|---|---|---|
| `dca` | Versements programmés | `money` (€/an), `start`, `end` |
| `lumpsum` | Versement unique | `money`, `start` |
| `loan` | Emprunt (injecte le capital) | `money`, `rate`, `duration`, `loanType` (`amortissable`/`inFine`/`capitalConstant`) |
| `withdrawal` | Retraits programmés | `money` (€/an), `start`, `end` |

### Aiguillage, détenteurs, événements {#noeuds-autres}

| Type | Description |
|---|---|
| `dispatcher` | Répartit un flux entre plusieurs comptes (`percentage` sur chaque connexion, somme = 100 %) |
| `holder` | Détenteur : taux moyen d'imposition, TMI, parts fiscales ; porte la fiscalité des comptes connectés |
| `close` | Vente/liquidation d'un compte à une année donnée (déclenche la fiscalité de sortie) |
| `lock` | Gel des versements à partir d'une année (ex. primes AV figées) |
| `scenario` | **Sortie obligatoire** du graphe : agrège le patrimoine d'un scénario |
| `all` | Branchement pratique : compte connecté à tous les scénarios |

## Règles de connexion {#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 {#prets}

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`) {#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 :

```json
{
  "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 » {#exemple}

```
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 {#bonnes-pratiques}

- **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 {#selfhost}

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 {#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](/mentions-legales).