crowdlending-app/mcp-server

crowdlending-mcp-server

Serveur MCP 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.

Deux modes, deux fichiers :

• Local (index.js, stdio) — lancé comme process enfant par Claude Desktop sur votre propre machine. Nécessite Node.js et ce dépôt cloné en local. Inclut l'outil crowdlending_fetch_url (lecture de page web).
• Distant (http-server.js, HTTP) — un service déployé une fois (par l'administrateur de l'instance) sur mcp.crowdlending.croguennec.net, accessible à n'importe quel utilisateur distant sans rien installer : juste une URL + sa clé API personnelle à coller dans son client MCP. N'inclut PAS crowdlending_fetch_url (voir plus bas).

Les deux partagent le même code pour les 6 outils de lecture de données (tools.js) — leur comportement ne peut donc pas diverger entre les deux modes.

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) : 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 :

{
  "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.

{
  "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 ».

Serveur distant — pour les utilisateurs sans installation locale

Si vous n'êtes pas sur la machine qui héberge ce dépôt (pas de Node.js, pas envie de cloner le repo), vous pouvez vous connecter directement au serveur MCP distant déployé sur https://mcp.crowdlending.croguennec.net — aucune installation nécessaire, juste votre clé API personnelle.

1. Créer votre clé API — dans l'app, Mon compte → Clés API → Nouvelle clé (elle ne sera affichée qu'une seule fois, copiez-la).

2. Ajouter le serveur dans Claude Desktop — Réglages → Développeur → Serveurs MCP locaux → Modifier la config, puis ajoutez :

{
  "mcpServers": {
    "crowdlending-distant": {
      "url": "https://mcp.crowdlending.croguennec.net/mcp",
      "headers": {
        "X-API-Key": "clk_live_..."
      }
    }
  }
}

3. Redémarrez Claude Desktop. Les 6 outils crowdlending_* doivent apparaître (sans crowdlending_fetch_url, réservé au serveur local).

Différences avec le serveur local

• Pas de crowdlending_fetch_url : lire une page web arbitraire pour un utilisateur tiers non maîtrisé augmenterait le risque SSRF sans bénéfice réel pour ce cas d'usage. Cet outil reste réservé au serveur local.
• Authentification par requête, pas par process : le serveur local a une clé API fixée une fois pour toutes via une variable d'environnement — un process = un utilisateur. Le serveur distant sert plusieurs utilisateurs en parallèle : chaque session est créée à partir de la clé API envoyée dans l'en-tête X-API-Key de la requête qui l'initialise, puis liée à cette session uniquement. Deux utilisateurs ne partagent jamais de données.
• Exposé publiquement, sans la liste blanche d'IP qui protège le reste de l'app (ipwhitelist-all) : la clé API est la seule barrière d'accès. Traitez-la comme un mot de passe — ne la partagez pas, révoquez-la immédiatement en cas de doute (Mon compte → Clés API).
• Limite de débit : 60 requêtes/minute par adresse IP, au-delà l'API répond 429.
• Sessions : une session inactive plus de 30 minutes est fermée côté serveur (mémoire uniquement, aucune persistance) ; votre client MCP en recréera une automatiquement à la prochaine requête.

Déploiement (administrateur de l'instance)

Le service crowdlending-mcp du docker-compose.yml construit et lance http-server.js, exposé via Traefik sur mcp.crowdlending.croguennec.net (certificat TLS automatique, même resolver que le reste de l'app). Un enregistrement DNS pour ce sous-domaine, pointant vers la même IP que crowdlending.croguennec.net, est nécessaire avant le premier déploiement. Variables d'environnement du service : CROWDLENDING_API_URL (URL interne du backend sur le réseau Docker, déjà configurée) et MCP_ALLOWED_HOSTS (validation de l'en-tête Host, protection anti DNS-rebinding — doit correspondre exactement au(x) nom(s) de domaine exposé(s)).

Tester sans Claude Desktop

Le MCP 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	(serveur local uniquement) 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, 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).