Aides sociales françaises

MCP 服务 - 法国社会福利

这是一项 API/MCP 服务，专为将其集成到自有软件中的开发者和 AI Agent 而设计，并非供大众单独使用的模拟器。它根据一些简单信息，为法国家庭计算 RSA、就业活动补助金和住房补助（APL/ALS/ALF）：工资、房租、住房状态、子女数量和伴侣关系状况。

计算完全在本地进行，使用开源库 openfisca-france（法国社会福利标准的官方计算引擎）。不会调用公共 API api.fr.openfisca.org 或其他外部服务。

⚠️ 重要：这些是估算值，并非官方决定。 计算基于简化假设（假定成年人年龄、近几个月的情况保持稳定等）。只有 CAF 或 MSA 才能给出最终且准确的金额。

致谢

计算使用 OpenFisca 完成，这是一个基于 AGPL-3.0 许可的自由开源社会税务引擎。源代码： github.com/openfisca/openfisca-france。

服务地址和访问方式

https://mcp-aides-sociales.onrender.com/mcp

此服务受**访问密钥（API key）**保护：每次调用都必须提供密钥，否则服务将拒绝响应。分为两个等级，均可 100% 自助办理（无需人工审核）：

等级	配额	价格	获取密钥
Free	每月 50 次请求	0 €（无需银行卡）	使用 {"email": "..."} 调用 POST /signup-free
Standard	不限量	29 €/月	buy.stripe.com/9B628q5Pb7t9a0QdurgEg01

Free 等级 — 即时注册，无需银行卡：

curl -X POST https://mcp-aides-sociales.onrender.com/signup-free \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

系统会通过电子邮件发送一个密钥（前缀为 free_...）。配额（每月 50 次请求）会在每月初自动重置。超出配额后，服务会返回 402 Payment Required，并提示升级到 Standard 等级，而不会只返回一条生硬的错误信息。

Standard 等级 — 订阅付款后，系统会自动通过电子邮件发送个人访问密钥（不限量），并在每次月度付款成功后续期。

在 Claude Desktop 中安装

1. 打开 Claude Desktop 的配置文件：
   • Mac：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加或补全 mcpServers 部分，如下所示：

{
  "mcpServers": {
    "aides-sociales-france": {
      "url": "https://mcp-aides-sociales.onrender.com/mcp",
      "headers": {
        "X-API-Key": "VOTRE_CLE_API"
      }
    }
  }
}

3. 将 VOTRE_CLE_API 替换为提供给您的密钥。
4. 重启 Claude Desktop。

在 Cursor 中安装

1. 打开 Cursor 的 MCP 设置（Settings → MCP → Add new MCP server， 或文件 ~/.cursor/mcp.json）。
2. 添加与上文相同的配置：

{
  "mcpServers": {
    "aides-sociales-france": {
      "url": "https://mcp-aides-sociales.onrender.com/mcp",
      "headers": {
        "X-API-Key": "VOTRE_CLE_API"
      }
    }
  }
}

3. 将 VOTRE_CLE_API 替换为您的密钥，然后重新加载 Cursor。

连接后可提问的示例

“我独自住在巴黎，每月税后收入为 900 欧元（税前约 1150 欧元），房租为 500 欧元，没有孩子。 我是否有资格领取 RSA、活动补贴和 APL？金额分别是多少？”

助手会自动使用 calculer_aides_sociales 和 calculer_apl 工具，并给出估算的月金额。

技术说明：首次调用有时较慢

服务托管在免费套餐上。如果一段时间未使用，首次提问可能需要 30 到 60 秒才会得到回复（这是服务“唤醒”所需的时间）。之后的问题响应会很快。

提供的工具

calculer_aides_sociales（RSA + 活动补贴）

参数：

• salaire_net_mensuel（数字）：申请人的月税后工资，单位为欧元。
• loyer_mensuel（数字）：家庭月租金，单位为欧元。
• statut_occupation_logement（文本）：以下值之一：proprietaire、 primo_accedant、locataire_hlm、locataire_vide、locataire_meuble、 loge_gratuitement、locataire_foyer、sans_domicile。
• nombre_enfants（整数）：受抚养子女数量。
• en_couple（是/否）。
• salaire_net_mensuel_conjoint（数字，可选）：若 en_couple 为真，则需提供。
• code_insee_commune（文本，可选）：市镇的 INSEE 代码（depcom），共 5 个字符（例如，巴黎为 75056）。可细化对 RSA 住房定额计算所做的内部核验（APL 区域）。如果未提供，该核验默认使用区域 2——这通常不会改变返回的 RSA/活动补贴金额（见下文 RSA 住房定额）。

返回计算月份、估算的月 RSA、估算的月活动补贴，以及计算所采用的假设。

calculer_apl（住房补助：根据资格发放 APL、ALS 或 ALF）

参数：

• salaire_brut_mensuel（数字）：申请人的月税前工资（扣缴前，即工资单顶部所列金额）——不是 calculer_aides_sociales 使用的税后工资。此参数为必填项，以便 openfisca-france 通过其自身的工资计算引擎，正确重新计算住房补助“实时”资源基数中使用的应税收入（2021 年改革）。
• loyer_mensuel（数字）：实际支付的租金，不含杂费。合租时，只填写个人承担的部分。
• code_insee_commune（文本，本工具必填）：市镇的 INSEE 代码，共 5 个字符——不是邮政编码。APL 区域会自动根据该代码确定（使用 openfisca-france 内置的分区文件，覆盖 37,000 多个市镇，无需联网调用）。若代码无效，会明确拒绝，而不会回退到默认区域。
• statut_occupation_logement（文本）：proprietaire、locataire_hlm、 locataire_vide、locataire_meuble、loge_gratuitement、 sans_domicile 均可计算（其中后三种情况会合理地返回 0 欧元，即实际不符合资格）。primo_accedant 和 locataire_foyer 不在支持范围内：工具会返回明确错误，而非近似金额（见 calculer_apl 不涵盖的情况）。
• nombre_enfants、en_couple、salaire_brut_mensuel_conjoint： 原则上与 calculer_aides_sociales 中的参数相同（但工资为税前）。
• en_colocation（是/否，可选，默认否）：应用面向合租者的较低租金上限。

返回计算月份、估算的月住房补助、适用的补助类型（APL、ALS 或 ALF）、计算假设，以及明确说明计算涵盖或未涵盖的内容。

calculer_apl 未涵盖的情况

• 正在偿还贷款的购房者（primo_accedant）： 取决于贷款的确切日期，而这里未收集该信息；自 2018 年以来， 几乎不再向新贷款开放。
• 福利住房／大学宿舍或 CROUS （locataire_foyer）：openfisca-france 本身就将此状态标记为 标准公式“无法计算”。
• 非工资收入：个体经营收入、失业救济、退休金、残疾抚恤金、 财产收入均未建模——这里只考虑稳定的工资收入。
• 付费寄宿的老年人／残障人士，以及特定的带家具房间。

RSA 的住房定额扣除（为什么 RSA 和 APL 可以相加）

calculer_aides_sociales 返回的 RSA 已包含住房定额扣除：法律 规定的一项固定定额扣除（约为单人 RSA 基本金额的 12%），只要 家庭有住所（支付房租、免费居住或拥有住房）就会适用。这并非对 实际住房补助金额的估算——这是独立的法定比例，因此这里返回的 RSA 和 calculer_apl 返回的金额可以相加：受益人实际领取的是 RSA （已扣除这笔固定定额）加上全额 APL/ALS/ALF。

在本地自行运行此服务

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
API_KEY=une-cle-secrete-a-vous python src/server.py

服务通过 HTTP 监听环境变量 PORT 指定的端口（默认为 8000）， 路径为 /mcp。

访问密钥的工作原理

服务从不以明文存储密钥：代码中仅包含其 SHA-256 指纹（一种 无法逆向还原的单向哈希）。只有当客户端提供的密钥指纹匹配时， 该密钥才会被接受。这样，服务无需在托管平台配置环境变量即可 “开箱即用”（例如使用 Render 的“Blueprint managed”模式时，可能 无法始终从控制面板添加变量）。

如需在不更改代码的情况下替换密钥（例如在本地，或在支持环境变量 的托管平台上）：

• API_KEY=votre-cle python src/server.py（明文密钥会在启动时进行哈希），或
• API_KEY_SHA256=votre-empreinte python src/server.py（已计算好的指纹）。

如需永久更改默认密钥：计算新密钥的 SHA-256 指纹，并替换 src/server.py 中的常量 _EMPREINTE_CLE_API_PAR_DEFAUT。

已实施的防护措施

• 必须提供访问密钥（见上文）才能调用所有计算接口。
• 严格验证收到的数据（金额、子女数量、类型）：格式错误或包含 不合理值的请求都会被妥善拒绝，绝不会导致服务崩溃。
• 限制每个 IP 地址的请求数量（每分钟的调用次数超过一定限额后， 服务会回复“请求过多”，而不是处理请求），避免滥用重复调用使这项 托管在免费套餐上的服务过载。

部署

• render.yaml：可直接用于部署到 Render.com 的配置（类型为“Blueprint”）。
• nixpacks.toml / Procfile：可直接用于部署到 Railway.app 的配置。

Stripe 付款并自动发送密钥（面向维护者）

可以通过 Stripe Payment Link 销售该服务。Webhook （POST /webhook/stripe，不受访问密钥保护）会监听 两个事件：

• checkout.session.completed（仅限一次性付款模式）：这是旧版 one_time Payment Link 的历史情况，目前已停用。 根据 Stripe 会话 ID 和服务器密钥，通过 HMAC-SHA256 生成永久有效的访问密钥。
• invoice.paid（月度订阅，目前的情况）：每次订阅付款成功时（首次付款或续订），都会生成一个 根据 Stripe 订阅 ID 派生的密钥，有效期截至已开票周期结束时 （另加 3 天宽限期）。如果订阅已取消或付款失败，最近发送的密钥只会在到期时停止 生效——无需撤销列表。

这两种情况都不使用数据库：通过重新计算密钥的 HMAC 签名来验证密钥， 而不是在存储中查找（Render 的免费磁盘在重启后不会保留数据）。 邮件通过 Resend 发送。

需在托管服务提供商一侧设置的环境变量（除 API_KEY / API_KEY_SHA256 外，参见上文）：

• STRIPE_WEBHOOK_SECRET：Webhook 端点的签名密钥 （whsec_...），创建 Webhook 时由 Stripe 提供。
• API_KEY_PEPPER：服务器专用的随机密钥，用于为每位客户派生和验证生成的密钥。只需生成 一次，且绝不能更改（否则已发送的密钥将失效）。
• RESEND_API_KEY：用于发送邮件的 Resend API 密钥。
• RESEND_FROM_EMAIL（可选）：发件地址。默认为 [email protected]；在验证域名之前，只能向 Resend 账户本身的邮箱地址发送邮件。在 生产环境中，请使用已验证域名下的地址（例如： [email protected]，已在 Resend 上验证 DKIM/SPF/MX）。

安全措施：每个生成的密钥也会记录在服务器日志中 （[paiement] nouvelle cle generee ...），以便在邮件发送失败时找到密钥并手动重新发送。

免费套餐（面向维护者）

POST /signup-free（公开，不受访问密钥保护）会生成一个 免费套餐密钥（前缀为 free_...，与其他密钥一样使用 HMAC-SHA256——因此始终可以在无需数据库的情况下 验证密钥的真实性），并通过邮件发送。无需验证邮箱：只要较低的配额（每月 50 次）让滥用几乎没有实际收益， 就维持这一决定（官方免费替代方案——CAF、1jeune1solution——无论如何都存在）；只有在发现实际滥用时 才重新考虑。

与付费密钥不同，免费密钥需要跟踪一段时间内的使用情况 （本月的请求数）才能执行配额——单靠简单的 HMAC 签名无法做到这一点。只有这个计数器使用外部存储： Upstash Redis （免费套餐，无需信用卡），通过简单的 HTTP 请求访问（对 usage:{mois}:{cle 执行 INCR，并在约 40 天后过期清理）。 月份包含在 Redis 密钥名称中，因此配额每月自然归零，无需编写 重置逻辑。

其他环境变量：

• UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN：Upstash Redis 数据库的 REST 凭据（该服务的免费套餐）。如果未设置这些变量，任何使用 free_... 密钥的请求都会明确失败 （503“配额服务不可用”），而不是默认接受请求或导致程序崩溃——付费套餐的 HMAC 密钥机制不依赖这些变量，仍可正常运行。