Personal project · Built and shipped by Ismael Melendez
Plenty of organizations need to answer "which county is this ZIP code in?" — for service-area reporting, grant boundaries, or figuring out where participants actually come from. It sounds simple, and the common shortcut gets it wrong. This project builds a tool that answers it correctly, including the messy cases, and lets an AI assistant look it up directly instead of someone checking by hand.
Short answerZIP codes don't map cleanly onto counties — many cross county lines, so the common one-to-one lookup silently returns wrong answers for service-area reporting or grant boundaries. This project builds a tested lookup that returns every county a ZIP actually touches, and exposes it so an AI assistant can query real data instead of guessing.
The problem
A ZIP code is a postal delivery construct, not a governmental boundary — plenty of ZIP codes cross county lines, and a naive one-to-one lookup silently produces wrong answers for anyone doing geographic analysis, service-area planning, or compliance work tied to county boundaries. Getting this right means handling overlap explicitly rather than picking whichever county happens to come back first.
The second problem was how people would actually use it. A script that one technical person runs on their laptop doesn't help the staff member who needs the answer mid-task. So it was built as a tool an AI assistant can call on its own, in the middle of a conversation — you ask a plain-language question, and it queries real data instead of guessing. (The technical mechanism is the Model Context Protocol, or MCP, a standard way of exposing a tool to AI assistants.)
Architecture
Geographic reference data is pulled from an external API and held in BigQuery, giving the server a queryable, versioned source of truth instead of re-fetching or re-deriving mappings on every call.
Rather than one do-everything endpoint, the server exposes distinct tools — forward lookup (ZIP → county), a batch variant for multiple ZIPs at once, and a reverse lookup (county → ZIPs) — each with a narrow, predictable contract an agent can call correctly without guessing at parameters.
Because ZIP codes can span multiple counties, the server treats overlap as a first-class case rather than an edge case — a lookup returns every county a ZIP actually intersects, with filtering logic to narrow results when a caller needs a single best match instead of the full set.
The lookup and overlap logic is covered by tests — geographic edge cases (ZIPs spanning several counties, invalid or non-existent ZIPs) are exactly the kind of thing that looks correct until a specific real input breaks it.
What it proves
This isn't really a ZIP-code project. It's a template for a broader pattern: taking a fragmented, easy-to-get-subtly-wrong data problem and turning it into a small, well-tested, explainable tool that an AI agent — or a human — can call with confidence. The same shape applies to plenty of messy organizational data problems that aren't about geography at all.
The hard part was never fetching the data. It was deciding what "correct" means when the real world doesn't map cleanly onto the data model — and building tests that hold that decision in place.
If something in your organization's data doesn't line up as cleanly as everyone assumes, that's usually where the real work is.