Data Gov Il

data-gov-il-mcp

面向以色列政府开放数据的生产级 Model Context Protocol (MCP) 服务，数据来自 data.gov.il。

此服务通过官方 CKAN API，为兼容 MCP 的客户端提供对以色列政府数据集、资源、标签、组织和表格记录的结构化访问。它使用 TypeScript 编写，借助 Zod 验证输入和输出，以 JSON 为优先格式返回工具响应，并同时支持本地 stdio 和远程 Streamable HTTP 传输方式。

亮点

区域	状态
MCP 工具	默认提供 9 个工具，启用可选 Sampling 后提供 10 个
MCP 资源	5 个静态资源 + 1 个数据集资源模板
MCP 提示词	3 个支持参数补全的领域提示词
发现	内存中的目录快照，支持希伯来语规范化、模糊匹配、标签排序和共现分析
传输方式	stdio 和 Streamable HTTP
身份验证	none、API 密钥承载身份验证、OAuth 2.1 JWT/JWKS
HTTP 安全加固	Helmet、CORS、速率限制、请求 ID、Host/Origin 验证
响应	structuredContent，以及 content[0].text 中与之相同的 JSON
运行时配置	由环境变量驱动，并在启动时通过 Zod 验证

快速开始

Claude Desktop / 本地 Stdio

直接使用已发布的软件包：

{
  "mcpServers": {
    "data-gov-il": {
      "command": "npx",
      "args": ["-y", "data-gov-il-mcp"]
    }
  }
}

Streamable HTTP

npm install -g data-gov-il-mcp
data-gov-il-mcp-http

然后配置 MCP 客户端：

{
  "mcpServers": {
    "data-gov-il": {
      "url": "http://localhost:3664/mcp"
    }
  }
}

Docker

docker run -p 3664:3664 ghcr.io/davidosherproceed/data-gov-il-mcp:latest

本地开发：

npm install
npm run build
npm run start:stdio
# or
npm run start:http

目录发现层

此服务附带已提交的目录快照 src/data/catalog/catalog.snapshot.json。该快照由 data.gov.il 生成，并打包进构建产物中。启动时，系统会验证快照并将其编入内存索引。

发现层提供以下功能：

• find_datasets：优先搜索目录，CKAN 实时搜索作为回退。
• list_all_datasets：即时枚举本地数据集，可选按组织筛选。
• list_organizations：即时列出本地组织及其数据集数量。
• list_available_tags 和 search_tags：从实际的 CKAN 标签/分面数据中获取信息。
• 为 datagov://dataset/{id} 提供动态补全。
• datagov://tags 和 datagov://catalog/stats 资源。

其中包括：

• 希伯来语规范化，包括移除元音符号和规范化词尾字母。
• 用于模糊匹配和容错拼写的分词和三元组索引。
• 数据集、标签和组织映射。
• 标签到数据集、组织到数据集的索引。
• 用于推荐相关标签的标签共现分析。
• 基于精确匹配、词元、标签、组织和模糊匹配信号进行加权排序。

刷新快照：

npm run catalog:refresh
npm run build

计划任务 GitHub Actions 工作流（.github/workflows/catalog-refresh.yml）会刷新快照，并在目录数据发生变化时创建 PR。

了解详情：docs/catalog-discovery-layer.md。

工具

所有成功的工具响应都会返回：

• structuredContent：类型化的 JSON 对象。
• content[0].text：序列化为 JSON 的同一对象，供仅支持文本的客户端使用。

默认工具

工具	用途
find_datasets	主要的数据集发现工具。优先使用本地目录，需要时再回退到实时 CKAN。
get_dataset_info	数据集的完整 CKAN 元数据，包括标签和资源。
list_all_datasets	即时获取由目录支持的数据集摘要，可选择按组织筛选。
list_resources	列出数据集中的文件／数据存储，并识别 datastore_active 资源。
search_records	查询 CKAN 数据存储记录，支持全文搜索、筛选条件、字段、排序、分页和不同值。
list_organizations	由目录支持的组织列表，包含希伯来语标题和数据集数量。
get_organization_info	实时 CKAN 组织元数据。
list_available_tags	按排名列出目录标签及数据集数量和相关标签。
search_tags	模糊搜索标签并提供相关标签建议。

可选工具

工具	启用方式	用途
summarize_dataset	MCP_ENABLE_SAMPLING=true	请求兼容客户端执行 MCP Sampling，以生成易读的数据集摘要。Sampling 不可用时回退到元数据。

find_datasets 中的征询

find_datasets 可以选择性地公开 interactive 参数：

{
  "query": "תחבורה",
  "interactive": true
}

只有在以下条件下才会注册：

MCP_ENABLE_ELICITATION=true

启用后，兼容客户端可能会针对宽泛搜索显示澄清表单。例如，服务可以要求用户按发布组织缩小大量匹配数据集的范围。如果客户端不支持 Elicitation、用户拒绝，或请求超时，该工具会回退到常规搜索结果。

默认情况下此功能处于禁用状态，因为 MCP 客户端的支持情况各不相同。

资源

URI	类型	描述
datagov://organizations	静态 JSON	来自 CKAN 并经过缓存的组织列表。
datagov://tags	静态 JSON	来自已提交目录快照的排名标签。
datagov://featured	静态 JSON	精选的高价值数据集，包含可直接使用的 resource_id 值和字段架构。
datagov://guide	静态文本	工具、资源和推荐工作流的使用指南。
datagov://catalog/stats	静态 JSON	快照元数据：生成时间、数据集数量、标签数量、组织数量和顶级组织。
datagov://dataset/{id}	模板 JSON	按数据集 slug 或 ID 获取完整数据集元数据。包含动态补全和由目录支持的资源列表。

该服务还以最小且符合标准的方式实现资源订阅：

• 声明 resources.subscribe。
• 处理 resources/subscribe 和 resources/unsubscribe。
• 仅向订阅了资源的客户端发送 notifications/resources/updated。
• 不会实时轮询 CKAN。

提示词

提示词	参数	用途
food-nutrition-analysis	analysis_type	食品价格、营养、洁食、安全、进出口。
environmental-sustainability-analysis	analysis_focus	空气质量、绿色建筑、废弃物、水、污染场地。
real-estate-market-analysis	market_focus	住房、城市更新、补贴住房、城市／房地产分析。

提示词参数使用 MCP 补全。领域重点建议经过精选，组织补全由目录支持。

可选 MCP 客户端功能

这些功能默认关闭。仅在目标 MCP 客户端支持这些功能，且你希望服务公开这些功能时启用。

变量	默认值	作用
MCP_ENABLE_ELICITATION	false	为 find_datasets 添加 interactive，并允许服务发起澄清表单。适用于 Cursor 和 Claude Code 等客户端。
MCP_ENABLE_SAMPLING	false	注册 summarize_dataset，通过 MCP Sampling 请求客户端生成模型内容。

客户端支持情况各不相同：

• Cursor 支持 Elicitation，但目前不提供 Sampling。
• Claude Code 的近期版本支持 Elicitation。
• Claude Desktop 支持许多 MCP 功能，但 Elicitation 支持不可靠或不可用。
• Sampling 的可用性因客户端而异；服务始终会安全地回退。

配置

将 .env.example 复制为 .env：

cp .env.example .env

核心

变量	默认值	描述
TRANSPORT	stdio	使用通用入口点时的默认传输方式。也提供专用二进制文件。
PORT	3664	HTTP 端口。
HOST	0.0.0.0	HTTP 绑定主机。
CORS_ORIGIN	*	允许的 CORS 来源。生产环境的浏览器部署应避免使用通配符。
LOG_LEVEL	info	fatal、error、warn、info、debug 或 trace。
NODE_ENV	production	development、production 或 test。

CKAN

变量	默认值	描述
CKAN_BASE_URL	https://data.gov.il/api/3/action	CKAN action API 基础 URL。
CKAN_TIMEOUT_MS	10000	CKAN 请求的默认超时时间。
CKAN_SEARCH_TIMEOUT_MS	15000	较重的数据存储／搜索请求的超时时间。
CACHE_TTL_MS	300000	默认缓存 TTL。
CACHE_MAX_ITEMS	500	每个内存缓存的最大条目数。

HTTP 加固

变量	默认值	描述
TRUST_PROXY	false	信任反向代理标头。在 nginx/Caddy/ALB 后方时设置。
RATE_LIMIT_WINDOW_MS	60000	速率限制窗口。设为 0 可禁用。
RATE_LIMIT_MAX	120	每个 IP 在每个窗口内的请求数上限。设为 0 可禁用。
ALLOWED_HOSTS	empty	用于防范 DNS 重绑定的主机允许列表。未设置时，默认为回环／本地主机。
ALLOWED_ORIGINS	empty	浏览器 Origin 允许列表。适当时回退到 CORS_ORIGIN。

身份验证

变量	默认值	描述
AUTH_MODE	none	none、apikey 或 oauth。
API_KEYS	empty	用逗号分隔的 bearer 令牌，用于 AUTH_MODE=apikey。
OAUTH_ISSUER	unset	AUTH_MODE=oauth 时预期的 JWT 颁发者。
OAUTH_AUDIENCE	unset	AUTH_MODE=oauth 时预期的 JWT 受众。
OAUTH_JWKS_URI	unset	用于验证 JWT 的 JWKS URL。
OAUTH_RESOURCE_SERVER	unset	OAuth 受保护资源元数据的规范 MCP 资源 URL。通常包含 /mcp。

服务身份

变量	默认值	描述
SERVICE_NAME	package/server default	MCP 服务名称覆盖值。
SERVICE_VERSION	package version	MCP 服务版本覆盖值。
SERVICE_DESCRIPTION	built-in description	MCP 服务语义描述覆盖值。

推荐工作流

查找和查询数据集

1. 使用 find_datasets 和自然的希伯来语或英语词语。
2. 对选定的数据集使用 get_dataset_info 或 list_resources。
3. 选择 datastore_active=true 的资源。
4. 先使用 limit=5 调用 search_records，检查字段。
5. 根据需要添加 filters、fields、sort、distinct 或分页参数。

示例流程：

find_datasets({ "query": "מחיר למשתכן" })
get_dataset_info({ "dataset": "mechir-lamishtaken" })
search_records({
  "resource_id": "7c8255d0-49ef-49db-8904-4cf917586031",
  "limit": 5,
  "include_total": true
})

发现标签

search_tags({ "keyword": "דיור", "limit": 5 })
find_datasets({ "query": "תחבורה", "tags": "תחבורה ציבורית" })

使用交互式发现

需要：

MCP_ENABLE_ELICITATION=true

然后，Agent 可以调用：

find_datasets({ "query": "תחבורה", "interactive": true })

兼容的客户端可能会显示表单，请用户缩小结果范围。

使用客户端摘要

需要：

MCP_ENABLE_SAMPLING=true

然后：

summarize_dataset({ "dataset": "mechir-lamishtaken", "language": "he" })

如果 Sampling 不可用，该工具会返回数据集元数据，并设置 sampling.used=false。

开发

npm install

# Type-check
npm run typecheck

# Lint
npm run lint

# Test
npm test

# Build
npm run build

# Refresh local catalog snapshot
npm run catalog:refresh

在本地运行：

# stdio
npm run build
npm run start:stdio

# HTTP
npm run build
npm run start:http

在本地启用可选功能：

MCP_ENABLE_ELICITATION=true MCP_ENABLE_SAMPLING=true npm run start:http

在 PowerShell 中：

$env:MCP_ENABLE_ELICITATION="true"
$env:MCP_ENABLE_SAMPLING="true"
npm run start:http

项目结构

src/
  auth/           Authentication providers and Express middleware
  bin/            stdio and HTTP entry points
  cache/          In-memory TTL/LRU cache
  catalog/        Snapshot validation, indexing, fuzzy search, CatalogService
  ckan/           Typed CKAN API client and CKAN response types
  config/         Zod env config, constants, server identity
  core/           Dependency container, MCP server factory, lifecycle
  data/catalog/   Committed catalog snapshot artifact
  formatting/     JSON response builders and guidance text
  observability/  Pino logger
  prompts/        MCP prompt definitions, templates, registration
  resources/      MCP resources, templates, subscriptions
  services/       Domain services for CKAN data access
  tools/          MCP tool definitions and Zod schemas
  transports/     stdio and Streamable HTTP transports
tests/
  fixtures/       Test fixtures
  unit/           Unit tests
scripts/
  refresh-catalog.ts
docs/
  catalog-discovery-layer.md
  MIGRATION.md

Docker

docker build -t data-gov-il-mcp .
docker run -p 3664:3664 data-gov-il-mcp

启用可选功能：

docker run -p 3664:3664 \
  -e MCP_ENABLE_ELICITATION=true \
  -e MCP_ENABLE_SAMPLING=true \
  data-gov-il-mcp

质量

项目应通过以下检查：

npm run typecheck
npm run lint
npm test
npm run build

当前实现包含对环境解析、身份验证提供方、CKAN 错误、缓存、格式化、目录文本规范化／模糊匹配／索引／搜索逻辑、快照验证、服务、资源、订阅以及 HTTP Host／Origin 防护的单元测试覆盖。

许可证

MIT