🚀 Civicnet MCP Server – Model Context Protocol

Welcome to the official open-source MCP Server.
This is the heart of Konstellation & CivicNet’s federated civic infrastructure—a modular, principle-driven server for running local, trusted, and agentic community AI.

---

🧭 What Is the MCP Server?

The MCP Server powers neighborhood, city, or org-level “nodes” in the CivicNet/Konstellation grid. Each node:

- Ingests and validates local data (GIS, policy, community stories, public records)
- Hosts and orchestrates agentic models (reasoning, self-audit, simulation, role-play, etc.)
- Applies civic principles (equity, truth, privacy, transparency) to every query and output
- Publishes secure, documented APIs for dashboards, GIS clients, and external partners
- Federates with other MCP nodes to share knowledge while keeping local control

Why?
So every community can own, govern, and continually improve their own civic intelligence—no black boxes, no vendor lock-in, no silent bias.

---

🌌 Key Features

- LLM-Agnostic: Plug in any modern language model (OpenAI, Anthropic, open source)
- Cloud-Agnostic: Deploy on your cloud, on-prem, edge, or local device
- Principle Repository: Define, audit, and evolve community principles in code
- Modular Agentic Logic: Supports chain-of-thought, self-reflection, role simulation, multi-agent debate, and more
- Data Stewardship: Fine-grained connectors for local, open, and federated civic data
- Simulation-Ready: Run “what-if” scenarios and participatory simulations
- Full Audit Trail: Every output, agent step, and data source is logged and reviewable
- Dockerized: Easy container setup, local or distributed

---

🗃 Directory Overview

| Folder | Purpose |
|----------------|----------------------------------------------|
| src/agents | Agentic models (reasoning, alignment, simulation) |
| src/api | REST/GraphQL APIs for queries, data, tools |
| src/principles | Principle repo (YAML/JSON + logic) |
| src/data | Data ingestion, validation, and connectors |
| src/prompts | Prompt templates and scenario scripts |
| src/simulation | Simulation, scenario modeling logic |
| src/utils | Logging, audit, helper functions |
| config/ | Node config, enabled features, .env template |
| scripts/ | Dev, test, migration scripts |
| tests/ | Unit and integration tests |

---

⚡️ Quickstart (Local Docker Compose)

1. Clone the Repo:

   git clone https://github.com/PublikPrinciple/civicnet-mcp-server.git

   cd civicnet-mcp-server

   

2. Copy and edit your environment variables:

   cp config/.env.example .env
   # Edit .env with your API keys, DB, LLM settings, etc.
   

3. Start the MCP Server (plus optional data services):

   docker-compose up --build
   

4. View API Docs:

Go to http://localhost:4000/docs (Swagger/OpenAPI by default)

All outputs are checked, filtered, or rewritten to align with your community’s core principles (e.g., “ensure equity,” “avoid harm,” “cite sources”).
Update principles via YAML/JSON in /src/principles/.

Chain-of-Thought Agent: Step-by-step logic for transparency
Self-Reflective Agent: Checks its own bias, logic, and compliance
Role Simulation Agent: Simulates debates (planner vs. resident), expert panels, or historical perspectives
Multi-Agent Collaboration: Supports scenario testing, participatory budgeting, and red teaming
Each agent’s logic is modular and composable (see /src/agents/).

Data Layer

Connectors for GIS, census, local CSVs, APIs, and more
Validation/Redaction steps for privacy and data hygiene
Federation: Share/selectively with trusted nodes (opt-in)

All agentic reasoning is driven by prompt templates (see /src/prompts/)
Write your own or use built-in civic case study and simulation templates

Model “what if?” futures (housing, climate, budget, etc.) using real and synthetic data
Outputs are interactive and principle-audited

Generate a “Durham Housing Crisis” case study with maps, timelines, and equity analysis, ready for GIS and public review
Support a participatory budgeting simulation with role-played debate between community agents
Publish a plain-language, principle-aligned data API for local dashboards
Audit all outputs for bias, error, and community principles (with logs and feedback)
Federate with other neighborhoods/cities to compare, remix, and improve local analyses

---

🧑‍💻 For Developers

Languages: TypeScript/Node.js by default, Python agent compatibility in roadmap
Contributing: See CONTRIBUTING.md for branching, code style, and principle-alignment PR checks
Tests: npm test (Jest), or run all with docker-compose -f docker-compose.test.yml up

Principle-Driven Governance: Edit /src/principles/ to update your node’s values
Logs & Audit: Every answer is traceable (who asked, what data, which agents, what checks)
Open APIs: Build your own GIS client, dashboard, or mobile app on top of the MCP Server’s endpoints

---

🔒 Security & Privacy

Sensitive data is never shared or exposed without explicit principle-driven consent and redaction
Each node is sandboxed; federation is always opt-in and auditable

---

🌍 Federation & Constellation

Konstellation Ready: This server is designed to federate—publish/share insights with other communities, cities, or regions while keeping full local governance and privacy
Federated queries: Allow comparisons (e.g., “Show eviction rates across all neighborhoods”)

---

📖 Docs & Community

Full docs in /docs/ or link to civicnet.org/docs
Join the #mcp-server channel on Discord for support and discussion

---

📝 License

AGPL 2.0 – Open, remixable, and community-driven
See LICENSE for details

---

✨ Get Started Building the Future of Civic Infrastructure!

---

📘 Swagger/OpenAPI Setup (API Endpoint Overview)

Add this to /src/api/routes.ts (sample):

import express from 'express';
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const router = express.Router();
const swaggerDocument = YAML.load('./config/swagger.yaml');

router.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
export default router;

Sample swagger.yaml starter:

openapi: 3.0.0
info:
title: MCP Server API
version: 1.0.0
paths:
/api/analyze:
post:
summary: Analyze civic query using agentic logic
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
context:
type: object
responses:
'200':
description: Analysis complete