ayudas-es

ayudas-es-mcp

西班牙援助与补贴 MCP 服务使用指南。

可让 AI 查询两个官方数据源，无需密钥或抓取数据：

• BDNS (infosubvenciones.es)： 所有行政机构发布的援助与补贴公告，包括国家、自治区、省级政府和市政府。
• BOE（开放数据）： 法规、公务员考试和招标。

查询实时进行。无需下载或同步任何数据库： 安装后即可运行。

提供的功能

在 BDNS API 的基础上，该服务还提供：

• 精确计数，而非根据样本估算。
• 根据每条公告的文本计算申请期限。
• 区分确实可以申请的援助。
• 阅读 PDF 中的条款，并标注每条引文所在的页码。
• 预测每年重复发布的公告日程。
• 遇到不确定的信息时明确提示，而非保持沉默。

1. 要求

• Node.js 22.13 或更高版本。
• 兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor 或其他客户端）。

无需安装其他内容，也无需配置密钥。

2. 安装

Claude Code

claude mcp add ayudas -- npx -y ayudas-es-mcp

Claude Desktop、Cursor 和其他客户端

将此代码块添加到客户端的 MCP 配置中，然后重启客户端：

{
  "mcpServers": {
    "ayudas": {
      "command": "npx",
      "args": ["-y", "ayudas-es-mcp"]
    }
  }
}

3. 检查是否正常运行

在终端中：

npx ayudas-es-mcp --version

在客户端中提问，例如：“加利西亚有哪些面向个体经营者的开放数字化援助？”如果服务已启动，AI 将使用 ayudas_* 工具。

4. 可以询问什么

• “未来两个月，巴斯克地区通常会有哪些面向中小企业的援助？”
• “有没有每年这个时候都会发布、但今年还没发布的援助？”
• “今年哪个自治区发布的住房援助最多？”
• “从 5 月开始，每个月发布了多少项面向中小企业的援助？”
• “为安达卢西亚的一家餐饮业中小企业制作每周摘要。”
• “这个月 BOE 有没有发布护理专业的公务员考试公告？”

此外，还有两个提示词，客户端会将其显示为命令（/）：

提示词	用途
ayudas_para_mi	根据个人资料（“个体经营者，在毕尔巴鄂经营美发店”），以表格形式列出开放的援助、预计近期发布的援助，以及最佳选项的申请要求。
analizar_convocatoria	根据公告代码生成公告详情卡片，包括申请期限、金额、要求和所需材料，并注明页码。

5. 工具

所有工具均为只读（MCP 注解），因此支持此功能的客户端不会在每次调用时都请求确认。封闭列表中的值（社区、受益人、用途……）支持大写、重音符号和常见名称：「País Vasco」、「Euskadi」或「pymes」与 pais-vasco 或 autonomo-o-pyme 等效。

工具	功能
ayudas_buscar	按文本、社区、受益人、用途、工具和管理机构搜索。提供精确总数，以及包含状态、期限和预算的样本。
ayudas_recuento	按社区、用途、受益人、工具、管理机构、部门、月份或年份进行精确计数和排名。
ayudas_previstas	预期日历：每年都会发布的资助，以及根据其自 2021 年以来的历史记录，即将发布或正在延迟发布的资助。
ayuda_detalle	完整档案：解读后的期限、官方摘要、依据、文档和历史记录。
ayuda_texto	读取依据 PDF，并按页返回其中各部分的原文。
novedades_perfil	面向特定档案的简报：尚未截止的新资助，以及与其主题相关的 BOE 内容，不包括协议或学习计划。如果某个主题没有搜索结果，则会按前缀重新搜索并说明这一点。
estado_datos	数据来源、缓存状态和日历状态。
boe_sumario_dia	某日的 BOE 发布内容，可按关键词和栏目筛选。
boe_buscar	按日期范围、关键词和栏目搜索 BOE（2B 为考试，5A 为招标）。
boe_documento	BOE 中某项规定的文本。

服务器还会向模型发送指令：应使用哪个工具进行计数或读取要求，并应引用代码和通知，而不是补充虚构数据。

6. 配置

npx ayudas-es-mcp --help
npx ayudas-es-mcp --version
npx ayudas-es-mcp --vaciar-cache

可选环境变量：

变量	控制内容	默认值
AYUDAS_CACHE	缓存文件路径	~/.cache/ayudas-es-mcp/cache.sqlite
BDNS_INTERVALO_MS	BDNS 请求间隔	1000
AYUDAS_TIMEOUT_MS	每次请求的最长时间	30000

缓存

响应会保存在磁盘上（如果无法写入，则只保存在内存中），以避免重复请求。这不是 BDNS 的副本：它只会保存已查询的内容。缓存时长取决于各项数据可能发生变化的程度：

数据	缓存时长
结束时间超过 7 天的期间内的总数和列表	1 周
包含近期日期的总数和列表	1 小时
期限为暂定状态的档案（摘要尚未发布）	1 天
已截止或无需申请的征集档案	1 个月
其他档案	1 周
从 PDF 提取的文本	1 个月
预期日历	1 周
结束时间超过 1 个月的年份的历史记录（供日历使用，已压缩）	6 个月
当年的历史记录（供日历使用，已压缩）	1 天

日历历史记录在磁盘上约占 25 MB（每年约 4 MB）。

7. 工作原理

每个问题都会转换为对 BDNS 官方 API 的查询：

• 一次请求即可获得精确总数。 API 会返回搜索匹配项数量，而无需下载匹配项。简单计数只需一次请求，排名则每个分组需要一次请求。
• 分两步按词搜索。 API 会搜索子字符串（搜索「tala」会找到「instalación」）。系统会将每个单词的词根发送给 API，然后根据下文所述的单词规则处理 API 的响应。
• 只获取所展示内容的详情。 期限、预算和类型均在每项征集的档案中，只有在展示时才会请求。
• 谨慎控制频率。 对 BDNS 的请求最多每秒一次；BDNS 会阻止突发请求。

按关键词搜索

搜索标题（以及巴斯克语、加泰罗尼亚语或加利西亚语的共同官方标题），不考虑重音符号，匹配完整单词，单数和复数视为等价（「pyme」和「pymes」），并支持使用 * 作为前缀（「digital*」可找到 digitalización 和 digitales）。搜索范围较广的主题时，建议使用 finalidad。

常见术语会扩展为其同义词：「autónomos」也能找到「por cuenta propia」和「autoempleo」；「pymes」也能找到「pequeñas y medianas empresas」和「microempresa」；「vehículo eléctrico」也能找到「movilidad eléctrica」和「MOVES」。列表位于 src/texto.ts，只包含经过真实标题审核、含义密切对应的词语。像「Consejería de Empleo」中的「empleo」这样通常属于机构名称的词语不在列表中，因为它们主要会引入噪声。同义词中的词语必须按顺序连续出现，中间最多间隔两个词。响应会指出添加了哪些词语；使用 sinonimos: false 时，只搜索输入的词语。带有 * 的词语不会扩展。列表之外不进行语义搜索：「digitalización」不会找到「transformación tecnológica」。

同义词不会增加请求次数：API 支持搜索「这些词中的任意一个」，之后再应用精确筛选。

每项征集的申请期限

BDNS 仅提供部分征集的申请日期。其他征集的期限以文字形式给出，并通过规则解析，不使用 AI：

文本内容	结果
类型为「Concesión directa - instrumental」	无法申请：这是已授予特定受益人的援助记录。
「Hasta el 30 de noviembre de 2026」、「31 de decembro」、「1/3/27」	根据日期判断是否开放或已截止（西班牙语、加利西亚语和加泰罗尼亚语）。
「10 días hábiles desde el día siguiente a la publicación」，且摘要已发布	根据日历计算截止日期。
同上，但摘要尚未发布	待发布。
「Sin plazo de solicitud」、「no procede」、「nominativa」	无法申请。
多个期限或非标准起始时间	请查阅：不冒险给出日期。

计算遵循《第 39/2015 号法律》第 30 条：工作日不包括周六、周日和节假日；月份在到期月份的同一日结束；如果最后一天为非工作日，则顺延至下一个工作日。全国和自治区节假日数据来自 Nager.Date。不包括地方节假日，因此响应始终会说明这是估算，并说明计算方式。手动核验过的案例位于 src/plazos.test.ts。

阅读条款（PDF）

ayuda_texto 会下载征集的 PDF，并返回带页码的原文，不进行摘要，也不使用 AI。仅按需处理，每份文档只处理一次。

• 按名称选择文档：优先选择「texto íntegro」或「bases」，而不是附件、表格或批准协议。如果选中的文档无法读取，则继续尝试下一个，并说明原因。响应会列出其他文档，供用户请求（documento）。
• 根据标题定位章节（Artículo、Base、「Primero.-」、「6. Plazo…」、大写字母）。区分章节（存在对应标题）和提及（仅提到相关主题）。
• 如果无法识别章节，可使用 buscar 和 paginas 直接搜索词语或指定页面。
• 提取所有欧元金额，并附上每个金额所在的句子。
• PDF 内容会标记为外部文档的原文，不会被视为指令。

限制：不支持 OCR（无法读取没有文本层的扫描版 PDF），不读取 Word 文档或其他格式；对于超过 25 MB 或 200 页的文件，只读取前面的内容。章节通过规则检测，因此建议核对所引用的页面。

预计日历

同一主管机构下标题相同的征集会归为一组，不考虑年份、日期或届次 （«XIV Premios X 2026» 等同于 «XV Premios X 2027»）。征集年份达到 3 年或以上的会形成一个系列，并标注其典型登记日期及变化情况。具名资助、直接资助和协议不纳入其中，因为无法申请。

每个系列都会根据征集年份数量和日期规律性标注置信度（高、中或低）。如果上一年登记时间明显偏离通常日期，置信度就会降低一级；如果有年份未征集，置信度最高为中。低置信度系列默认隐藏。有些系列会更名或停止征集，因此预计日期仅为估算。工具会根据每个日历计算评估结果并显示出来，以便 AI 说明其可信程度。

日历需要从 2021 年开始的历史数据。首次使用资助工具时，会在后台准备这些数据，而不是在启动时准备；与此同时，ayudas_previstas 会提示正在准备，而不是回答“没有”。首次准备约需 1 分钟。每年数据下载后都会立即保存：如果客户端中途关闭，下次会从缺少的年份继续下载。每周更新时，只会重新下载当年的数据，大约需要 20 秒。

8. 如何避免提供错误信息

风险	处理方式
搜索没有结果就说“没有资助”	空结果会附带提示：搜索依据是标题关键词，无法证明不存在资助。
根据样本数量进行统计	ayudas_buscar 会给出确切总数，并标明列表是样本；统计数量请使用 ayudas_recuento。
将国家级资助与某个自治区的资助混为一谈	每条资助信息都会注明适用范围；覆盖西班牙全国的资助会标为“ESTATAL”，即使征集方是其他自治区的机构。
查询已无法申请的资助	区分已关闭、无需申请（直接授予）和开放状态，并单独列出工具性资助。
累加部分预算	BDNS 不会整体提供预算，因此统计结果不会累加预算；每项征集的预算见其详情。
只查看最近 90 天却不说明	会注明这一点，并统计使用相同筛选条件时更早登记的其他资助数量。
为一个问题下载数千行数据	如果排除直接授予需要下载超过 30.000 行数据，会要求缩小范围。
凌晨时“今天”的日期不对	日期采用西班牙半岛时间，而非 UTC。
数据源响应缓慢或不可用	每次请求都有超时时间和重试机制，即使响应中途截断也一样；单次故障不会导致整个回答失败，并会提示缺少的内容。
同义词导致搜索范围过宽	回答会说明添加了哪些词；设置 sinonimos: false 后，只搜索输入的内容。
日历尚未准备好	会提示正在准备，而不是显示“0 项定期资助”。
日历中的系列每年有多项资助	会标记主管机构以相同标题登记了多项资助的系列。
引用 PDF 中不存在的内容	返回带页码的原文，区分实际章节与提及，并在找不到相关主题时予以提示。
PDF 文本中包含指令	会将其标注为外部文档中的原始数据。
代码不存在	立即给出明确错误，不进行重试。

9. 已知限制

• 补助状态。 BDNS 不会标明某个征集是否开放（其字段 abierto 始终为 false，有关开放状态和类型的筛选条件也会被静默忽略），因此需要根据 解析后的期限推断。计算出的期限不包括地方节假日。
• 直接授予。 只有查看各征集的详情才能确定哪些属于直接授予。在搜索和计数中， 筛选条件 excluir_directas 会根据标题进行估算，因此无法识别全部直接授予。未使用 此筛选条件的计数会包含直接授予，并会对此进行提示。
• 预算和较早的补助。 预算和期限只记录在各征集的详情页中，因此计数不会汇总预算，搜索也无法找到 数月前登记但仍开放的补助（会提示统计周期开始前有多少项）。
• 首次生成排名。 按自治区或目的分组需要针对每个组发起一次请求，可能需要一些时间；再次生成时会从缓存中读取。
• 日历。 预测的是在 BDNS 中的登记时间，而非申请期限，也无法检测名称发生变化的补助。
• 自治区。 BDNS 中有一部分征集没有指定所属自治区。
• 标题相同、补助不同。 有些机构会以同一标题登记数十项单独的补助；它们并非重复项，因此不会被删除。
• PDF 读取。 通过规则而非 OCR 或 AI 进行处理。
• 多个实例。 每秒一次请求的限制针对单个进程：同时打开多个客户端时，请求频率会累加，但它们会共用磁盘缓存。

10. 开发

git clone … && cd ayudas-es-mcp
npm install
npm run build
npm test            # pruebas sin red: plazos, lectura de documentos, fechas, caché
npm run test:live   # búsqueda en directo frente a la referencia + prueba de extremo a extremo

数据和许可证

代码以 MIT 许可证发布（参见 LICENSE）。

• BDNS。 数据来源：西班牙国家行政总局干预总局。数据根据其法律声明重复使用，该声明允许商业和非商业用途，但须注明来源，且不得歪曲信息。此服务仅查询征集信息，不查询受益人的个人数据。
• BOE。 数据来源：西班牙国家官方公报国家机构，通过其开放数据 API 获取。数据根据其 法律声明重复使用，该声明允许商业和非商业用途，但须注明来源、附上指向 boe.es 的链接，且不得暗示获得其认可。
• 节假日。 Nager.Date，公共节假日 API。

本项目独立运营：与 IGAE、西班牙国家 BOE 机构或任何公共机构均无关联，也未获得其认可。来源中的信息可能会更改或更正：提交申请前，请务必在官方详情页核实。