API V1 Public + preparation serveur MCP
This commit is contained in:
@@ -0,0 +1,181 @@
|
||||
# crowdlending-mcp-server
|
||||
|
||||
Serveur MCP local (stdio) pour le portefeuille de crowdlending. Il expose en
|
||||
lecture seule les données d'un investisseur (investissements, remboursements,
|
||||
dépôts/retraits, dashboard) à un client MCP — Claude Desktop, Claude Code,
|
||||
ou tout autre client compatible — en s'appuyant sur l'API publique `/api/v1`
|
||||
du backend.
|
||||
|
||||
Il ne fait aucune écriture : toutes les modifications restent à faire dans
|
||||
l'app web.
|
||||
|
||||
## Prérequis
|
||||
|
||||
- Node.js ≥ 18 (fetch natif requis)
|
||||
- Une clé API générée dans l'app : **Mon compte → Clés API → Nouvelle clé**
|
||||
- Le backend accessible (en local `http://localhost:4000`, ou l'URL de votre
|
||||
instance en production)
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
cd mcp-server
|
||||
npm install
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Trois variables d'environnement :
|
||||
|
||||
| Variable | Obligatoire | Défaut | Exemple |
|
||||
|---|---|---|---|
|
||||
| `CROWDLENDING_API_KEY` | oui | — | `clk_live_...` |
|
||||
| `CROWDLENDING_API_URL` | non | `http://localhost:4000/api/v1` | `https://mon-domaine.fr/api/v1` |
|
||||
| `CROWDLENDING_LABEL` | non | — | `dev`, `prod` |
|
||||
|
||||
`CROWDLENDING_LABEL` sert uniquement à distinguer plusieurs instances
|
||||
connectées en même temps (voir [Faire tourner dev et prod en même
|
||||
temps](#faire-tourner-dev-et-prod-en-même-temps)) : il apparaît dans le nom
|
||||
du serveur, dans le titre de chaque outil (`[DEV]` / `[PROD]`) et dans la
|
||||
description (avec l'URL API ciblée), pour que l'agent — et vous — sachiez
|
||||
toujours quel environnement est interrogé.
|
||||
|
||||
## Utiliser avec Claude Desktop
|
||||
|
||||
Localisez le fichier de config Claude Desktop — le chemin diffère selon la
|
||||
provenance de l'installation Windows :
|
||||
|
||||
- **Installeur classique** (téléchargé depuis claude.ai) :
|
||||
`%APPDATA%\Claude\claude_desktop_config.json`
|
||||
- **Microsoft Store** : Windows redirige `%APPDATA%` vers un dossier virtualisé
|
||||
propre à l'app —
|
||||
`%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json`
|
||||
(le `<id>` est un identifiant généré, propre à votre installation).
|
||||
|
||||
Le plus fiable dans les deux cas : Réglages → Développeur → Serveurs MCP
|
||||
locaux → **Modifier la config**, qui ouvre directement le bon fichier quelle
|
||||
que soit la provenance de l'installation.
|
||||
|
||||
Ajoutez une entrée dans `mcpServers` :
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"crowdlending": {
|
||||
"command": "node",
|
||||
"args": ["C:\\dev\\crowdlending-app\\mcp-server\\index.js"],
|
||||
"env": {
|
||||
"CROWDLENDING_API_KEY": "clk_live_...",
|
||||
"CROWDLENDING_API_URL": "http://localhost:4000/api/v1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Redémarrez Claude Desktop. L'icône 🔌 (ou le menu des outils MCP) doit
|
||||
afficher les 7 outils `crowdlending_*` ci-dessous.
|
||||
|
||||
Pour pointer vers votre instance de production plutôt que le backend local,
|
||||
changez uniquement `CROWDLENDING_API_URL` (et utilisez une clé API générée
|
||||
sur cette instance).
|
||||
|
||||
## Faire tourner dev et prod en même temps
|
||||
|
||||
Claude Desktop peut se connecter à plusieurs serveurs MCP simultanément : il
|
||||
suffit de déclarer deux entrées avec des clés distinctes dans `mcpServers`.
|
||||
Chaque outil est alors automatiquement rattaché à son serveur d'origine —
|
||||
pas de collision technique possible entre les deux, même si les noms
|
||||
d'outils (`crowdlending_get_dashboard`, etc.) sont identiques des deux côtés.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"crowdlending-dev": {
|
||||
"command": "node",
|
||||
"args": ["C:\\dev\\crowdlending-app\\mcp-server\\index.js"],
|
||||
"env": {
|
||||
"CROWDLENDING_API_KEY": "clk_live_...",
|
||||
"CROWDLENDING_API_URL": "http://localhost:4000/api/v1",
|
||||
"CROWDLENDING_LABEL": "dev"
|
||||
}
|
||||
},
|
||||
"crowdlending-prod": {
|
||||
"command": "node",
|
||||
"args": ["C:\\dev\\crowdlending-app\\mcp-server\\index.js"],
|
||||
"env": {
|
||||
"CROWDLENDING_API_KEY": "clk_live_...",
|
||||
"CROWDLENDING_API_URL": "https://mon-domaine.fr/api/v1",
|
||||
"CROWDLENDING_LABEL": "prod"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez deux clés API différentes (une par instance, générées séparément
|
||||
sur chaque backend) : ça permet de révoquer l'une sans affecter l'autre, et
|
||||
c'est cohérent avec le principe d'une clé par usage.
|
||||
|
||||
Avec `CROWDLENDING_LABEL` renseigné, chaque outil affiche son environnement
|
||||
dans son titre (ex. « Synthèse du portefeuille [PROD] ») et sa description
|
||||
se termine par la source exacte interrogée — de quoi lever toute ambiguïté
|
||||
si vous demandez « mon encours en prod » vs « mon encours en dev ».
|
||||
|
||||
## Tester sans Claude Desktop
|
||||
|
||||
Le [MCP Inspector](https://github.com/modelcontextprotocol/inspector) permet
|
||||
de lister et appeler les outils depuis une interface web, sans configurer de
|
||||
client :
|
||||
|
||||
```
|
||||
CROWDLENDING_API_KEY=clk_live_... npm run inspect
|
||||
```
|
||||
|
||||
## Outils exposés
|
||||
|
||||
Tous en lecture seule (`readOnlyHint: true`) :
|
||||
|
||||
| Outil | Description |
|
||||
|---|---|
|
||||
| `crowdlending_get_investisseur` | Profil de l'investisseur lié à la clé |
|
||||
| `crowdlending_get_dashboard` | Synthèse KPI : capital investi, capital en risque, intérêts perçus (filtrable par année), cash |
|
||||
| `crowdlending_list_investissements` | Liste des investissements, filtrable par statut |
|
||||
| `crowdlending_get_investissement` | Détail d'un investissement + ses remboursements |
|
||||
| `crowdlending_list_remboursements` | Historique des remboursements, filtrable par période |
|
||||
| `crowdlending_list_depots_retraits` | Historique des mouvements de cash |
|
||||
| `crowdlending_fetch_url` | Lit une page web (annonce de projet) et en extrait le texte propre — voir ci-dessous |
|
||||
|
||||
## Lire une annonce de projet (`crowdlending_fetch_url`)
|
||||
|
||||
Cet outil récupère une page web et en extrait le contenu lisible (titre +
|
||||
texte principal) via [Readability](https://github.com/mozilla/readability),
|
||||
la librairie du mode lecture de Firefox — menus, pubs, scripts et bandeaux
|
||||
cookies sont éliminés automatiquement.
|
||||
|
||||
Il ne fait **aucune extraction métier** côté serveur (pas de tentative de
|
||||
deviner taux/montant/durée par regex) : c'est l'agent qui lit le texte
|
||||
retourné et en extrait les informations pertinentes dans la conversation,
|
||||
pour vous les proposer avant toute saisie. Cohérent avec le reste du
|
||||
serveur : lecture seule, aucune création automatique d'investissement (l'API
|
||||
v1 n'a pas de capacité d'écriture).
|
||||
|
||||
Exemple d'usage : *« Regarde cette page et propose-moi les infos pour créer
|
||||
l'investissement : https://plateforme.fr/projets/xxx »*.
|
||||
|
||||
Garde-fous :
|
||||
- http/https uniquement, pages HTML uniquement.
|
||||
- Hôtes locaux/privés bloqués (`localhost`, `127.0.0.1`, plages `10.x`/`172.16-31.x`/`192.168.x`...) —
|
||||
l'outil ne peut pas cibler votre réseau local, y compris votre propre backend.
|
||||
- Texte tronqué à 8000 caractères sur les pages très longues (le champ
|
||||
`truncated` de la réponse l'indique).
|
||||
|
||||
## Dépannage
|
||||
|
||||
- **`ERREUR : CROWDLENDING_API_KEY est requise`** — la variable d'env n'est
|
||||
pas transmise. Vérifiez la section `env` de votre config MCP.
|
||||
- **`Clé API invalide ou révoquée`** — régénérez une clé dans Mon compte →
|
||||
Clés API et mettez à jour la config.
|
||||
- **`Impossible de joindre l'API`** — le backend n'est pas démarré, ou
|
||||
`CROWDLENDING_API_URL` pointe au mauvais endroit (vérifiez le port et le
|
||||
suffixe `/api/v1`).
|
||||
Reference in New Issue
Block a user