{
  "markdown": "# Serveur MCP - Aides sociales françaises\n\n[![audescs-spec/mcp-aides-sociales MCP server](https://glama.ai/mcp/servers/audescs-spec/mcp-aides-sociales/badges/score.svg)](https://glama.ai/mcp/servers/audescs-spec/mcp-aides-sociales)\n[![AllMCPs Verified](https://allmcps.com/api/badge/aides-sociales-francaises)](https://allmcps.com/mcp/aides-sociales-francaises?verify=1a9248c2-44e0-4bb7-9063-c725047e0c0a)\n[![smithery badge](https://smithery.ai/badge/aude-scs/mcp-aides-sociales)](https://smithery.ai/servers/aude-scs/mcp-aides-sociales)\n[![MCP Badge](https://lobehub.com/badge/mcp/audescs-spec-mcp-aides-sociales)](https://lobehub.com/mcp/audescs-spec-mcp-aides-sociales)\n\nCe service est une **API/MCP pensée pour les développeurs et les agents\nIA qui l'intègrent** dans leurs propres logiciels — pas un simulateur\ngrand public à usage isolé. Elle calcule le **RSA**, la **prime\nd'activité** et l'**aide au logement (APL/ALS/ALF)** pour un foyer\nfrançais, à partir de quelques informations simples : salaire, loyer,\nstatut du logement, nombre d'enfants, situation de couple.\n\nLe calcul est fait **entièrement en local**, avec la bibliothèque open\nsource [openfisca-france](https://github.com/openfisca/openfisca-france)\n(le moteur officiel des barèmes sociaux français). Aucun appel n'est fait\nà l'API publique `api.fr.openfisca.org` ni à un autre service externe.\n\n⚠️ **Important : ce sont des estimations, pas des décisions officielles.**\nLe calcul repose sur des hypothèses simplificatrices (âge des adultes\nsupposé, situation stable sur les derniers mois, etc.). Seule la CAF ou\nla MSA peut donner un montant définitif et exact.\n\n## Crédits\n\nCalculs effectués avec [OpenFisca](https://www.openfisca.fr/), moteur\nsocio-fiscal libre et open source sous licence AGPL-3.0. Code source :\n[github.com/openfisca/openfisca-france](https://github.com/openfisca/openfisca-france).\n\n## Adresse du serveur et accès\n\n```\nhttps://mcp-aides-sociales.onrender.com/mcp\n```\n\nCe service est protégé par une **clé d'accès (API key)** : chaque appel\ndoit la fournir, sinon le serveur refuse de répondre. Deux paliers,\n100% self-service (aucune validation manuelle) :\n\n| Palier | Quota | Prix | Obtenir une clé |\n|---|---|---|---|\n| **Free** | 50 requêtes/mois | 0 € (sans carte bancaire) | `POST /signup-free` avec `{\"email\": \"...\"}` |\n| **Standard** | Illimité | 29 €/mois | [buy.stripe.com/9B628q5Pb7t9a0QdurgEg01](https://buy.stripe.com/9B628q5Pb7t9a0QdurgEg01) |\n\n**Palier Free** — inscription immédiate, sans carte bancaire :\n\n```bash\ncurl -X POST https://mcp-aides-sociales.onrender.com/signup-free \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"vous@example.com\"}'\n```\n\nUne clé (préfixe `free_...`) est envoyée par email. Le quota (50\nrequêtes/mois) se réinitialise automatiquement au début de chaque mois.\nAu-delà, le serveur répond `402 Payment Required` avec un message\ninvitant à passer au palier Standard — jamais une simple erreur sèche.\n\n**Palier Standard** — après paiement de l'abonnement, une clé d'accès\npersonnelle (illimitée) est envoyée automatiquement par email, et\nrenouvelée à chaque paiement mensuel réussi.\n\n## Installer dans Claude Desktop\n\n1. Ouvrez le fichier de configuration de Claude Desktop :\n   - Sur Mac : `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Sur Windows : `%APPDATA%\\Claude\\claude_desktop_config.json`\n2. Ajoutez (ou complétez) la section `mcpServers` ainsi :\n\n```json\n{\n  \"mcpServers\": {\n    \"aides-sociales-france\": {\n      \"url\": \"https://mcp-aides-sociales.onrender.com/mcp\",\n      \"headers\": {\n        \"X-API-Key\": \"VOTRE_CLE_API\"\n      }\n    }\n  }\n}\n```\n\n3. Remplacez `VOTRE_CLE_API` par la clé qui vous a été transmise.\n4. Redémarrez Claude Desktop.\n\n## Installer dans Cursor\n\n1. Ouvrez les réglages MCP de Cursor (Settings → MCP → Add new MCP server,\n   ou le fichier `~/.cursor/mcp.json`).\n2. Ajoutez la même configuration que ci-dessus :\n\n```json\n{\n  \"mcpServers\": {\n    \"aides-sociales-france\": {\n      \"url\": \"https://mcp-aides-sociales.onrender.com/mcp\",\n      \"headers\": {\n        \"X-API-Key\": \"VOTRE_CLE_API\"\n      }\n    }\n  }\n}\n```\n\n3. Remplacez `VOTRE_CLE_API` par votre clé, puis rechargez Cursor.\n\n## Exemple de question à poser une fois connecté\n\n> « J'habite seul(e) à Paris, je gagne 900 euros nets par mois (environ\n> 1150 euros bruts), je paie 500 euros de loyer et je n'ai pas d'enfant.\n> Est-ce que j'ai droit au RSA, à la prime d'activité, et à l'APL, et\n> pour quel montant ? »\n\nL'assistant utilisera automatiquement les outils `calculer_aides_sociales`\net `calculer_apl` et répondra avec les montants mensuels estimés.\n\n## Note technique : premier appel parfois lent\n\nLe serveur est hébergé sur un plan gratuit. S'il n'a pas été utilisé\ndepuis un moment, il peut mettre 30 à 60 secondes à répondre à la toute\npremière question (le temps de \"se réveiller\"). Les questions suivantes\nsont ensuite rapides.\n\n## Les outils exposés\n\n### `calculer_aides_sociales` (RSA + prime d'activité)\n\nParamètres :\n\n- `salaire_net_mensuel` (nombre) : salaire net mensuel du demandeur, en euros.\n- `loyer_mensuel` (nombre) : loyer mensuel du foyer, en euros.\n- `statut_occupation_logement` (texte) : un parmi `proprietaire`,\n  `primo_accedant`, `locataire_hlm`, `locataire_vide`, `locataire_meuble`,\n  `loge_gratuitement`, `locataire_foyer`, `sans_domicile`.\n- `nombre_enfants` (entier) : nombre d'enfants à charge.\n- `en_couple` (vrai/faux).\n- `salaire_net_mensuel_conjoint` (nombre, optionnel) : à fournir si `en_couple` est vrai.\n- `code_insee_commune` (texte, optionnel) : code INSEE (depcom) de la\n  commune, 5 caractères (ex: `75056` pour Paris). Affine une vérification\n  interne au calcul du forfait logement du RSA (zone APL). En son\n  absence, la zone 2 est utilisée par défaut pour cette vérification\n  uniquement — cela ne change généralement pas le RSA/la prime\n  d'activité renvoyés (voir *Le forfait logement du RSA* ci-dessous).\n\nRetourne le mois de calcul, le RSA mensuel estimé, la prime d'activité\nmensuelle estimée, et les hypothèses retenues pour le calcul.\n\n### `calculer_apl` (aide au logement : APL, ALS ou ALF selon éligibilité)\n\nParamètres :\n\n- `salaire_brut_mensuel` (nombre) : salaire **brut** mensuel du demandeur\n  (avant cotisations, en haut du bulletin de paie) — **pas** le salaire\n  net utilisé par `calculer_aides_sociales`. Nécessaire pour qu'openfisca-france\n  recalcule correctement, via son propre moteur de paie, le revenu\n  imposable utilisé dans la base ressources \"temps réel\" de l'aide au\n  logement (réforme 2021).\n- `loyer_mensuel` (nombre) : loyer réellement payé, hors charges. En cas\n  de colocation, indiquer uniquement la part personnelle.\n- `code_insee_commune` (texte, **obligatoire pour cet outil**) : code\n  INSEE de la commune, 5 caractères — pas le code postal. La zone APL en\n  est déduite automatiquement (fichier de zonage embarqué dans\n  openfisca-france, 37 000+ communes, aucun appel réseau). Un code\n  inconnu est rejeté explicitement plutôt que de retomber sur une zone\n  par défaut.\n- `statut_occupation_logement` (texte) : `proprietaire`, `locataire_hlm`,\n  `locataire_vide`, `locataire_meuble`, `loge_gratuitement`,\n  `sans_domicile` sont calculés (les 3 derniers donnent légitimement\n  0 €, non-éligibilité réelle). `primo_accedant` et `locataire_foyer`\n  sont **hors périmètre** : l'outil renvoie une erreur explicite plutôt\n  qu'un montant approximatif (voir *Ce que `calculer_apl` ne couvre\n  pas*).\n- `nombre_enfants`, `en_couple`, `salaire_brut_mensuel_conjoint` :\n  identiques en principe à `calculer_aides_sociales` (mais en brut).\n- `en_colocation` (vrai/faux, optionnel, défaut faux) : applique le\n  plafond de loyer réduit prévu pour les colocataires.\n\nRetourne le mois de calcul, l'aide au logement mensuelle estimée, le\ndispositif applicable (APL, ALS ou ALF), les hypothèses de calcul, et un\ndescriptif explicite de ce que le calcul couvre ou non.\n\n#### Ce que `calculer_apl` ne couvre pas\n\n- **Accession à la propriété avec prêt en cours** (`primo_accedant`) :\n  dépend de la date exacte du prêt, non collectée ici, et n'est presque\n  plus ouvert aux nouveaux prêts depuis 2018.\n- **Logement-foyer / résidence universitaire ou CROUS**\n  (`locataire_foyer`) : openfisca-france marque lui-même ce statut\n  \"non calculable\" par la formule standard.\n- **Revenus non salariés** : indépendants, chômage indemnisé, retraite,\n  pension d'invalidité, revenus du patrimoine ne sont pas modélisés —\n  seul un revenu salarié stable est pris en compte.\n- Personnes âgées/handicapées hébergées à titre onéreux, chambres\n  meublées spécifiquement.\n\n### Le forfait logement du RSA (pourquoi RSA et APL s'additionnent)\n\nLe RSA renvoyé par `calculer_aides_sociales` intègre déjà un **forfait\nlogement** : une déduction forfaitaire **fixe**, prévue par la loi\n(environ 12 % du montant de base du RSA pour une personne seule),\nappliquée dès que le foyer est logé (loyer payé, logé gratuitement, ou\npropriétaire). **Ce n'est pas une estimation du montant réel d'aide au\nlogement** — c'est un taux légal indépendant, donc le RSA renvoyé ici et\nle montant renvoyé par `calculer_apl` peuvent bien être additionnés :\nun allocataire perçoit réellement le RSA (déjà minoré de ce forfait\nfixe) **plus** son APL/ALS/ALF entière.\n\n## Faire tourner ce serveur soi-même (en local)\n\n```\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nAPI_KEY=une-cle-secrete-a-vous python src/server.py\n```\n\nLe serveur écoute en HTTP sur le port défini par la variable\nd'environnement `PORT` (8000 par défaut), sur le chemin `/mcp`.\n\n## Comment fonctionne la clé d'accès\n\nLe serveur ne stocke jamais la clé en clair : le code contient uniquement\nson **empreinte SHA-256** (un hachage à sens unique, impossible à inverser).\nUne clé fournie par un client n'est acceptée que si son empreinte\ncorrespond. Cela permet au service de fonctionner \"prêt à l'emploi\" sans\nconfigurer de variable d'environnement chez l'hébergeur (utile quand,\ncomme sur Render en mode \"Blueprint managed\", il n'est pas toujours\npossible d'ajouter une variable depuis le tableau de bord).\n\nPour remplacer la clé sans changer le code (par exemple en local, ou chez\nun hébergeur qui permet les variables d'environnement) :\n\n- `API_KEY=votre-cle python src/server.py` (la clé en clair est hachée au démarrage), ou\n- `API_KEY_SHA256=votre-empreinte python src/server.py` (empreinte déjà calculée).\n\nPour changer définitivement la clé par défaut : calculez l'empreinte\nSHA-256 de la nouvelle clé et remplacez la constante\n`_EMPREINTE_CLE_API_PAR_DEFAUT` dans `src/server.py`.\n\n## Protections en place\n\n- **Clé d'accès obligatoire** (voir ci-dessus) sur tous les appels de calcul.\n- **Validation stricte des données reçues** (montants, nombre d'enfants,\n  types) : toute requête malformée ou avec des valeurs absurdes est\n  rejetée proprement, sans jamais faire planter le serveur.\n- **Limitation du nombre de requêtes par adresse IP** (au-delà d'un\n  certain nombre d'appels par minute, le serveur répond \"trop de\n  requêtes\" au lieu de traiter la demande), pour éviter qu'un usage\n  répété abusif ne surcharge ce service hébergé sur un plan gratuit.\n\n## Déploiement\n\n- `render.yaml` : configuration prête pour un déploiement sur\n  [Render.com](https://render.com) (type \"Blueprint\").\n- `nixpacks.toml` / `Procfile` : configuration prête pour\n  [Railway.app](https://railway.app).\n\n## Paiement Stripe et envoi automatique de la clé (pour les mainteneurs)\n\nLe service peut être vendu via un Stripe Payment Link. Un webhook\n(`POST /webhook/stripe`, non protégé par la clé d'accès) écoute\ndeux événements :\n\n- `checkout.session.completed` (mode paiement unique uniquement) : cas\n  historique de l'ancien Payment Link one_time, aujourd'hui désactivé.\n  Génère une clé d'accès **à vie**, dérivée par HMAC-SHA256 de\n  l'identifiant de session Stripe et d'un secret serveur.\n- `invoice.paid` (abonnement mensuel, cas actuel) : à chaque paiement\n  d'abonnement réussi (initial ou renouvellement), génère une clé\n  dérivée de l'identifiant d'abonnement Stripe et **expirant à la fin de\n  la période facturée** (+ 3 jours de marge). Si l'abonnement est annulé\n  ou qu'un paiement échoue, la dernière clé envoyée cesse simplement de\n  fonctionner à son expiration — pas besoin de liste de révocation.\n\nDans les deux cas, aucune base de données : la clé se vérifie par\nrecalcul de sa signature HMAC, pas par recherche dans un stockage (le\ndisque gratuit de Render n'est pas persistant entre redémarrages).\nL'envoi se fait par email via [Resend](https://resend.com).\n\nVariables d'environnement à définir côté hébergeur (en plus de\n`API_KEY` / `API_KEY_SHA256`, voir plus haut) :\n\n- `STRIPE_WEBHOOK_SECRET` : secret de signature du endpoint webhook\n  (`whsec_...`), fourni par Stripe à la création du webhook.\n- `API_KEY_PEPPER` : secret aléatoire propre au serveur, utilisé pour\n  dériver et vérifier les clés générées par client. À générer une seule\n  fois et ne jamais changer (sinon les clés déjà envoyées deviennent\n  invalides).\n- `RESEND_API_KEY` : clé API [Resend](https://resend.com) utilisée pour\n  l'envoi des emails.\n- `RESEND_FROM_EMAIL` (optionnel) : adresse d'expédition. Par défaut\n  `onboarding@resend.dev`, qui **ne peut envoyer qu'à l'adresse du\n  compte Resend lui-même** tant qu'aucun domaine n'est vérifié. En\n  production, utilise une adresse sur un domaine vérifié (ex:\n  `hello@kapsik.com`, vérifié DKIM/SPF/MX sur Resend).\n\nFilet de sécurité : chaque clé générée est aussi journalisée dans les\nlogs du serveur (`[paiement] nouvelle cle generee ...`), pour pouvoir la\nretrouver et la renvoyer manuellement si l'email échoue.\n\n## Palier gratuit (pour les mainteneurs)\n\n`POST /signup-free` (public, non protégé par la clé d'accès) génère une\nclé du palier gratuit (préfixe `free_...`, HMAC-SHA256 comme les autres\nclés — l'authenticité de la clé se vérifie donc toujours sans base de\ndonnées) et l'envoie par email. Aucune vérification d'email : décision\nassumée tant que le quota bas (50/mois) rend l'abus sans intérêt réel\n(l'alternative gratuite officielle — CAF, 1jeune1solution — existe de\ntoute façon) ; à reconsidérer seulement si un abus réel est constaté.\n\nContrairement aux clés payantes, une clé gratuite a besoin d'un **suivi\nd'usage dans le temps** (nombre de requêtes ce mois-ci) pour appliquer le\nquota — chose qu'une simple signature HMAC ne peut pas faire seule. Seul\nce compteur utilise un stockage externe : [Upstash Redis](https://upstash.com)\n(palier gratuit, aucune carte requise), interrogé en HTTP simple (`INCR`\nsur la clé `usage:{mois}:{cle}`, expiration de nettoyage à ~40 jours).\nLe mois fait partie du nom de la clé Redis, donc le quota repart\nnaturellement à zéro chaque mois, sans logique de reset à écrire.\n\nVariables d'environnement supplémentaires :\n\n- `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` : identifiants\n  REST de la base Upstash Redis (palier gratuit du service). Sans ces\n  variables, toute requête avec une clé `free_...` échoue explicitement\n  (503 \"service de quota indisponible\") plutôt que d'être acceptée par\n  défaut ou de planter — le mécanisme de clé HMAC des paliers payants\n  n'en dépend pas et continue de fonctionner normalement.\n",
  "bytes": 15212,
  "sha": "f0091465453bc9a816b36e5bef5d1937912c3314b3919e53347f6e315053123d",
  "repo_slug": "audescs-spec/mcp-aides-sociales",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_audescs_spec_mcp_aides_sociale_6d058cde/readme"
}