# Commonwealth-MCP

> An MCP server that lets AI assistants look things up in Virginia's
> government records. Every answer names the government system it came
> from and when it was fetched.

Independent project. Not affiliated with or maintained by the Commonwealth
of Virginia.

Virginia has 133 counties and independent cities, and each publishes its
records its own way. This project does the per-locality work once and
exposes the result through the Model Context Protocol.

## What it answers today

Fifteen tools, nine of them in the default set and thirteen in discovery.

- Which local government covers a place, by name, FIPS code, street
  address, ZIP code, or coordinates. Ambiguous names return every match
  rather than a guess: Fairfax City is not inside Fairfax County, and none
  of Virginia's 38 independent cities sit inside the county they share a
  name with. A point inside a town returns the town and its county;
  which of them answers a question depends on the topic.
- What a parcel record says, by parcel ID or by a point. Fairfax County,
  Richmond City, Charles City County, and the Town of Leesburg publish
  their own; VGIN publishes a statewide layer. Where two cover the same ground both are returned,
  unranked, and a disagreement is reported as a disagreement.
- How a parcel is zoned, in Fairfax County, Richmond City, and the Towns
  of Leesburg and Vienna. A point in Vienna returns the town's layer and
  the county's, both unranked. This is
  screening evidence from a county GIS layer. The adopted ordinance
  governs, and the answer says so every time.
- Where a street address is, from the statewide address points. The city
  on an envelope is a postal city and often not the government: mail
  addressed to Alexandria is frequently in Fairfax County.
- What is on the ground and near it: building footprints, road segments
  from two sources that model roads differently, named public places, and
  DEQ's water-quality monitoring stations. Each is one published layer and
  none is an inventory.
- Where a jurisdiction's boundary runs, statewide.
- The text of a Code of Virginia section, by citation, and the Code's
  own table of contents to walk to one you do not have.

Six skills package those into workflows — the order to ask in, and what
an empty answer means at each step:

- `whose-government`: which government covers a place, from a name,
  address, ZIP, or coordinate.
- `parcel-zoning-screen`: a parcel's zoning district and what the record
  does and does not establish.
- `site-context-screen`: what is on and around one piece of ground.
- `coverage-check`: whether a question is answerable for a place before
  asking it, and which of the three empties applies when it is not.
- `code-topic-walk`: reaching a Code of Virginia section by subject when
  the reader has no citation, by walking the Code's own contents.
- `federal-site-screen`: one point screened against Virginia's records and
  the federal flood, wetland and cleanup-site layers on a partner server,
  reported as two halves with their citations kept apart.

They install with the server as a plugin bundle: add the marketplace
`pranava0x0/Commonwealth-MCP` and install `commonwealth-mcp`. For a client
with no plugin system, `commonwealth configure <client>` writes the server
entry alone.

An answer too large to return inline comes back summarised with a
`commonwealth://` handle to everything that was retrieved, readable as an
MCP resource for 24 hours.

## What it does not do

- Zoning outside those four localities. Everywhere else returns
  a registry gap, which is not the same as unzoned land.
- A source of its own for most localities. All 133 counties and
  independent cities and all 189 incorporated towns are in the
  jurisdiction table, so a name or a coordinate anywhere in Virginia finds
  the right government. Three localities publish a parcel layer this
  project reads; the rest are answered by VGIN's statewide layers or not
  at all.
- Full-text search of the Code of Virginia. No public endpoint offers it:
  the publisher's JSON API has no search operation and its own search
  backend was down on 2026-09-08. You can walk the Code's contents to a
  section and read it; you cannot ask which sections mention a word.
- Bills, meetings, permits, finance, or elections. Some are designed and
  unbuilt; the open issues say which.
- Any write. It reads published public records and submits nothing.

## Two kinds of empty

An empty result says which kind it is. Either the records were searched
and nothing matched, or no source is registered for that place. Neither proves that a feature does not exist.

## Setup

Two ways. `uv tool install commonwealth-mcp` gets the server on its own:
the source manifests, the jurisdiction table and the skills ship inside
the package. The examples, the recorded fixtures and the tests are
repo-only, so clone the repository and follow the README for those. Tools
are also callable from Python and the CLI without an AI client.

The package is not on PyPI yet (issue #40), so today the checkout is the
only path that runs.

## Docs

- [README](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/README.md): what works, how to run it
- [Architecture and decisions](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/design/architecture.md): how it is built, and one record per choice with the rejected options kept
- [Design specs](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/design/README.md): the per-feature contract the code is written against
- [Source quirks](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/design/source-quirks.md): things real government data does that its schema does not predict
- [Research](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/research/README.md): the evidence behind the design
- [Contributing](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/CONTRIBUTING.md): how to add a government source
- [Open issues](https://github.com/pranava0x0/Commonwealth-MCP/issues): what is next, by priority label

## Optional

- [Site](https://pranava0x0.github.io/Commonwealth-MCP/): what it answers, the quick start, one recorded walk, and the coverage table
- [Tool reference](https://pranava0x0.github.io/Commonwealth-MCP/tools.html): every tool with the arguments it takes, searchable by name, package, or description
- [Source registry](https://pranava0x0.github.io/Commonwealth-MCP/sources.html): every registered government system, whose terms apply, and what each one does not cover
- [Recorded lookups](https://pranava0x0.github.io/Commonwealth-MCP/examples.html): one call per tool with the full answer, grouped by what each walk demonstrates
- [Run log](https://github.com/pranava0x0/Commonwealth-MCP/blob/main/docs/RUNLOG.md): what happened when