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.0 --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.0 --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.0 --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.0):

https://raw.githubusercontent.com/darwinphi/ph-schools-dataset/v1.0.0/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_SCHOOLS_DATA_TAG: canonical tag for sync-data when URL is not provided

VS Code MCP Config (Copy/Paste)

Set .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"
      }
    }
  }
}

If PH_SCHOOLS_DATA_PATH file is missing, the server automatically downloads from canonical source and writes to that path.

Claude Desktop Config (Copy/Paste)

Update Claude config:

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

Alternative if npx is unreliable in your shell: install globally and use "command": "ph-schools-mcp-server".

If PH_SCHOOLS_DATA_PATH file is missing, the server automatically downloads from canonical source and writes to that path.

Typical macOS config file:

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

Test Commands

npm test
npm run test:package

Example Prompts

• 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".

Publishing and Release Flow

One-time npm setup (Trusted Publishing):

1. On npmjs.com, open package @darwinphi/ph-schools-mcp-server → Settings → Trusted publishers.
2. Add GitHub Actions trusted publisher with:
   • Owner/User: darwinphi
   • Repository: ph-schools-mcp-server
   • Workflow filename: cd.yml
3. Do not use NPM_TOKEN; release workflow uses OIDC (id-token: write).

Manual release flow (v1):

1. Update pinned dataset tag in src/constants.js.
2. Bump package version:

npm version patch   # or minor / major

What npm version patch does:

• Updates package.json version (e.g., 1.0.1 -> 1.0.2)
• Updates package-lock.json version fields
• Creates a git commit
• Creates a git tag (e.g., v1.0.2)

3. Sync server.json version to match package.json.
4. Run:

npm ci
npm test
npm run test:package

5. Push commit and tags:

git push
git push --tags

6. Create GitHub Release notes from the tag:

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

Example:

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

7. Push commit and tags. Tag pushes (v*) automatically trigger CD Release workflow.
8. Workflow publishes npm package, then publishes MCP Registry metadata.

For metadata-only updates, use workflow Publish MCP Registry Metadata.

License and Data Provenance

• Code license: ISC (LICENSE).
• Dataset source: darwinphi/ph-schools-dataset (canonical repository backed by gov.ph source data).
• Use of dataset remains subject to source terms and applicable policies.