Idescat MCP Server

Idescat MCP 服务

MCP（Model Context Protocol）服务，可通过任何 MCP 客户端（Claude、Windsurf、Cursor、VS Code 等）查询由 Idescat（Institut d'Estadística de Catalunya）发布的加泰罗尼亚官方统计数据。

• 公共端点： https://api.idescat.cat/mcp
• 传输方式： Streamable HTTP（MCP 规范 2026-07-28，支持按请求提供元数据和 server/discover，并兼容 2025-11-25 及更早版本的旧版 initialize），无状态——每个 POST 请求均相互独立，不使用会话。POST 响应会根据客户端的 Accept 标头使用 JSON 或 SSE；不通过 GET 提供持久 SSE 流。
• 身份验证： 无需身份验证（数据为公开数据）。
• 数据： Idescat 的官方统计数据，采用 JSON-stat 格式；标签和说明使用加泰罗尼亚语；地域范围为加泰罗尼亚及其各级行政区划（县、市镇、省等）。

安装

公共端点为 https://api.idescat.cat/mcp。将以下任一配置片段添加到 MCP 客户端的配置中。不同客户端需要的键（serverUrl、url 等）可能不同，有时还需要指定 type。

Windsurf/Devin、Antigravity（serverUrl）

{
	"mcpServers": {
		"idescat": {
			"serverUrl": "https://api.idescat.cat/mcp"
		}
	}
}

Cursor、Roo Code、Zoo Code（type: streamable-http）

{
	"mcpServers": {
		"idescat": {
			"type": "streamable-http",
			"url": "https://api.idescat.cat/mcp"
		}
	}
}

Cline（type: streamableHttp）

{
	"mcpServers": {
		"idescat": {
			"type": "streamableHttp",
			"url": "https://api.idescat.cat/mcp"
		}
	}
}

VS Code 和新兴的标准形式（servers、type: http）

{
	"servers": {
		"idescat": {
			"type": "http",
			"url": "https://api.idescat.cat/mcp"
		}
	}
}

Claude.ai（自定义连接器）

Claude.ai（网页和桌面应用）无需配置文件，即可通过自定义连接器直接访问远程服务。

1. 打开自定义 → 连接器。
2. 点击添加自定义连接器。
3. 填写以下字段：
   • 名称： Idescat
   • 远程 MCP 服务 URL： https://api.idescat.cat/mcp
4. 点击添加。由于数据为公开数据，因此无需身份验证（OAuth / API 密钥）。
5. 返回聊天界面，从工具/附件菜单中启用 Idescat 连接器。助手现在可以使用其工具和资源。
6. （可选）在连接器的工具设置中，将每个 Idescat 工具的设置从需要批准切换为始终允许，这样助手每次运行工具时就无需请求确认。所有工具均为只读，因此可以放心使用。

Claude Desktop 和仅支持 stdio 的客户端（通过 mcp-remote 桥接）

仅支持 stdio 的客户端可通过 mcp-remote 桥接访问远程服务：

{
	"mcpServers": {
		"idescat": {
			"command": "npx",
			"args": ["-y", "mcp-remote", "https://api.idescat.cat/mcp"]
		}
	}
}

不确定客户端需要哪个键？（通用配置）

大多数客户端会忽略无法识别的键，因此以下包含多种键的配置适用于许多客户端：

{
	"mcpServers": {
		"idescat": {
			"url": "https://api.idescat.cat/mcp",
			"serverUrl": "https://api.idescat.cat/mcp",
			"type": "streamable-http",
			"streamableHttp": "https://api.idescat.cat/mcp"
		}
	}
}

协议版本

该服务支持双时代（MCP 版本控制）：

时代	协议版本	版本选择方式	行为
旧版	2025-11-25、2025-06-18、2025-03-26、2024-11-05	initialize 协商	与之前完全相同：输入 JSON-RPC → 输出 JSON-RPC，支持 ping、initialize；错误仍返回 HTTP 200（资源不存在时返回 -32002）。
新版	2026-07-28	每个请求中的 params._meta["io.modelcontextprotocol/protocolVersion"]（或 server/discover）	结果包含 resultType: "complete"、_meta serverInfo，以及可缓存方法的 ttlMs/cacheScope。此版本不支持 initialize/ping（-32601 → HTTP 404）；资源不存在时返回 -32602；不支持的版本返回 -32022；标头违规返回 -32020（HTTP 400）。

新版请求还必须发送匹配的标头：MCP-Protocol-Version（与 _meta 版本相同）、Mcp-Method（与 JSON-RPC 方法相同），以及 tools/call 的 Mcp-Name（工具名称）和 resources/read 的 Mcp-Name（URI；UTF-8 值可使用 =?base64?...?= 占位符）。始终接受 Origin——数据是公开的，API 支持 CORS *。

新版客户端可以打开 subscriptions/listen：服务会通过 SSE 流响应 notifications/subscriptions/acknowledged，并附带空筛选器（不支持任何通知类型——服务是无状态的，列表不会更改），随后按规范定义的方式逐渐关闭连接。客户端应改为依赖 ttlMs。

可用工具

工具	描述
get_idescat_stats	可用统计数据的完整列表。
get_idescat_stat	统计数据的信息（按缩写查询：censph、pibc 等）。
get_idescat_stat_tables	列出某项统计数据的表格。
get_table_metadata	表格元数据（维度、类别、单位等）。
get_table_data	JSON-stat 格式的表格数据：完整数据，或按维度／地区／时期筛选的数据，可使用可选参数 filters 和 last（应用筛选后最多 20,000 个单元格）。支持服务端计算：年龄范围筛选器（">=65"）、对某个维度的类别求 sum，以及 derive（占比／差值／百分比变化）。
get_table_geo	表格可用的地区划分（cat、prov、com、mun 等）。
render_table	生成可直接使用的 Markdown 表格（可选择行／列），并附上指向 Idescat 网站上对应表格的归属链接。接受与 get_table_data 相同的计算（年龄范围筛选器、sum、derive），并在表格下方的“Calculations:”区块中列出这些计算。

可用资源

除了工具之外，该服务还公开 MCP 资源——客户端可以将其附加到上下文中，而无需执行任何操作。

静态资源（resources/list）：

URI	描述
idescat://instructions	使用指南。
idescat://glossary/geo	地区代码词汇表（cat、prov、com、mun 等）。
idescat://catalog/stats	统计数据完整目录。

资源模板（resources/templates/list）——带参数的 URI：

URI 模板	描述
idescat://stat/{stat}	统计数据的信息（例如 .../censph）。
idescat://stat/{stat}/tables	列出某项统计数据的表格。
idescat://table/{stat}/{table}	表格元数据（例如 .../censph/538）。
idescat://table/{stat}/{table}/data	表格的 JSON-stat 数据（最多 20,000 个单元格）。

传输是无状态的，因此不提供 subscribe 和 resources/list_changed 通知（不存在持久连接）。

服务端计算

语言模型在对长串数值进行心算时出了名地不可靠。因此，get_table_data 和 render_table 接受三个可选参数，让服务端确定性地计算结果，而不是让模型自行对返回的数值进行加、减或除：

{ "filters": { "AGE": ">=65", "SEX": "TOTAL" }, "last": 1 }
{ "sum": ["AGE"] }
{ "derive": { "share": "AGE", "percent_change": "previous" } }

• 年龄范围筛选器。 对于编码为 Y000、Y005_009、Y_GE100 等的维度，筛选值可以是范围表达式（">=65"、">65"、"<16"、"<=15"、"16-64"）；服务端会将其解析为确切的代码列表。如果已发布的分组无法精确表达该范围，则会报错 range_not_representable。
• sum 通过加总类别来汇总列出的维度；结果为单个 SUM 类别。系统会自动排除 TOTAL。
• derive 会向指标维度追加派生指标：share（<METRIC>_SHARE = 100 × 数值 / 给定维度中 TOTAL 的数值）、difference（<METRIC>_DIFF，与上一期或指定时期相比）以及 percent_change（<METRIC>_PCT = 100 × (数值 − 基准值) / 基准值）。

计算引擎遵循 Idescat 的约定：指标维度上的 extension["%"] 声明了可加性（只有可加指标才能求和或计算占比），TOTAL 是总计代码，无法计算的单元格会以状态 d 返回 null。所有已应用的操作都会记录在 extension.derived 中（范围、汇总代码、公式、警告），而 render_table 会在表格下方以 Calculations: 区块显示这些内容。

不安全的请求会被拒绝：metric_not_additive、geo_not_summable（绝不汇总地域维度——请使用已发布该汇总数据的地域划分所对应的 geo 参数）、range_not_representable、incomplete_data 和 total_not_available。

Agent 技能

Agent Skills 开放格式的两项技能（一个包含 SKILL.md 文件的目录：YAML frontmatter + Markdown 说明）用于指导 Agent 正确使用 Idescat 数据。这些技能已发布在网站上，并在 ARD 清单中列出：

技能	URL	描述
jsonstat	https://www.idescat.cat/dev/api/taules/jsonstat/SKILL.md	如何读取 JSON-stat 2.0 数据集：维度索引、行优先顺序、步长/偏移量运算、null 和 status 处理。通用技能——适用于任何 JSON-stat 数据提供方。
workflow	https://www.idescat.cat/dev/api/taules/workflow/SKILL.md	如何可靠地查询 Idescat 数据（通过此 MCP 服务或 Tables API）：选择统计指标和地域层级、先查元数据的流程、20,000 个单元格的限制与筛选器，以及强制注明来源。

仓库文件

以下文件定义了服务的指导内容和资源，并以原样提供给 MCP 客户端：

• instructions.md — 服务在握手期间发送给客户端，并作为 idescat://instructions 资源公开的使用指南。该文件说明如何选择统计数据、数据检索流程、如何解读 JSON-stat，以及来源标注规则。
• resources.json — 服务公开的 MCP 资源和资源模板声明（即上文可用资源部分中的两张表），包含每项资源的 URI、标题、说明、MIME 类型及其对应的文件或工具。
• resources/geo.md — 用于 geo 参数的区域代码（cat、prov、at、com、mun、dis、sec）词汇表，作为 idescat://glossary/geo 资源公开。

仓库还包含：

• server.json — 服务的元数据清单，采用标准的 server.json 格式，用于将服务发布到官方 MCP 注册表。
• jsonstat/SKILL.md 和 workflow/SKILL.md — 两项 Agent 技能，也发布在网站的 https://www.idescat.cat/dev/api/taules/ 页面上。

发现（Agentic Resource Discovery）

该服务依据 Agentic Resource Discovery (ARD) 规范（v0.91）进行公告，以便 Agent 自动发现：

• ARD 清单发布于 https://www.idescat.cat/.well-known/ard.json 和 https://api.idescat.cat/.well-known/ard.json（两个主机均通过 Access-Control-Allow-Origin: * 提供服务）。清单包含顶层 specVersion，因此同一文档既是有效的 ARD 清单，也是有效的 AI Catalog 文件： /.well-known/ai-catalog.json 通过对 ard.json 的内部重写直接提供 （不重定向），媒体类型为 application/ai-catalog+json——这是某些 MCP 发现流程仍会优先请求的前身格式。 清单公告了四个条目：此 MCP 服务 (application/mcp-server-card+json)、由其 OpenAPI 文档 (application/openapi+json) 描述的 Idescat Tables API，文档位于 https://www.idescat.cat/dev/api/taules/openapi.json，以及两个 Agent 技能 (application/agent-skills+md，这是以 Markdown SKILL.md 文件发布的技能所用的 AI Catalog 媒体类型)。
• MCP 服务卡 (application/mcp-server-card+json) 位于 https://api.idescat.cat/mcp/server-card，这是实验性 Server Card 发现规范 指定的 <streamable-http-url>/server-card 位置。对裸端点 https://api.idescat.cat/mcp 执行 GET（或 HEAD）会返回 405——该端点 仅支持 POST，不过 POST 响应可以使用 SSE。服务卡与 MCP 握手中的 (serverInfo) 使用相同名称 cat.idescat/mcp，与 MCP Registry 中的名称一致。 服务卡响应遵循规范的缓存约定： Cache-Control: public, max-age=3600、通过 ETag 对 If-None-Match 请求返回 304，以及 CORS 标头（Allow-Methods: GET、 Allow-Headers: Content-Type, If-None-Match、Expose-Headers: ETag）。
• 旧版服务卡别名 /.well-known/mcp/server-card.json 和 /.well-known/mcp.json 在 api.idescat.cat 上通过内部重写直接提供 （字节内容相同，不重定向——有些爬虫不会跟随重定向）；在 www.idescat.cat 上则会重定向（307）到 https://api.idescat.cat/mcp/server-card。
• ard.json 中的 MCP 条目指向服务卡 URL，并通过 metadata.mcpEndpoint 提供传输端点 (https://api.idescat.cat/mcp)。它使用 application/mcp-server-card+json： 较早的 application/mcp-server+json 媒体类型已在 ARD ADR-0008 中弃用。
• 网站页面还包含指向清单的链接： <link rel="ard" href="/.well-known/ard.json" type="application/json"> （ard 链接关系取代了前身 ai-catalog 关系）。
• robots.txt 包含一个指向清单的 Agentmap: 指令。
• 网站的 llms.txt 文件也公告了此 MCP 服务。

MCP Registry

该服务以 cat.idescat/mcp 这一名称列于官方 MCP Registry 中（参见 server.json）。MCP 客户端和聚合器可以通过 Registry API 获取其元数据：

https://registry.modelcontextprotocol.io/v0.1/servers/cat.idescat%2Fmcp/versions/latest

使用 MCP Inspector 进行交互式测试

npx @modelcontextprotocol/[email protected]

固定指定版本（例如 @2.0.0）可确保工具具有可复现性，并避免意外引入更改；这需要 Node.js >= 22.19.0。任何 npm warn deprecated ... / ERESOLVE 消息都来自 Inspector 自身的依赖项，不会造成影响——它们不会影响此 MCP 服务。

选择 “Streamable HTTP” 传输方式并输入端点 URL。

Links

• Idescat: https://www.idescat.cat
• Model Context Protocol: https://modelcontextprotocol.io
• MCP specification (2026-07-28, Streamable HTTP transport): https://modelcontextprotocol.io/specification/2026-07-28
• MCP versioning (dual-era servers): https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
• Agentic Resource Discovery (ARD): https://agenticresourcediscovery.org
• ARD specification (rendered): https://agenticresourcediscovery.org/spec/
• ARD specification repository (schemas, conformance tooling): https://github.com/ards-project/ard-spec