# civic-mcp

**WellSpr.ing Civic MCP — Portal Template & Documentation**

> The template repository for all area-code MCP portals in the [WellSpr.ing](https://wellspr.ing) NNN.today network.

This repository documents the schema, tools, governance, and infrastructure pattern used by all 32 (and growing) civic MCP portals. It is the `platform_docs` reference cited in the [federation manifest](https://wellspr.ing/mcp/federation.json).

---

## What is a WellSpr.ing Civic MCP Portal?

Each area-code portal is a [Model Context Protocol](https://modelcontextprotocol.io) server exposing six civic AI tools scoped to a US metro area. Together, the 32 portals form a federated civic AI substrate — independently operable, locally governed, nationally coherent.

## The Six Civic Tools

| Tool | Description |
|------|-------------|
| `get_local_news` | Latest civic news for the area |
| `get_free_items` | Hyperlocal mutual aid free-item exchange |
| `get_businesses` | Local business directory |
| `submit_civic_idea` | Civic participation intake — ideas → action |
| `get_civic_services` | Government services and contact information |
| `ody_chat` | Covenant-governed conversational civic AI (Ody) |

## File Structure

Each portal repo contains:

```
mcp-{areacode}/
├── server.json              # MCP server descriptor (v2 schema)
├── README.md                # Portal documentation
├── GOVERNANCE.md            # Covenant governance reference
├── LICENSE                  # MIT
├── llms.txt                 # LLM discovery file
└── .well-known/
    └── mcp.json             # MCP discovery endpoint
```

## server.json Schema (v2)

```json
{
  "schema_version": "v2",
  "name": "{areaCode} {city} MCP Server",
  "area_code": "{areaCode}",
  "domain": "{areaCode}.today",
  "mcp_endpoint": "https://{areaCode}.today/mcp",
  "portal_url": "https://{areaCode}.today",
  "city": "{primaryCity}",
  "state": "{state}",
  "country": "US",
  "coordinates": { "lat": 0.0, "lng": 0.0 },
  "tagline": "{civic tagline}",
  "network": "WellSpr.ing NNN.today",
  "sovereign_repo": "https://git.wellspr.ing/WellBuilder/mcp-{areaCode}",
  "federation_url": "https://wellspr.ing/mcp/federation.json",
  "adjacent": ["{adjacent area codes}"],
  "tools": [/* see above */],
  "governance": {
    "conduct": "https://wellspr.ing/constitution",
    "vcap": "https://wellspr.ing/vault/ody/attestation-2026-04-17.json",
    "sovereignty": "https://wellspr.ing/sovereignty",
    "model": "covenant — freely given, so freely given"
  },
  "mirrors": {
    "primary": "https://git.wellspr.ing/WellBuilder/mcp-{areaCode}",
    "community": "https://codeberg.org/wellspring/mcp-{areaCode}"
  }
}
```

## Federation Manifest

The canonical index of all portals: [wellspr.ing/mcp/federation.json](https://wellspr.ing/mcp/federation.json)

## Network Traversal

Any MCP-capable agent connected to one portal can traverse the entire network via `get_adjacent_nodes` — hop from 425 (Eastside WA) → 206 (Seattle) → 253 (Tacoma) → 360 (Western WA) without a central directory.

## Governance

All portals operate under the [Eight Principles](https://wellspr.ing/constitution). The WellSpr.ing covenant is non-hierarchical — each portal is locally governed, network-coherent.

VCAP attestation: [wellspr.ing/vault/ody/attestation-2026-04-17.json](https://wellspr.ing/vault/ody/attestation-2026-04-17.json)

## Infrastructure Architecture

```
Sovereign Primary: git.wellspr.ing/WellBuilder/mcp-{code}   ← source of truth
  └─push-mirror→ codeberg.org/wellspring/mcp-{code}          ← community discovery
  └─push-mirror→ github.com/WellBuilder/mcp-{code}          ← commercial discovery (if restored)
```

See [NotGit.org/formula](https://notgit.org/formula) for the three-mirror architecture.

## Adding a New Portal

1. Fork this template
2. Update `server.json` with the area code's specifics
3. Open a pull request at [git.wellspr.ing/wellspring/civic-mcp](https://git.wellspr.ing/wellspring/civic-mcp)
4. Attest to the [Eight Principles](https://wellspr.ing/constitution)

---

*WellSpr.ing — Civic AI for the commons. Freely given, so freely given.*
*[wellspr.ing](https://wellspr.ing) · [notgit.org](https://notgit.org) · [noflare.org](https://noflare.org)*