PH Schools MCP Server

Local stdio MCP server for querying and analyzing the Philippine schools masterlist dataset.

What This Server Provides

Tools:

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

Install and Run

npm install
npm start

Use npm start only when running from this repo manually.

Which Setup to Use

• VS Code MCP (.vscode/mcp.json): enough for normal usage. If status is Running, VS Code already started the server.
• Claude Desktop (claude_desktop_config.json): enough for normal usage. Restart Claude after config changes.
• npx -y @darwinphi/ph-schools-mcp-server ...: one-off CLI usage without cloning repo.
• npm install && npm start: local development/maintenance in this repository.

Usage Scenarios

1. mcp.json configured, no manual npx: works for chat tool calls (dataset_stats, search_schools, etc.).
2. Manual npx -y @darwinphi/ph-schools-mcp-server, no MCP client config: server process starts, but chat clients won't use it automatically.
3. mcp.json configured plus manual npx start: usually unnecessary; let the MCP client manage start/stop.
4. One-off commands without MCP chat: use npx ... --help or npx ... sync-data ....

Without MCP client config, automatic VS Code/Claude tool-calling will not work.

When to Use mcp.json

Use mcp.json for normal day-to-day MCP usage in VS Code (or equivalent client config in Claude Desktop).

Use it for:

1. Automatic server startup and lifecycle management by the MCP client
2. MCP tool usage directly from chat prompts (dataset_stats, search_schools, etc.)
3. Team/project-level shared MCP setup in a workspace

If MCP status shows Running, the client already started the server; manual npm start or manual npx start is usually unnecessary.

When to Use npx

Use npx from a terminal when you need one-off CLI actions without cloning or developing this repo.

Use it for:

1. Sanity check that the published package runs: npx -y @darwinphi/ph-schools-mcp-server --help
2. Manual dataset download/update: npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"
3. Manual debug startup outside client-managed MCP lifecycle: npx -y @darwinphi/ph-schools-mcp-server

Do not use npx start as a replacement for VS Code/Claude MCP config. In normal usage, let the MCP client manage server startup from its config.

When to Use npm install and npm start

Use these when working from this repository (developer/maintainer workflow), not for normal client usage.

Use them for:

1. Local development while editing source files in this repo
2. Running tests before commits/releases
3. Debugging local unpublished changes

Typical local workflow:

npm install
npm test
npm start

If your VS Code/Claude MCP config is already working, you usually do not need to run npm start manually.

CLI (published package)

# 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"

Quick Verify

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"

Dataset Configuration

This server is hybrid by default:

• If local dataset file exists, it uses that file immediately.
• If local dataset file is missing, it auto-downloads from the canonical dataset URL and caches locally.

Default canonical URL (pinned tag v1.0.1):

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

Runtime env vars:

• PH_SCHOOLS_DATA_PATH: preferred local JSON file path (used directly if present; auto-synced to this path if missing)
• PH_SCHOOLS_DATA_URL: override download URL for sync-data
• `PH

... View full README on GitHub