{"_id":"@darwinphi/ph-schools-mcp-server","_rev":"4-c2cd2011b4644cff3f8929d777b575cd","name":"@darwinphi/ph-schools-mcp-server","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@darwinphi/ph-schools-mcp-server","version":"1.0.0","keywords":["mcp","model-context-protocol","philippines","schools","dataset"],"author":{"name":"darwinphi"},"license":"ISC","_id":"@darwinphi/ph-schools-mcp-server@1.0.0","maintainers":[{"name":"darwinphi","email":"darwinmanalophi@gmail.com"}],"homepage":"https://github.com/darwinphi/ph-schools-mcp-server#readme","bugs":{"url":"https://github.com/darwinphi/ph-schools-mcp-server/issues"},"bin":{"ph-schools-mcp-server":"src/cli.js"},"dist":{"shasum":"93342d8deec07a93575a9564b73798cd46acfaaa","tarball":"https://registry.npmjs.org/@darwinphi/ph-schools-mcp-server/-/ph-schools-mcp-server-1.0.0.tgz","fileCount":11,"integrity":"sha512-w5PEPMAN6PUNWQCxXeE6GMtPq84aIdV3bQINOMauzveaE/jVH+0IOP0KtM3oBQIr9H+bLf/w3m5nx9ONN3MZsA==","signatures":[{"sig":"MEQCIFJJHZNKy0V6FzuV3QoE6U+yOnCSpmqU+I/NSsf+B2WUAiASU6ZdNblaTigaNREq8l7X0Ok7JWQkVnxUGff6cc4rGA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27903},"main":"src/server.js","engines":{"node":">=18"},"gitHead":"e6c39f657f17c290adac68d4147a0cfdc1b45d25","mcpName":"io.github.darwinphi/ph-schools","scripts":{"test":"npm run check && node test/run-tests.js","check":"node --check src/cli.js && node --check src/server.js && node --check src/mcp-server.js && node --check src/store.js && node --check src/dataset.js && node --check src/sync.js && node --check src/constants.js && node --check scripts/sync-data.mjs && node --check scripts/check-pack.mjs && node --check scripts/verify-release.mjs && node --check test/run-tests.js && node --check test/store.test.js && node --check test/dataset-load.test.js && node --check test/sync.test.js && node --check test/mcp.integration.test.js","start":"node src/cli.js start","sync-data":"node src/cli.js sync-data","test:unit":"npm run check && node test/run-tests.js --suite unit","test:package":"node scripts/check-pack.mjs","release:verify":"node scripts/verify-release.mjs","test:integration":"npm run check && node test/run-tests.js --suite integration"},"_npmUser":{"name":"darwinphi","email":"darwinmanalophi@gmail.com"},"repository":{"url":"git+https://github.com/darwinphi/ph-schools-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for querying the Philippine schools dataset","directories":{},"_nodeVersion":"22.17.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ph-schools-mcp-server_1.0.0_1775808563165_0.6112313061436607","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@darwinphi/ph-schools-mcp-server","version":"1.0.1","keywords":["mcp","model-context-protocol","philippines","schools","dataset"],"author":{"name":"darwinphi"},"license":"ISC","_id":"@darwinphi/ph-schools-mcp-server@1.0.1","maintainers":[{"name":"darwinphi","email":"darwinmanalophi@gmail.com"}],"homepage":"https://github.com/darwinphi/ph-schools-mcp-server#readme","bugs":{"url":"https://github.com/darwinphi/ph-schools-mcp-server/issues"},"bin":{"ph-schools-mcp-server":"src/cli.js"},"dist":{"shasum":"713060cd8f63accaabee5dc16dcb4e9391b0c6d1","tarball":"https://registry.npmjs.org/@darwinphi/ph-schools-mcp-server/-/ph-schools-mcp-server-1.0.1.tgz","fileCount":11,"integrity":"sha512-JVZ6BhmPBv8rOw6r/66wsDKgazYm4cmC/eM+b0vnGjegKr5C2ROqpSU6FUzp/CJFDyRwSWOrAZk5DI4NtF/qdQ==","signatures":[{"sig":"MEYCIQCEveovs+CdGN7VAbjA0cqvN3r3EtWO7L/4ePDSBqz/pwIhAMl9Y61nXnJdzJxZ3O+gjahZZLcN8EFZsnAHqji2S5jX","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@darwinphi%2fph-schools-mcp-server@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":27903},"main":"src/server.js","engines":{"node":">=18"},"gitHead":"edc6e7c2ee39dbb45bca11aa3116a27fc8bef34f","mcpName":"io.github.darwinphi/ph-schools","scripts":{"test":"npm run check && node test/run-tests.js","check":"node --check src/cli.js && node --check src/server.js && node --check src/mcp-server.js && node --check src/store.js && node --check src/dataset.js && node --check src/sync.js && node --check src/constants.js && node --check scripts/sync-data.mjs && node --check scripts/check-pack.mjs && node --check scripts/verify-release.mjs && node --check test/run-tests.js && node --check test/store.test.js && node --check test/dataset-load.test.js && node --check test/sync.test.js && node --check test/mcp.integration.test.js","start":"node src/cli.js start","sync-data":"node src/cli.js sync-data","test:unit":"npm run check && node test/run-tests.js --suite unit","test:package":"node scripts/check-pack.mjs","release:verify":"node scripts/verify-release.mjs","test:integration":"npm run check && node test/run-tests.js --suite integration"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:96a1fd74-9f06-4073-8c9b-4308029532e9"}},"repository":{"url":"git+https://github.com/darwinphi/ph-schools-mcp-server.git","type":"git"},"_npmVersion":"11.11.0","description":"MCP server for querying the Philippine schools dataset","directories":{},"_nodeVersion":"24.14.1","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ph-schools-mcp-server_1.0.1_1775808869963_0.28297829093030047","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@darwinphi/ph-schools-mcp-server","version":"1.0.2","keywords":["mcp","model-context-protocol","philippines","schools","dataset"],"author":{"name":"darwinphi"},"license":"ISC","_id":"@darwinphi/ph-schools-mcp-server@1.0.2","maintainers":[{"name":"darwinphi","email":"darwinmanalophi@gmail.com"}],"homepage":"https://github.com/darwinphi/ph-schools-mcp-server#readme","bugs":{"url":"https://github.com/darwinphi/ph-schools-mcp-server/issues"},"bin":{"ph-schools-mcp-server":"src/cli.js"},"dist":{"shasum":"4c7375555c3ff9cffda0bd5575449cf6ceea476a","tarball":"https://registry.npmjs.org/@darwinphi/ph-schools-mcp-server/-/ph-schools-mcp-server-1.0.2.tgz","fileCount":11,"integrity":"sha512-EHwB2SDps0AX/SJnNmPoYYpfIrchBTOGO+B9p1ylm06hquw/Af78YEiTN5h7Ljllv5MkvdZupfBqvR5c2Ujn6g==","signatures":[{"sig":"MEYCIQDA9Xoeo+bD3luCz2RMtOp0CN7B/Lf0UPqY8LZog9S8hgIhALz8S2dADRBxBmslLLe1Gof9v3aiYKgv0CzvOtSANTIW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@darwinphi%2fph-schools-mcp-server@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":32145},"main":"src/server.js","engines":{"node":">=18"},"gitHead":"2d23553015b62cdbe5690019c7a2c3f7bf8c07c9","mcpName":"io.github.darwinphi/ph-schools","scripts":{"test":"npm run check && node test/run-tests.js","check":"node --check src/cli.js && node --check src/server.js && node --check src/mcp-server.js && node --check src/store.js && node --check src/dataset.js && node --check src/sync.js && node --check src/constants.js && node --check scripts/sync-data.mjs && node --check scripts/check-pack.mjs && node --check scripts/verify-release.mjs && node --check test/run-tests.js && node --check test/store.test.js && node --check test/dataset-load.test.js && node --check test/dataset-hybrid.test.js && node --check test/sync.test.js && node --check test/mcp.integration.test.js","start":"node src/cli.js start","sync-data":"node src/cli.js sync-data","test:unit":"npm run check && node test/run-tests.js --suite unit","test:package":"node scripts/check-pack.mjs","release:verify":"node scripts/verify-release.mjs","test:integration":"npm run check && node test/run-tests.js --suite integration"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:96a1fd74-9f06-4073-8c9b-4308029532e9"}},"repository":{"url":"git+https://github.com/darwinphi/ph-schools-mcp-server.git","type":"git"},"_npmVersion":"11.11.0","description":"MCP server for querying the Philippine schools dataset","directories":{},"_nodeVersion":"24.14.1","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ph-schools-mcp-server_1.0.2_1775812736122_0.9980220690688961","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@darwinphi/ph-schools-mcp-server","version":"1.0.3","description":"MCP server for querying the Philippine schools dataset","license":"ISC","main":"src/server.js","bin":{"ph-schools-mcp-server":"src/cli.js"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/darwinphi/ph-schools-mcp-server.git"},"homepage":"https://github.com/darwinphi/ph-schools-mcp-server#readme","bugs":{"url":"https://github.com/darwinphi/ph-schools-mcp-server/issues"},"engines":{"node":">=18"},"mcpName":"io.github.darwinphi/ph-schools","scripts":{"start":"node src/cli.js start","sync-data":"node src/cli.js sync-data","check":"node --check src/cli.js && node --check src/server.js && node --check src/mcp-server.js && node --check src/store.js && node --check src/dataset.js && node --check src/sync.js && node --check src/constants.js && node --check scripts/sync-data.mjs && node --check scripts/check-pack.mjs && node --check scripts/verify-release.mjs && node --check test/run-tests.js && node --check test/store.test.js && node --check test/dataset-load.test.js && node --check test/dataset-hybrid.test.js && node --check test/sync.test.js && node --check test/mcp.integration.test.js","test":"npm run check && node test/run-tests.js","test:unit":"npm run check && node test/run-tests.js --suite unit","test:integration":"npm run check && node test/run-tests.js --suite integration","test:package":"node scripts/check-pack.mjs","release:verify":"node scripts/verify-release.mjs"},"keywords":["mcp","model-context-protocol","philippines","schools","dataset"],"author":{"name":"darwinphi"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.3.6"},"gitHead":"55dc8d3c0300c61ce48f9986637e87628c1d3b88","_id":"@darwinphi/ph-schools-mcp-server@1.0.3","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-Sesa8BGwI0Ene6BrzMjrTwaZ8Txza6/DtZRHpJDVTx+dDFr5H8a39Q8xlbXC5sPbNOgVnFEUOhwFDpmn4FlE0g==","shasum":"8786e9e33d308882a59f61f5a790506d08a15d27","tarball":"https://registry.npmjs.org/@darwinphi/ph-schools-mcp-server/-/ph-schools-mcp-server-1.0.3.tgz","fileCount":11,"unpackedSize":32699,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@darwinphi%2fph-schools-mcp-server@1.0.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDivL/llL9j+qEPyR8qT8J952/SIi3Zrl6VcOqXOWG/oQIhAMOmXqBMTEcUp8oUxyaM1VKXTWYOibrUBxumdbSXfhhT"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6665fa06-5189-446a-8d4a-11f06d2109b7"}},"directories":{},"maintainers":[{"name":"darwinphi","email":"darwinmanalophi@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ph-schools-mcp-server_1.0.3_1775904225501_0.2729940238382853"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-10T08:09:23.088Z","modified":"2026-04-11T10:43:45.923Z","1.0.0":"2026-04-10T08:09:23.284Z","1.0.1":"2026-04-10T08:14:30.103Z","1.0.2":"2026-04-10T09:18:56.247Z","1.0.3":"2026-04-11T10:43:45.679Z"},"bugs":{"url":"https://github.com/darwinphi/ph-schools-mcp-server/issues"},"author":{"name":"darwinphi"},"license":"ISC","homepage":"https://github.com/darwinphi/ph-schools-mcp-server#readme","keywords":["mcp","model-context-protocol","philippines","schools","dataset"],"repository":{"type":"git","url":"git+https://github.com/darwinphi/ph-schools-mcp-server.git"},"description":"MCP server for querying the Philippine schools dataset","maintainers":[{"name":"darwinphi","email":"darwinmanalophi@gmail.com"}],"readme":"# 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","readmeFilename":"README.md"}