PH Schools MCP Server

PH Schools MCP Server

フィリピンの学校マスターリストデータセットを検索・分析するためのローカル 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 ...：リポジトリをクローンせずに、一度だけ CLI を使用します。
• 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 で MCP を日常的に使用する場合は、mcp.json を使用してください（Claude Desktop では同等のクライアント設定を使用します）。

次の用途に使用します。

1. MCP クライアントによるサーバーの自動起動とライフサイクル管理
2. チャットのプロンプトから直接 MCP ツールを使用（dataset_stats、search_schools など）
3. ワークスペースでチーム／プロジェクト共通の MCP セットアップを使用

MCP のステータスが Running の場合、クライアントはすでにサーバーを起動しています。通常、手動での npm start や npx の起動は不要です。

npx を使用する場合

リポジトリをクローンまたは開発せず、一度だけ CLI 操作を実行する必要がある場合は、ターミナルから 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

VS Code／Claude の MCP 設定の代わりに npx で起動しないでください。通常の使用では、設定に基づくサーバーの起動は MCP クライアントに任せてください。

npm install と npm start を使用する場合

通常のクライアント利用ではなく、このリポジトリで作業する場合（開発者／メンテナーのワークフロー）に使用してください。

次の用途に使用します。

1. このリポジトリでソースファイルを編集中のローカル開発
2. コミット／リリース前のテスト実行
3. 未公開のローカル変更のデバッグ

一般的なローカルワークフロー：

npm install
npm test
npm start

VS Code／Claude の MCP 設定がすでに機能している場合、通常は手動で npm start を実行する必要はありません。

CLI（公開済みパッケージ）

# 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 が不安定な場合は、グローバルにインストールして "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 リリースノートを作成します。

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 のソースデータを基にした正規のリポジトリ）。
• データセットの使用には、引き続きソースの利用条件および適用されるポリシーが適用されます。