{
  "markdown": "# PH Schools MCP Server\n\nLocal `stdio` MCP server for querying and analyzing the Philippine schools masterlist dataset.\n\n## What This Server Provides\n\nTools:\n\n1. `search_schools`\n2. `get_school_by_beis_id`\n3. `list_regions`\n4. `list_divisions`\n5. `dataset_stats`\n\n## Install and Run\n\n```bash\nnpm install\nnpm start\n```\n\nUse `npm start` only when running from this repo manually.\n\n## Which Setup to Use\n\n- VS Code MCP (`.vscode/mcp.json`): enough for normal usage. If status is `Running`, VS Code already started the server.\n- Claude Desktop (`claude_desktop_config.json`): enough for normal usage. Restart Claude after config changes.\n- `npx -y @darwinphi/ph-schools-mcp-server ...`: one-off CLI usage without cloning repo.\n- `npm install && npm start`: local development/maintenance in this repository.\n\n## Usage Scenarios\n\n1. `mcp.json` configured, no manual `npx`: works for chat tool calls (`dataset_stats`, `search_schools`, etc.).\n2. Manual `npx -y @darwinphi/ph-schools-mcp-server`, no MCP client config: server process starts, but chat clients won't use it automatically.\n3. `mcp.json` configured plus manual `npx` start: usually unnecessary; let the MCP client manage start/stop.\n4. One-off commands without MCP chat: use `npx ... --help` or `npx ... sync-data ...`.\n\nWithout MCP client config, automatic VS Code/Claude tool-calling will not work.\n\n## When to Use `mcp.json`\n\nUse `mcp.json` for normal day-to-day MCP usage in VS Code (or equivalent client config in Claude Desktop).\n\nUse it for:\n\n1. Automatic server startup and lifecycle management by the MCP client\n2. MCP tool usage directly from chat prompts (`dataset_stats`, `search_schools`, etc.)\n3. Team/project-level shared MCP setup in a workspace\n\nIf MCP status shows `Running`, the client already started the server; manual `npm start` or manual `npx` start is usually unnecessary.\n\n## When to Use `npx`\n\nUse `npx` from a terminal when you need one-off CLI actions without cloning or developing this repo.\n\nUse it for:\n\n1. Sanity check that the published package runs: `npx -y @darwinphi/ph-schools-mcp-server --help`\n2. Manual dataset download/update: `npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output \"$HOME/.ph-schools/data.json\"`\n3. Manual debug startup outside client-managed MCP lifecycle: `npx -y @darwinphi/ph-schools-mcp-server`\n\nDo 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.\n\n## When to Use `npm install` and `npm start`\n\nUse these when working from this repository (developer/maintainer workflow), not for normal client usage.\n\nUse them for:\n\n1. Local development while editing source files in this repo\n2. Running tests before commits/releases\n3. Debugging local unpublished changes\n\nTypical local workflow:\n\n```bash\nnpm install\nnpm test\nnpm start\n```\n\nIf your VS Code/Claude MCP config is already working, you usually do not need to run `npm start` manually.\n\n### CLI (published package)\n\n```bash\n# Start MCP server over stdio\nnpx -y @darwinphi/ph-schools-mcp-server\n\n# Sync canonical dataset once to a chosen path\nnpx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output \"$HOME/.ph-schools/data.json\"\n```\n\n### Quick Verify\n\n```bash\nnpx -y @darwinphi/ph-schools-mcp-server --help\nnpx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output \"$HOME/.ph-schools/data.json\"\n```\n\n## Dataset Configuration\n\nThis server is hybrid by default:\n\n- If local dataset file exists, it uses that file immediately.\n- If local dataset file is missing, it auto-downloads from the canonical dataset URL and caches locally.\n\nDefault canonical URL (pinned tag `v1.0.1`):\n\n`https://raw.githubusercontent.com/darwinphi/ph-schools-dataset/v1.0.1/schools_masterlist_2020_2021.json`\n\nRuntime env vars:\n\n- `PH_SCHOOLS_DATA_PATH`: preferred local JSON file path (used directly if present; auto-synced to this path if missing)\n- `PH_SCHOOLS_DATA_URL`: override download URL for `sync-data`\n- `PH_SCHOOLS_DATA_TAG`: canonical tag for `sync-data` when URL is not provided\n\n## VS Code MCP Config (Copy/Paste)\n\nSet `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"phSchools\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@darwinphi/ph-schools-mcp-server\"],\n      \"env\": {\n        \"PH_SCHOOLS_DATA_PATH\": \"/Users/your-user/.ph-schools/data.json\"\n      }\n    }\n  }\n}\n```\n\nIf `PH_SCHOOLS_DATA_PATH` file is missing, the server automatically downloads from canonical source and writes to that path.\n\n## Claude Desktop Config (Copy/Paste)\n\nUpdate Claude config:\n\n```json\n{\n  \"mcpServers\": {\n    \"ph-schools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@darwinphi/ph-schools-mcp-server\"],\n      \"env\": {\n        \"PH_SCHOOLS_DATA_PATH\": \"/Users/your-user/.ph-schools/data.json\"\n      }\n    }\n  }\n}\n```\n\nAlternative if `npx` is unreliable in your shell: install globally and use `\"command\": \"ph-schools-mcp-server\"`.\n\nIf `PH_SCHOOLS_DATA_PATH` file is missing, the server automatically downloads from canonical source and writes to that path.\n\nTypical macOS config file:\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n## Test Commands\n\n```bash\nnpm test\nnpm run test:package\n```\n\n## Example Prompts\n\n- `Run dataset_stats and summarize key insights.`\n- `List all divisions in Region I using list_divisions.`\n- `Search schools in region \"Region I\" and division \"Ilocos Norte\".`\n- `Get school by BEIS ID 100001 using get_school_by_beis_id.`\n- `Search schools with query \"High School\".`\n\n## Publishing and Release Flow\n\nOne-time npm setup (Trusted Publishing):\n\n1. On npmjs.com, open package `@darwinphi/ph-schools-mcp-server` → Settings → Trusted publishers.\n2. Add GitHub Actions trusted publisher with:\n   - Owner/User: `darwinphi`\n   - Repository: `ph-schools-mcp-server`\n   - Workflow filename: `cd.yml`\n3. Do not use `NPM_TOKEN`; release workflow uses OIDC (`id-token: write`).\n\nManual release flow (v1):\n\n1. Update pinned dataset tag in `src/constants.js`.\n2. Bump package version:\n\n```bash\nnpm version patch   # or minor / major\n```\n\nWhat `npm version patch` does:\n- Updates `package.json` version (e.g., `1.0.1` -> `1.0.2`)\n- Updates `package-lock.json` version fields\n- Creates a git commit\n- Creates a git tag (e.g., `v1.0.2`)\n\n3. Sync `server.json` version to match `package.json`.\n4. Run:\n\n```bash\nnpm ci\nnpm test\nnpm run test:package\n```\n\n5. Push commit and tags:\n\n```bash\ngit push\ngit push --tags\n```\n\n6. Create GitHub Release notes from the tag:\n\n```bash\ngh release create v<new_version> --generate-notes --title \"v<new_version>\"\n```\n\nExample:\n\n```bash\ngh release create v1.0.2 --generate-notes --title \"v1.0.2\"\n```\n\n7. Push commit and tags. Tag pushes (`v*`) automatically trigger `CD Release` workflow.\n8. Workflow publishes npm package, then publishes MCP Registry metadata.\n\nFor metadata-only updates, use workflow `Publish MCP Registry Metadata`.\n\n## License and Data Provenance\n\n- Code license: ISC ([LICENSE](./LICENSE)).\n- Dataset source: `darwinphi/ph-schools-dataset` (canonical repository backed by gov.ph source data).\n- Use of dataset remains subject to source terms and applicable policies.\n",
  "bytes": 7163,
  "sha": "e81dff83b9604e3dd5e8ae0f419f8306d8a08359012e2e61008c1f57c6c3e1f2",
  "repo_slug": "darwinphi/ph-schools-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_darwinphi_ph_schools_562d927d/readme"
}