{"_id":"@aaronzara/psgc-mcp","_rev":"2-4295fbdf385e7be45c53c4d0da638103","name":"@aaronzara/psgc-mcp","dist-tags":{"latest":"1.4.2"},"versions":{"1.3.0":{"name":"@aaronzara/psgc-mcp","version":"1.3.0","keywords":["mcp","philippines","psgc","barangay","philippine-geography","psa","cloudflare-workers"],"author":{"name":"Aaron Zara","email":"aaron.zara@godmode.ph"},"license":"MIT","_id":"@aaronzara/psgc-mcp@1.3.0","maintainers":[{"name":"aaronzara","email":"aaron.zara@godmode.ph"}],"homepage":"https://godmode.ph","bugs":{"url":"https://github.com/GodModeArch/psgc-mcp/issues"},"dist":{"shasum":"600323416b93e9fbb5b63f7f513cadc207925693","tarball":"https://registry.npmjs.org/@aaronzara/psgc-mcp/-/psgc-mcp-1.3.0.tgz","fileCount":3,"integrity":"sha512-Cf6R4fMzOJ7AFP6jvYG7K2ctLE6rSEIQ89Ltm5H3CgAVeJxvBqVStrI5msdKyPrxS5q1L2TUdWlRG+2cFnui2w==","signatures":[{"sig":"MEUCIQCeNE83Ud1aPa5rfjor/QFl3J05rqRyzmmhlnf31nzLCQIgM0Ru+g4ceFlsZ8/Jz0TwnViwzjgVroqXtYc7WMfxVks=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12565},"gitHead":"f56e17545d2337bfe95dbeb3fc33d3a1d2c181e8","private":false,"scripts":{"dev":"wrangler dev","test":"vitest run","start":"wrangler dev","deploy":"wrangler deploy","test:all":"npm run test && npm run test:integration","diff-psgc":"tsx scripts/diff-psgc.ts","upload-kv":"tsx scripts/upload-kv.ts","cf-typegen":"wrangler types","parse-psgc":"tsx scripts/parse-psgc.ts","test:watch":"vitest","type-check":"tsc --noEmit","test:integration":"vitest run --config vitest.integration.config.ts"},"_npmUser":{"name":"aaronzara","email":"aaron.zara@godmode.ph"},"repository":{"url":"git+https://github.com/GodModeArch/psgc-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server providing Philippine Standard Geographic Code (PSGC) data to AI agents. Data sourced directly from PSA quarterly publications.","directories":{},"_nodeVersion":"20.19.5","dependencies":{"zod":"^4.3.6","agents":"^0.5.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.2.4","exceljs":"^4.4.0","wrangler":"^4.67.0","typescript":"5.9.3","@cloudflare/vitest-pool-workers":"^0.12.18"},"_npmOperationalInternal":{"tmp":"tmp/psgc-mcp_1.3.0_1772717257020_0.07208716875364307","host":"s3://npm-registry-packages-npm-production"}},"1.4.2":{"name":"@aaronzara/psgc-mcp","version":"1.4.2","private":false,"description":"MCP server providing Philippine Standard Geographic Code (PSGC) data to AI agents. Data sourced directly from PSA quarterly publications.","author":{"name":"Aaron Zara","email":"aaron.zara@godmode.ph"},"homepage":"https://godmode.ph","repository":{"type":"git","url":"git+https://github.com/GodModeArch/psgc-mcp.git"},"license":"MIT","keywords":["mcp","philippines","psgc","barangay","philippine-geography","psa","cloudflare-workers"],"scripts":{"deploy":"wrangler deploy","dev":"wrangler dev","start":"wrangler dev","cf-typegen":"wrangler types","type-check":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:integration":"vitest run --config vitest.integration.config.ts","test:all":"npm run test && npm run test:integration","parse-psgc":"tsx scripts/parse-psgc.ts","diff-psgc":"tsx scripts/diff-psgc.ts","upload-kv":"tsx scripts/upload-kv.ts"},"dependencies":{"agents":"^0.5.0","zod":"^4.3.6"},"devDependencies":{"@cloudflare/vitest-pool-workers":"^0.12.18","exceljs":"^4.4.0","tsx":"^4.19.0","typescript":"5.9.3","vitest":"^3.2.4","wrangler":"^4.67.0"},"_id":"@aaronzara/psgc-mcp@1.4.2","gitHead":"d65a88e900038c27d67bf280b8d9515bbcf7f83a","bugs":{"url":"https://github.com/GodModeArch/psgc-mcp/issues"},"_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-EC6Q2I3Ku4Pryxf6g7cJGK9dsIbBIyQJiQ7711eP4Hj9c7ERT4IuOfGZ0rWlbHhDBjOWj4YsVVyP+G1dTjoWIw==","shasum":"5e9bc78fbb27608b8eeef0ca6e675c909a472d3f","tarball":"https://registry.npmjs.org/@aaronzara/psgc-mcp/-/psgc-mcp-1.4.2.tgz","fileCount":3,"unpackedSize":12896,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB068s9iMH9kCiFKuWLFTrPnxSP9vje3qnAzcHLJAsh2AiA082Sk9dxYqpjnM54JfVcMXdZsnOzPTxtXNqyhmN+jqQ=="}]},"_npmUser":{"name":"aaronzara","email":"aaron.zara@godmode.ph"},"directories":{},"maintainers":[{"name":"aaronzara","email":"aaron.zara@godmode.ph"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/psgc-mcp_1.4.2_1773278429559_0.12751302208628656"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T13:27:36.929Z","modified":"2026-03-12T01:20:29.851Z","1.3.0":"2026-03-05T13:27:37.168Z","1.4.2":"2026-03-12T01:20:29.736Z"},"bugs":{"url":"https://github.com/GodModeArch/psgc-mcp/issues"},"author":{"name":"Aaron Zara","email":"aaron.zara@godmode.ph"},"license":"MIT","homepage":"https://godmode.ph","keywords":["mcp","philippines","psgc","barangay","philippine-geography","psa","cloudflare-workers"],"repository":{"type":"git","url":"git+https://github.com/GodModeArch/psgc-mcp.git"},"description":"MCP server providing Philippine Standard Geographic Code (PSGC) data to AI agents. Data sourced directly from PSA quarterly publications.","maintainers":[{"name":"aaronzara","email":"aaron.zara@godmode.ph"}],"readme":"# PSGC MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@aaronzara/psgc-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/@aaronzara/psgc-mcp)\n![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-F38020?logo=cloudflare&logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)\n![License: MIT](https://img.shields.io/badge/License-MIT-green)\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) server that provides Philippine Standard Geographic Code (PSGC) data to LLMs. Built on Cloudflare Workers with KV storage.\n\nPublic, read-only, no authentication required. Data sourced directly from the [Philippine Statistics Authority](https://psa.gov.ph/classification/psgc/) quarterly PSGC publication. Cached in Cloudflare KV for reliability and low-latency global access.\n\n\n \"psgc-mcp\n\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `lookup` | Fetch a geographic entity by its 10-digit PSGC code |\n| `search` | Search entities by name with optional level filter and strict mode |\n| `get_hierarchy` | Get the full administrative chain (barangay to region) |\n| `list_children` | List direct children of a parent entity |\n| `list_by_type` | List all entities at a given geographic level |\n| `batch_lookup` | Look up multiple entities in one call (max 50 codes) |\n| `query_by_population` | Query entities by population range with sorting and filtering |\n\n### Geographic Levels\n\n| Level | Description | Count |\n|-------|-------------|-------|\n| `Reg` | Region | 18 |\n| `Prov` | Province | 82 |\n| `Dist` | District (NCR only) | 4 |\n| `City` | City | 149 |\n| `Mun` | Municipality | 1,493 |\n| `SubMun` | Sub-Municipality (Manila only) | 16 |\n| `SGU` | Special Geographic Unit (BARMM) | ~8 |\n| `Bgy` | Barangay | ~42,000 |\n\n## Response Format\n\nAll data responses are wrapped in a standard envelope:\n\n```json\n{\n \"_meta\": {\n \"dataset_version\": \"PSGC Q4 2025\",\n \"dataset_date\": \"2025-12-31\",\n \"last_synced\": \"2026-03-02\",\n \"source\": \"Philippine Statistics Authority (PSA)\",\n \"source_url\": \"https://psa.gov.ph/classification/psgc/\"\n },\n \"data\": { ... }\n}\n```\n\nError responses (`isError: true`) and informational messages (e.g. \"No children found\") are returned as plain text without wrapping.\n\n### Entity Schema\n\nEntity objects returned by `lookup`, `get_hierarchy`, `list_children`, `list_by_type`, `batch_lookup`, and `query_by_population` use snake_case field names:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `psgc_code` | `string` | 10-digit PSGC code |\n| `name` | `string` | Official place name |\n| `level` | `string` | Geographic level (Reg, Prov, Dist, City, Mun, SubMun, SGU, Bgy) |\n| `old_name` | `string \\| null` | Previous name, if renamed |\n| `city_class` | `string \\| null` | City classification: HUC, ICC, CC, or null |\n| `income_class` | `string \\| null` | Income classification (1st through 6th) |\n| `urban_rural` | `string \\| null` | Urban/Rural classification (barangays only) |\n| `population` | `number \\| null` | 2024 Census population count |\n| `parent_code` | `string \\| null` | PSGC code of parent entity |\n\nAll fields are always present. Fields without data are `null`, never omitted.\n\n### Search Results\n\nThe `search` tool returns a lighter result object:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `psgc_code` | `string` | 10-digit PSGC code |\n| `name` | `string` | Official place name |\n| `level` | `string` | Geographic level |\n\n### Strict Search\n\nThe `search` tool accepts an optional `strict` boolean parameter. When `strict: true`, only exact name matches are returned (after normalization). Partial and substring matches are excluded. Useful when you know the exact place name and want to avoid ambiguous results.\n\n### Batch Lookup\n\nThe `batch_lookup` tool accepts an array of 1-50 PSGC codes and returns results in the same order as input. Codes not found return `null` at their position.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `results` | `(Entity \\| null)[]` | Entities in input order, `null` for not found |\n| `found` | `number` | Count of codes that resolved |\n| `not_found` | `number` | Count of codes that returned null |\n| `total` | `number` | Total codes requested |\n\n### Query by Population\n\nThe `query_by_population` tool finds entities within a population range, sorted by population. Useful for questions like \"largest cities in Region III\" or \"municipalities under 50,000 people.\"\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `level` | `string` | Yes | Geographic level to query |\n| `parent_code` | `string` | Bgy only | Scope results to a parent entity (prefix matching). Required for barangays. |\n| `min_population` | `number` | No | Minimum population (inclusive) |\n| `max_population` | `number` | No | Maximum population (inclusive) |\n| `sort` | `asc \\| desc` | No | Sort order (default: `desc`) |\n| `limit` | `number` | No | Max results, 1-100 (default: 10) |\n\nResponse includes `results` (entity array), `total_matching` (total before limit), and `returned` (actual count returned). Entities with null population are excluded.\n\n## Connect\n\nAdd to your MCP client configuration:\n```json\n{\n \"mcpServers\": {\n \"psgc\": {\n \"url\": \"https://psgc.godmode.ph/mcp\"\n }\n }\n}\n```\n\n### Quick test\n```bash\ncurl -X POST https://psgc.godmode.ph/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"search\",\n \"arguments\": { \"query\": \"Carmona\", \"level\": \"Mun\" }\n }\n }'\n```\n\n## PSGC Code Format\n\nPSGC codes are 10 digits with no spaces. The segments encode the full geographic hierarchy:\n```\n1 4 0 2 1 0 0 0 0 0\n│ │ └─┬─┘ └─┬─┘ └─┬─┘\n│ │ │ │ └── Barangay (last 3 digits)\n│ │ │ └──────── Municipality/City (3 digits)\n│ │ └────────────── Province (2 digits)\n│ └────────────────── Island Group modifier\n└──────────────────── Region (1 digit)\n```\n\nLeading zeros are significant — `014021000000` and `14021000000` are different codes. Always use the full 10-digit string.\n\nKnown edge cases:\n- NCR uses **Districts** instead of Provinces (`Dist` level)\n- Cotabato City is administratively in BARMM but geographically in Region XII — it appears under `Prov` code `124700000` (Maguindanao del Norte)\n- BARMM Special Geographic Units (`SGU`) don't follow the standard hierarchy and have no Province parent\n\n## Data Sources\n\n| Source | Vintage | Description |\n|--------|---------|-------------|\n| [PSA PSGC Publication](https://psa.gov.ph/classification/psgc/) | Q4 2025 (January 13, 2026) | Geographic codes, names, levels, classifications |\n| [2024 Census of Population](https://psa.gov.ph/population-and-housing) | Proclamation No. 973 | Population counts per entity |\n| PSA PSGC Old Names column | Q4 2025 | Historical/previous place names |\n| PSA PSGC Urban/Rural column | Q4 2025 | Barangay urban/rural classification |\n\nLast synced: March 2, 2026.\n\n## Breaking Changes (v1.1.0+)\n\n- All data responses are now wrapped in `{ _meta, data }`. Consumers must unwrap `data` from the response.\n- Entity field names changed to snake_case: `code` is now `psgc_code`, `parent` is now `parent_code`, `cityClass` is now `city_class`, etc.\n- Search results use `psgc_code` instead of `code`.\n- All entity fields are always present. Previously optional fields now appear as `null` instead of being omitted.\n- Internal fields `regionCode` and `provinceCode` are no longer exposed in API responses.\n\n## Related Projects\n\nPart of a suite of Philippine public data MCP servers:\n\n- **PSGC MCP** (this repo)\n- **[LTS MCP](https://github.com/GodModeArch/lts-mcp)** - DHSUD License to Sell verification\n- **PH Holidays MCP** -> Coming soon\n- **BSP Bank Directory MCP** -> Coming soon\n\nAll servers are free, public, and read-only. Data pulled from official Philippine government sources.\n\n## Contributing and Issues\n\nFound a data error or an edge case that isn't handled? Open an issue. The quirks section above covers the most common ones, but PSGC data has accumulated inconsistencies over decades of LGU reclassifications and the issues list is the best place to track them.\n\nPSA publishes updates quarterly. If the data looks stale, open an issue and it will be refreshed ahead of the next scheduled sync.\n\n## Data Pipeline\n\nThe PSGC data is parsed from PSA's Excel publication and stored in Cloudflare KV. To update:\n\n### 1. Download the PSGC Excel file\n\nGet the latest publication from [PSA PSGC](https://psa.gov.ph/classification/psgc) and place it in `scripts/data/`.\n\n### 2. Diff (optional)\n\n```bash\nnpm run diff-psgc -- \"scripts/data/Q3 2025/PSGC-3Q-2025-Publication-Datafile.xlsx\" \"scripts/data/PSGC-4Q-2025-Publication-Datafile (1).xlsx\"\n```\n\nCompares two quarterly Excel files and reports additions, removals, name changes, and field changes. Run this before the full parse to verify PSA's changelog.\n\n### 3. Parse\n```bash\nnpm run parse-psgc\n```\n\nReads the Excel file, derives parent relationships, and writes chunked JSON files to `scripts/data/output/`.\n\n### 4. Upload to KV\n```bash\nnpm run upload-kv\n```\n\nBulk uploads all JSON chunks to Cloudflare KV via wrangler.\n\n### 5. Deploy\n```bash\nnpm run deploy\n```\n\n## Development\n```bash\nnpm install\nnpm run dev\n```\n\nDev server starts at `http://localhost:8787`. Connect your MCP client to `http://localhost:8787/mcp`.\n\n## Setup\n\nBefore first deploy, create the KV namespace:\n```bash\nnpx wrangler kv namespace create PSGC_KV\n```\n\nUpdate `wrangler.jsonc` with the returned namespace ID.\n\n## Built by\n\n**Aaron Zara** - Fractional CTO at [Godmode Digital](https://godmode.ph)\n\nPreviously built [REN.PH](https://ren.ph), a programmatic real estate platform with 60,000+ structured geographic pages covering every barangay, city, and province in the Philippines. The PSGC MCP came out of needing reliable, queryable PH geography data for AI agents and not finding anything that fit.\n\nFor enterprise SLAs, custom integrations, or other PH data sources:\n→ [godmode.ph](https://godmode.ph)\n\n## License\n\nMIT","readmeFilename":"README.md"}