PH Schools MCP Server

菲律宾学校 MCP 服务

用于查询和分析菲律宾学校主名录数据集的本地 stdio MCP 服务。

此服务提供的功能

工具：

1. search_schools
2. get_school_by_beis_id
3. list_regions
4. list_divisions
5. dataset_stats

安装和运行

npm install
npm start

仅在手动从此仓库运行时使用 npm start。

选择哪种配置

• VS Code MCP（.vscode/mcp.json）：满足日常使用需求。如果状态为 Running，则表示 VS Code 已经启动了服务。
• Claude Desktop（claude_desktop_config.json）：满足日常使用需求。配置更改后请重启 Claude。
• npx -y @darwinphi/ph-schools-mcp-server ...：无需克隆仓库即可进行一次性命令行操作。
• npm install && npm start：用于在此仓库中进行本地开发和维护。

使用场景

1. 已配置 mcp.json，不手动运行 npx：聊天工具调用（dataset_stats、search_schools 等）正常工作。
2. 手动运行 npx -y @darwinphi/ph-schools-mcp-server，未配置 MCP 客户端：服务进程会启动，但聊天客户端不会自动使用它。
3. 已配置 mcp.json，同时手动运行 npx：通常没有必要；让 MCP 客户端管理启动和停止即可。
4. 不使用 MCP 聊天的一次性命令：使用 npx ... --help 或 npx ... sync-data ...。

未配置 MCP 客户端时，VS Code/Claude 无法自动调用工具。

何时使用 mcp.json

在 VS Code（或 Claude Desktop 中等效的客户端配置）中日常使用 MCP 时，请使用 mcp.json。

适用于：

1. 由 MCP 客户端自动启动服务并管理其生命周期
2. 直接通过聊天提示词使用 MCP 工具（dataset_stats、search_schools 等）
3. 在工作区中共享团队/项目级 MCP 配置

如果 MCP 状态显示为 Running，则表示客户端已经启动了服务；通常无需手动运行 npm start 或 npx。

何时使用 npx

需要在不克隆或开发此仓库的情况下执行一次性命令行操作时，请在终端中使用 npx。

适用于：

1. 确认已发布的软件包能够运行：npx -y @darwinphi/ph-schools-mcp-server --help
2. 手动下载/更新数据集：npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"
3. 在客户端管理的 MCP 生命周期之外手动启动调试：npx -y @darwinphi/ph-schools-mcp-server

请勿使用 npx 启动来替代 VS Code/Claude MCP 配置。日常使用时，请让 MCP 客户端根据其配置管理服务启动。

何时使用 npm install 和 npm start

在此仓库中工作时（开发者/维护者工作流）使用这些命令，而非用于日常客户端使用。

适用于：

1. 在此仓库中编辑源文件时进行本地开发
2. 在提交/发布前运行测试
3. 调试尚未发布的本地更改

典型的本地工作流：

npm install
npm test
npm start

如果 VS Code/Claude MCP 配置已经正常工作，通常无需手动运行 npm start。

命令行（已发布的软件包）

# Start MCP server over stdio
npx -y @darwinphi/ph-schools-mcp-server

# Sync canonical dataset once to a chosen path
npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"

快速验证

npx -y @darwinphi/ph-schools-mcp-server --help
npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"

数据集配置

此服务默认采用混合模式：

• 如果本地数据集文件存在，则立即使用该文件。
• 如果本地数据集文件不存在，则会自动从规范数据集 URL 下载并缓存到本地。

默认规范 URL（固定使用标签 v1.0.1）：

https://raw.githubusercontent.com/darwinphi/ph-schools-dataset/v1.0.1/schools_masterlist_2020_2021.json

运行时环境变量：

• PH_SCHOOLS_DATA_PATH：首选的本地 JSON 文件路径（如果文件存在则直接使用；如果不存在，则自动同步到此路径）
• PH_SCHOOLS_DATA_URL：为 sync-data 覆盖下载 URL
• PH_SCHOOLS_DATA_TAG：未提供 URL 时，供 sync-data 使用的规范标签

VS Code MCP 配置（复制/粘贴）

设置 .vscode/mcp.json：

{
  "servers": {
    "phSchools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@darwinphi/ph-schools-mcp-server"],
      "env": {
        "PH_SCHOOLS_DATA_PATH": "/Users/your-user/.ph-schools/data.json"
      }
    }
  }
}

如果 PH_SCHOOLS_DATA_PATH 指定的文件不存在，服务会自动从规范来源下载，并写入该路径。

Claude Desktop 配置（复制/粘贴）

更新 Claude 配置：

{
  "mcpServers": {
    "ph-schools": {
      "command": "npx",
      "args": ["-y", "@darwinphi/ph-schools-mcp-server"],
      "env": {
        "PH_SCHOOLS_DATA_PATH": "/Users/your-user/.ph-schools/data.json"
      }
    }
  }
}

如果 npx 在你的 shell 中不稳定，也可以全局安装并使用 "command": "ph-schools-mcp-server"。

如果 PH_SCHOOLS_DATA_PATH 文件不存在，服务会自动从规范来源下载数据，并写入该路径。

macOS 上常见的配置文件：

~/Library/Application Support/Claude/claude_desktop_config.json

测试命令

npm test
npm run test:package

示例提示词

• Run dataset_stats and summarize key insights.
• List all divisions in Region I using list_divisions.
• Search schools in region "Region I" and division "Ilocos Norte".
• Get school by BEIS ID 100001 using get_school_by_beis_id.
• Search schools with query "High School".

发布与版本流程

一次性 npm 设置（可信发布）：

1. 在 npmjs.com 上打开软件包 @darwinphi/ph-schools-mcp-server → Settings → Trusted publishers。
2. 添加 GitHub Actions 可信发布者，并填写：
   • Owner/User：darwinphi
   • Repository：ph-schools-mcp-server
   • Workflow filename：cd.yml
3. 不要使用 NPM_TOKEN；发布工作流使用 OIDC（id-token: write）。

手动发布流程（v1）：

1. 更新 src/constants.js 中固定的数据集标签。
2. 更新软件包版本：

npm version patch   # or minor / major

npm version patch 的操作：

• 更新 package.json 中的版本（例如，1.0.1 -> 1.0.2）
• 更新 package-lock.json 中的版本字段
• 创建 git 提交
• 创建 git 标签（例如，v1.0.2）

3. 将 server.json 中的版本同步为与 package.json 一致。
4. 运行：

npm ci
npm test
npm run test:package

5. 推送提交和标签：

git push
git push --tags

6. 根据标签创建 GitHub Release 说明：

gh release create v<new_version> --generate-notes --title "v<new_version>"

示例：

gh release create v1.0.2 --generate-notes --title "v1.0.2"

7. 推送提交和标签。推送标签（v*）会自动触发 CD Release 工作流。
8. 工作流会发布 npm 软件包，然后发布 MCP Registry 元数据。

如需仅更新元数据，请使用工作流 Publish MCP Registry Metadata。

许可证与数据来源

• 代码许可证：ISC（LICENSE）。
• 数据集来源：darwinphi/ph-schools-dataset（由 gov.ph 来源数据支持的规范仓库）。
• 数据集的使用仍受来源条款和适用政策约束。