Philippine Standard Geographic Code Mcp Server

PSGC MCP 服务

一种模型上下文协议（MCP）服务，可访问菲律宾标准地理代码（PSGC）API，提供菲律宾的分层地理数据。

功能

• 完整的地理层级：可访问岛群、地区、省、市、自治市、村和选区
• 搜索功能：按名称搜索所有层级的地理实体
• 代码验证：验证 PSGC 代码并获取完整的层级信息
• 实时数据：直接访问官方 PSGC API
• 类型安全：使用 TypeScript 构建，确保数据结构可靠

安装

从 NPM 安装（已发布的软件包）

npm install -g psgc-mcp

MCP 客户端配置

Cursor/Windsurf

添加到 MCP 配置文件：

{
  "mcpServers": {
    "psgc-mcp": {
      "command": "npx",
      "args": ["-y", "psgc-mcp"],
      "transport": "stdio"
    }
  }
}

Claude Desktop

添加到 Claude Desktop 配置：

{
  "mcpServers": {
    "psgc-mcp": {
      "command": "npx",
      "args": ["-y", "psgc-mcp"],
      "transport": "stdio"
    }
  }
}

本地开发

1. 克隆仓库
2. 安装依赖：npm install
3. 构建项目：npm run build
4. 本地运行：npm start

可用工具

该服务提供了一套全面的工具，用于访问 PSGC 数据，并按地理层级分类。

岛群工具

• get_island_groups：列出所有岛群。
• get_island_group：按代码获取指定岛群（例如，"luzon"）。
• get_island_group_regions：获取指定岛群内的所有地区。
• get_island_group_provinces：获取指定岛群内的所有省。
• get_island_group_districts：获取指定岛群内的所有选区。
• get_island_group_cities：获取指定岛群内的所有市。
• get_island_group_municipalities：获取指定岛群内的所有自治市。
• get_island_group_cities_municipalities：获取指定岛群内的所有市和自治市。
• get_island_group_sub_municipalities：获取指定岛群内的所有次级自治市。
• get_island_group_barangays：获取指定岛群内的所有村。

地区工具

• get_regions：列出所有地区。
• get_region：按代码获取指定地区（例如，"130000000"）。
• get_region_provinces：获取指定地区内的所有省。
• get_region_districts：获取指定地区内的所有选区。
• get_region_cities：获取指定地区内的所有市。
• get_region_municipalities：获取指定地区内的所有自治市。
• get_region_cities_municipalities：获取指定地区内的所有市和自治市。
• get_region_sub_municipalities：获取指定地区内的所有次级自治市。
• get_region_barangays：获取指定地区内的所有村。

省级工具

• get_provinces：列出所有省。
• get_province：按代码获取指定省（例如，"012800000"）。
• get_province_cities：获取指定省内的所有市。
• get_province_municipalities：获取指定省内的所有自治市。
• get_province_cities_municipalities：获取指定省内的所有市和自治市。
• get_province_sub_municipalities：获取指定省内的所有次级自治市。
• get_province_barangays：获取指定省内的所有村。

选区工具

• get_districts：列出所有选区。
• get_district：按代码获取指定选区（例如，"133900000"）。
• get_district_cities：获取指定选区内的所有市。
• get_district_municipalities：获取指定选区内的所有自治市。
• get_district_cities_municipalities：获取指定选区内的所有市和自治市。
• get_district_sub_municipalities：获取指定选区内的所有次级自治市。
• get_district_barangays：获取指定选区内的所有村。

市级工具

• get_cities：列出所有市。
• get_city：按代码获取指定市（例如，"012805000"）。
• get_city_barangays：获取指定市内的所有村。

市镇工具

• get_municipalities：列出所有市镇。
• get_municipality：根据代码获取指定市镇（例如，"012801000"）。
• get_municipality_barangays：获取指定市镇内的所有 barangay。

次级市镇工具

• get_sub_municipalities：列出所有次级市镇。
• get_sub_municipality：根据代码获取指定次级市镇（例如，"133901000"）。
• get_sub_municipality_barangays：获取指定次级市镇内的所有 barangay。

城市/市镇组合工具

• get_cities_municipalities：列出所有城市和市镇。
• get_city_municipality：根据代码获取指定城市或市镇。
• get_city_municipality_barangays：获取指定城市或市镇内的所有 barangay。

Barangay 工具

• get_barangays：列出所有 barangay。
• get_barangay：根据代码获取指定 barangay（例如，"012805001"）。

搜索和发现工具

• search_by_name：按名称搜索所有级别的地理实体。
• get_hierarchy：获取指定 PSGC 代码的完整层级结构。
• validate_code：验证地理代码是否存在并获取其详细信息。

可用资源

• 静态数据：访问所有地理级别的预加载静态数据。
• 动态查询：执行参数化查询以获取特定数据集。
• 层级数据：使用资源模板，获取任意给定 PSGC 代码的完整层级信息。

可用模板（提示词）

• 常见查询：使用预定义提示词回答常见地理问题（例如，“[省份] 的首府是什么？”）。
• 引导式发现：通过交互式提示词探索地理层级结构。
• 数据验证：验证 PSGC 代码和地理名称的提示词。

使用示例

获取所有地区

{
  "tool": "get_regions",
  "arguments": {}
}

获取某个地区内的省份

{
  "tool": "get_provinces",
  "arguments": {
    "region_code": "130000000"
  }
}

按名称搜索

{
  "tool": "search_by_name",
  "arguments": {
    "query": "Manila",
    "type": "city"
  }
}

获取完整层级结构

{
  "tool": "get_hierarchy",
  "arguments": {
    "code": "133900000"
  }
}

API 参考

该服务连接到官方 PSGC API：https://psgc.gitlab.io/api/。

PSGC 代码格式

PSGC 代码遵循层级格式：

• 岛群：010000000、020000000、030000000
• 地区：130000000（NCR）、140000000（CAR）等
• 省份：133900000（马尼拉）、137400000（宿务）等
• 城市/市镇：133903000（马尼拉市）、137404000（宿务市）等
• Barangay：133903001（马尼拉的 Barangay 1）等

开发

前置条件

• Node.js 18 或更高版本
• npm 或 yarn

设置

git clone https://github.com/your-username/psgc-mcp.git
cd psgc-mcp
npm install

构建

npm run build

开发模式

npm run dev

测试

npm test

使用 MCP Inspector 检查

npm run inspect

参与贡献

1. Fork 此代码库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改
4. 为新功能添加测试
5. 运行测试：npm test
6. 提交更改：git commit -am 'Add feature'
7. 推送到该分支：git push origin feature-name
8. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

支持

如有问题或疑问，请在 GitHub 代码库中提交 issue。