docs: provision README.md [WellSpr.ing auto]
This commit is contained in:
WellBuilder Admin
parent
b909bc991f
commit
b55fa83f32
1 changed files with 106 additions and 1 deletions
107
README.md
107
README.md
|
|
@ -1,3 +1,108 @@
|
||||||
# civic-mcp
|
# civic-mcp
|
||||||
|
|
||||||
WellSpr.ing Civic MCP Portal Template & Documentation
|
**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)*
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue