PSGC地理编码服务

PSGC MCP服务器

A. 模型上下文协议 向LLM提供菲律宾标准地理代码（PSGC）数据的服务器。基于Cloudflare Workers和KV存储构建。

公共、只读、无需身份验证。数据直接来源于 菲律宾统计局 巴黎圣日耳曼俱乐部季刊。在Cloudflare KV中缓存，以实现可靠性和低延迟全局访问。

工具

地理级别

响应格式

所有数据响应都封装在一个标准信封中：

{
  "_meta": {
    "dataset_version": "PSGC Q4 2025",
    "dataset_date": "2025-12-31",
    "last_synced": "2026-03-02",
    "source": "Philippine Statistics Authority (PSA)",
    "source_url": "https://psa.gov.ph/classification/psgc/"
  },
  "data": { ... }
}

错误响应(isError: true)信息性消息（例如“未找到子消息”）以纯文本形式返回，不进行包装。

实体架构

返回的实体对象 lookup, get_hierarchy, list_children, list_by_type, batch_lookup，以及 query_by_population 使用snake_case字段名：

所有字段始终存在。没有数据的字段是 null，从未遗漏。

搜索结果

这 search 工具返回一个较轻的结果对象：

严格搜索

这 search 工具接受可选 strict 布尔参数。当 strict: true，仅返回精确的名称匹配（规范化后）。部分匹配和子字符串匹配被排除在外。当您知道确切的地名并希望避免模糊的结果时，这很有用。

批量查找

这 batch_lookup 该工具接受1-50个PSGC代码的数组，并以与输入相同的顺序返回结果。未找到代码返回 null 在他们的位置。

按人口查询

这 query_by_population 该工具按总体排序，查找总体范围内的实体。适用于“第三区最大城市”或“5万人以下城市”等问题

响应包括 results （实体数组）， total_matching （限额前总计），以及 returned （返回实际计数）。包含空填充的实体被排除在外。

连接

添加到MCP客户端配置中：

{
  "mcpServers": {
    "psgc": {
      "url": "https://psgc.godmode.ph/mcp"
    }
  }
}

快速测试

curl -X POST https://psgc.godmode.ph/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": { "query": "Carmona", "level": "Mun" }
    }
  }'

PSGC代码格式

PSGC代码是10位数字，没有空格。这些片段编码了整个地理层次结构：

1 4 0 2 1 0 0 0 0 0
│ │ └─┬─┘ └─┬─┘ └─┬─┘
│ │   │     │     └── Barangay (last 3 digits)
│ │   │     └──────── Municipality/City (3 digits)
│ │   └────────────── Province (2 digits)
│ └────────────────── Island Group modifier
└──────────────────── Region (1 digit)

前导零很重要-- 014021000000 和 14021000000 是不同的代码。始终使用完整的10位字符串。

已知的边缘情况：

• NCR使用 区域 而不是省份(Dist 水平）
• 哥打巴托市在行政上位于巴尔姆姆，但在地理上位于第十二区——它似乎位于 Prov 代码 124700000 （北马京达瑙）
• BARMM特殊地理单位(SGU)不遵循标准层次结构，也没有省父级

数据源

最后同步时间：2026年3月2日。

重大更改（v1.1.0+）

• 所有数据响应现在都被包裹在 { _meta, data }消费者必须打开包装 data 从回应中。
• 实体字段名称更改为snake_case： code 现在是 psgc_code, parent 现在是 parent_code, cityClass 现在是 city_class等等。
• 搜索结果使用 psgc_code 而不是 code.
• 所有实体字段始终存在。以前的可选字段现在显示为 null 而不是省略。
• 内部字段 regionCode 和 provinceCode 不再暴露在API响应中。

相关项目

菲律宾公共数据MCP服务器套件的一部分：

• PSGC-MCP （此回购）
• ts MCP -DHSUD销售许可证验证
• PH假期MCP ->即将推出
• BSP银行目录MCP ->即将推出

所有服务器都是免费的、公共的、只读的。数据来自菲律宾政府官方消息来源。

贡献和问题

发现数据错误或边缘情况未得到处理？打开一个问题。上面的怪癖部分涵盖了最常见的怪癖，但PSGC数据在几十年的LGU重新分类中积累了不一致之处，问题列表是跟踪它们的最佳位置。

PSA每季度发布更新。如果数据看起来过时，打开一个问题，它将在下一次计划同步之前刷新。

数据管道

PSGC数据从PSA的Excel出版物中解析并存储在Cloudflare KV中。要更新：

1.下载PSGC Excel文件

从获取最新出版物 PSA-PSGC 然后把它放进去 scripts/data/.

2.差异（可选）

npm run diff-psgc -- "scripts/data/Q3 2025/PSGC-3Q-2025-Publication-Datafile.xlsx" "scripts/data/PSGC-4Q-2025-Publication-Datafile (1).xlsx"

比较两个季度Excel文件，并报告添加、删除、名称更改和字段更改。在完整解析之前运行此程序以验证PSA的更改日志。

3.解析

npm run parse-psgc

读取Excel文件，导出父关系，并将分块的JSON文件写入 scripts/data/output/.

4.上传到KV

npm run upload-kv

通过wrangler批量上传所有JSON块到Cloudflare KV。

5.部署

npm run deploy

发展

npm install
npm run dev

开发服务器启动时间 http://localhost:8787。将您的MCP客户端连接到 http://localhost:8787/mcp.

设置

在首次部署之前，创建KV命名空间：

npx wrangler kv namespace create PSGC_KV

更新 wrangler.jsonc 使用返回的命名空间ID。

建造于

亚伦·扎拉 -CTO分数 Godmode数码

以前建造 任。PH，一个程序化的房地产平台，拥有60000多个结构化的地理页面，覆盖菲律宾的每个乡镇、城市和省份。PSGC MCP的出现是因为AI代理需要可靠、可查询的PH地理数据，但找不到任何合适的数据。

对于企业SLA、自定义集成或其他PH数据源： → godmode.ph

许可证

麻省理工学院