Civitas

Civitas is an autonomous multi-agent food-procurement system that combines negotiation, evidence-lineage analysis, adaptive replanning, deterministic optimization, and guarded MCP execution. Its target product interface is a Codex-compatible MCP server: operators state a procurement goal conversationally, Codex invokes Civitas's intent-level tools, and Civitas owns the complete planning and safety workflow.

Specialized Parliament agents investigate competing objectives and compare solver-generated procurement alternatives. An evidence-aware Jury then evaluates provenance, genuine source independence, contradictions, and adversarial dissent before an action can pass the execution safety boundary.

The React application is a public landing and installation guide with an optional, read-only evidence and execution-audit route; the MCP server remains the product's primary entry point. The repository includes strict inbound MCP contracts, a deployable MCP composition root, PostgreSQL-backed resumable workflow execution, provider onboarding boundaries, persisted approval and guarded execution, tenant-scoped identity, and a deterministic integration suite. Real provider credentials and transports remain deployment-supplied, and durable clean-room investigation is completed by the next workstream. See MCP_INTERFACE.md, MCP_AGENT_WORKPLAN.md, PLAN.md, AGENTS.md, TECH_STACK.md, and SECURITY.md.

Product interface

The intended deployment has MCP on both sides of the application:

Operator → Codex → Civitas MCP server → planning / Jury / execution services
                                      → procurement-provider MCP servers

Codex is responsible for conversation, intent capture, progress narration, and presenting approval requests. Civitas remains authoritative for typed inputs, evidence retrieval, optimization, Parliament, Jury and Dissent, replanning, freshness revalidation, approval binding, idempotency, and execution audit. A model or chat message cannot bypass those controls.

The primary interaction should be as small as:

User: Protect seven days of demand across our warehouses while minimizing waste.
Codex: Civitas found false consensus on a stale lead-time source and replanned.
       The revised plan has Integrity 92/100 and all hard gates pass.
       Approve the exact plan for execution?

Related MCP server: mendicant-mcp-server

Install the MCP sandbox

The public installer runs a self-contained, side-effect-safe STDIO sandbox. It uses the real intent-level MCP surface, optimizer, Parliament/Jury workflow, approval binding, freshness checks, and duplicate-execution protection, but it cannot contact a supplier or create a live purchase order.

Install uv, then add Civitas to Codex:

codex mcp add civitas -- uvx --from git+https://github.com/minnhaaaaa/civitas civitas-mcp-demo

Or add it to Claude Code for the current user:

claude mcp add civitas --scope user -- uvx --from git+https://github.com/minnhaaaaa/civitas civitas-mcp-demo

Any STDIO-compatible MCP client can use this standard server definition:

{
  "mcpServers": {
    "civitas": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/minnhaaaaa/civitas",
        "civitas-mcp-demo"
      ]
    }
  }
}

The production entry point is civitas-mcp. Users can explicitly route its inventory, demand, supplier, capacity, and purchase-order capabilities across their own local or private MCP servers. Credentials remain environment references on their machine. See provider setup and the deployment guide.

Development

Prerequisites: Python 3.12, uv, Node.js 24, pnpm 10.31.0, and Docker Compose.

uv sync --frozen --all-groups
pnpm install --frozen-lockfile
docker compose up -d postgres
uv run alembic upgrade head

PostgreSQL listens on port 55432 by default to avoid colliding with a local installation. Set CIVITAS_POSTGRES_PORT to override it.

Run the required checks with:

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
pnpm format
pnpm lint
pnpm typecheck
pnpm build

Run the current demonstration API and optional audit viewer locally with:

uv run uvicorn civitas.api.app:create_app --factory --host 127.0.0.1 --port 8001
pnpm --filter @civitas/web dev

The Vite dev server proxies /api requests to http://127.0.0.1:8001.

civitas.api.app:create_app is the local, simulated demonstration API. It uses no live provider and performs no real procurement side effects. Keep it bound to loopback. The persistence-backed API factory in civitas.api.guarded_api requires a bearer token of at least 32 characters and an organization binding when it is composed by a deployment.

Demo

The current end-to-end integration demo is a false-consensus case file. It starts with supplier A winning on shared stale evidence, routes through a clean-room Dissent check, reopens planning, approves supplier B after fresh public evidence, then performs freshness revalidation and duplicate-protected MCP execution.

Run the golden suite with:

uv run pytest tests/golden/test_scenarios.py -q

Run the integration-focused checks with:

uv run pytest tests/integration/test_demo_api.py tests/unit/execution/test_service.py tests/contract/test_mcp_integration.py -q

For the offline viewer demonstration, open http://127.0.0.1:5173, choose False consensus with clean-room dissent, and start the run. The SSE stream is produced while the scenario executes. The event docket should show this sequence:

evidence retrieval
→ Parliament proposal / challenge / concession
→ Jury investigate
→ clean-room Dissent evidence
→ replanning
→ Jury approve
→ freshness revalidation
→ execution succeeded
→ duplicate execution downgraded to duplicate