PSGC MCP Server

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

特性

• 完整的地理层次结构：访问群岛、地区、省、市、镇、巴朗吉和区
• 搜索能力：通过名称在所有层级中查找地理实体
• 代码验证：验证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_districts：列出所有区。
• get_district：通过其代码（例如："133900000"）获取特定区。
• [...]：其他工具类似。

城市工具

• get_cities：列出所有城市。
• get_city：通过其代码（例如："012805000"）获取特定城市。
• get_city_barangays：获取特定城市内的所有巴朗吉。

镇工具

• get_municipalities：列出所有镇。
• get_municipality：通过其代码（例如："012801000"）获取特定镇。
• get_municipality_barangays：获取特定镇内的所有巴朗吉。

次镇工具

• get_sub_municipalities：列出所有次镇。
• get_sub_municipality：通过其代码（例如："133901000"）获取特定次镇。
• get_sub_municipality_barangays：获取特定次镇内的所有巴朗吉。

综合城市/镇工具

• get_cities_municipalities：列出所有城市和镇。
• get_city_municipality：通过其代码获取特定城市或镇。
• get_city_municipality_barangays：获取特定城市或镇内的所有巴朗吉。

巴朗吉工具

• get_barangays：列出所有巴朗吉。
• get_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（宿务市）等
• 巴朗吉：133903001（马尼拉巴朗吉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. 分叉仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改
4. 为新功能添加测试
5. 运行测试：npm test
6. 提交更改：git commit -am '添加功能'
7. 推送到分支：git push origin feature-name
8. 提交拉取请求

许可证

MIT许可证 - 详情见LICENSE文件。

支持

对于问题和疑问，请在GitHub仓库上打开一个issue。 </中文翻译>