osm-tagging-schema-mcp

OpenStreetMap 标记方案 MCP 服务

这是什么？

这是一个专为 AI Agent 和大模型应用设计的 Model Context Protocol (MCP) 服务。它充当人工智能系统与官方 @openstreetmap/id-tagging-schema 库提供的全面 OpenStreetMap 标记知识库之间的桥梁。

项目状态

本项目是一个概念验证。它在某些方面具有实际价值，但在其他方面也存在已知不足，以下都会如实说明。

• 它适用于最新的标记方案 @openstreetmap/id-tagging-schema v7。
• 正在开发一个更好的替代工具。它将比最初计划的更晚推出，且不承诺具体日期。

问题报告和想法：请提交 issue 或发起 discussion。

工作原理

服务默认通过 stdio 运行，也可通过 HTTP 运行，并将标记方案作为 MCP 工具公开。每个工具都会读取 @openstreetmap/id-tagging-schema 中随包提供的方案数据（预设、字段、已弃用标记、翻译），并以确定性方式据此作答。服务不会连接 OSM，也不包含 AI：AI Agent 调用工具并解读结果。

验证会根据方案检查标记：键是否已知、值是否为匹配字段允许的值，以及键/值是否已弃用并有建议的替代项。

能做什么，不能做什么

该工具有一定局限。依赖它之前，请先了解预期：它只根据方案数据作答，现实中存在或 OSM wiki 上记录的标记，有一部分未涵盖。

工具	能做什么	局限
validate_tag	接受常用标记（100%），几乎不会误报 deprecated（99.2%）	只能检测约 20% 的 wiki 已弃用标记；拼写错误和外语值会被接受为有效值（允许自定义标记）；railway=platform 和 railway=station 会被错误标记为已弃用
validate_tag_collection	与 validate_tag 一致（100%）	与 validate_tag 存在相同的遗漏；不会报告控制字符
suggest_improvements	为 92% 的常用标记匹配到预设	拼写错误和外语值通常会得到建议，而不是问题报告
get_tag_values	包含 97% 的 taginfo 值；会拒绝无效键和超出限制的请求	列表中缺少少数 taginfo 值
search_tags	按名称找到 60% 的键	尽管描述中提到模糊匹配，但不容忍拼写错误；带冒号的键（addr:street）常常无法找到；limit 为 0 或负数时不一定会被拒绝；access 会返回没有 key 的 keyMatches 项
search_presets	为 69% 的常用标记找到预设（前 3 个结果中占 56%）	多词查询（bicycle parking）可能没有结果；排序效果较弱；limit 为 0 或负数时不一定会被拒绝
get_preset_details	93% 的常用标记有对应预设；始终会拒绝未知 ID	一些常用标记（例如 historic=*、craft=grinding_mill、railway=stop）没有预设
compare_tags	与本地计算结果一致（100%）；文本和 JSON 输入会产生相同输出	可比较任意标记集合，因此不会判定某个标记是否错误；只会拒绝格式错误的输入
flat_to_json	无损转换，包括 ;、空格、=、Unicode、: 和 /	会静默接受重复键和控制字符
json_to_flat	无损往返转换（100%）；会拒绝无效输入	键不会按字母顺序排序，而是保留输入顺序

所有工具都不会因无效输入导致服务崩溃：错误信息易于理解，或结果为空列表。

摘要

适用于确定性逻辑足以胜任的场景：格式转换、比较标签集、读取预设和数值、验证常用标签。较弱的领域：检测已弃用标签和搜索（拼写错误、多个单词、带冒号的键）。

这不是什么

⚠️ 重要说明：

• 不是独立应用：此服务需要与 AI 系统（如 Claude Code 或 Claude Desktop）集成才能发挥作用。它没有用户界面或 Web 前端。
• 不供人类直接使用：如果没有 AI Agent 作为中介，此工具对终端用户毫无用处。它专为通过程序访问的 LLM 应用设计。

如果你在寻找面向用户的 OSM 标注工具，可以考虑使用 iD editor 或 JOSM。

安装

将服务添加到 Claude Code（stdio）：

# npx
claude mcp add --transport stdio osm-tagging-schema -- npx -y @gander-tools/osm-tagging-schema-mcp

# Docker
claude mcp add --transport stdio osm-tagging-schema -- docker run -i --rm ghcr.io/gander-tools/osm-tagging-schema-mcp:latest

HTTP 传输

stdio 是默认传输方式。设置 TRANSPORT=http 即可通过 HTTP 提供服务（可流式传输，Docker 镜像中的端口为 3000）：

变量	默认值	含义
TRANSPORT	stdio	stdio 或 http
PORT	3000	HTTP 端口
HOST	0.0.0.0	HTTP 绑定地址
CORS_ORIGINS	http://localhost:6274,https://mcp.ziziyi.com	以逗号分隔的允许使用的 CORS 来源
LOG_LEVEL	INFO	SILENT、ERROR、WARN、INFO、DEBUG

docker run --rm -p 3000:3000 -e TRANSPORT=http ghcr.io/gander-tools/osm-tagging-schema-mcp:latest

端点：GET /health（存活状态）、GET /ready（架构已加载）、GET /version。

许可证

GNU 通用公共许可证 v3.0 - 详情请参阅 LICENSE 文件。