Cartesi Knowledge MCP Server

Production-minded Model Context Protocol server that exposes curated Cartesi developer resources — including repositories, documentation, articles, and skills — from PostgreSQL to AI agents over streamable HTTP.

Current capabilities

• FastMCP (mcp[cli] 1.26.x) with streamable_http_app() — FastMCP's Starlette app used directly in production so session lifespan runs correctly (see create_app() in src/main.py).

• Async SQLAlchemy + asyncpg for read-only access to the knowledge database.

• Layered layout: config and logging (src/core/), DB session and models (src/db/), repositories, domain service (src/domain/resource_service.py), schemas, formatters, and server modules under src/server/.

• Transport security: DNS rebinding protection and configurable allowed_hosts / allowed_origins in src/server/server.py.

• Plain HTTP health: GET /health returns {"status":"ok"} alongside the MCP route.

Content delivery model

Workflow tools (prepare_cartesi_*, send_input_to_application, prepare_*_deposit_instructions, get_cartesi_app_logic_guidance) return instructions and command templates for the user's machine. They do not run the Cartesi CLI or cast from this server.

Recommended Agent Flow (Skills-First)

1. summarize_knowledge_base          → orientation (counts include skills + articles)
2. list_skills                       → check for a matching skill FIRST (body is inline)
   └─ get_skill(resource_id)         → read body directly — no URL fetch needed; stop here if sufficient
3. [No skill covers task] get_knowledge_taxonomy → discover valid tag/source filter values
4. search_knowledge_resources        → find repos/docs/articles by query+tag+source+kind
   └─ get_article_content(id)        → article bodies are inline (no URL fetch needed)
5. fetch_resource_content(url)       → for documentation/repository pages needing full body

Why skills first? Skills are purpose-built for agent consumption, their body is stored inline in the DB (zero external fetch latency), and they are curated validated procedures — more reliable than interpreting raw docs.

Requirements

• Python ≥ 3.11 (see pyproject.toml; the included Dockerfile uses Python 3.12).

• PostgreSQL database with the schema managed by the mcp-admin-server (includes resources, articles, skills, repositories, doc_routes, tags, sources tables).

Environment variables

Copy .env.example to .env and adjust. Defaults and field names are in src/core/config.py (notably DATABASE_URL, APP_HOST, APP_PORT, MCP_BASE_URL, pagination limits, connection pool settings). For PostgreSQL URLs, postgres://... is normalized to postgresql+asyncpg://..., and sslmode is translated to asyncpg-compatible ssl.

Install

Using uv (recommended):

uv sync

Using pip:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

python -m src.main

uv run python -m src.main

uv run uvicorn src.main:create_app --factory --host 0.0.0.0 --port 8000

The MCP endpoint is streamable HTTP at:

• http://<host>:<port>/mcp (default: http://0.0.0.0:8000/mcp)

Docker

Multi-stage Dockerfile — installs deps with uv, runs python -m src.main. Set DATABASE_URL and other env vars at runtime (via -e or your orchestrator).

Suggested client test

http://localhost:8000/mcp

MCP resources

MCP tools

Orientation (call first)

• summarize_knowledge_base — coverage counts (including skills/articles), orientation guide. Call this first.

• get_knowledge_taxonomy — canonical tag and source titles for filtering

Skills (check before knowledge search — body is inline)

• list_skills — list all skills with title, description, tags

• get_skill — full skill body returned inline, no URL fetch required

Articles (body inline)

• list_articles — list articles with optional tag/source filter

• get_article_content — full article body returned inline, no URL fetch required

Search

• search_knowledge_resources — search by query, tag, source, kind (repository, documentation, article, skill)

• search_documentation_routes — search routes across resources

• build_debugging_context — issue-focused bundle of resources and routes

Detail fetch

• get_resource_detail — one resource by ID, with optional routes

• list_resource_doc_routes — routes for a documentation resource

• list_doc_route_sections — distinct section names for a documentation resource

• list_resources_for_tag / list_resources_for_source

• get_repository_sync_status

Content proxy

• fetch_resource_content — fetch and return external URL body (docs.cartesi.io, github.com, etc.)

Cartesi app lifecycle (host-side instructions only)

• prepare_cartesi_create_command — stable v1.5.x vs alpha v2.0 create guidance

• prepare_cartesi_build_command

• prepare_cartesi_run_command

• get_cartesi_app_logic_guidance — address-book, portals, vouchers, notices, reports

Interaction & deposits (host-side instructions only)

• send_input_to_application — InputBox + cast templates

• prepare_erc20_deposit_instructions — ERC20Portal flow

• prepare_erc721_deposit_instructions — ERC721Portal flow

• prepare_erc1155_deposit_instructions — ERC1155SinglePortal flow

• prepare_eth_deposit_instructions — EtherPortal flow

• prepare_erc1155_batch_deposit_instructions — ERC1155BatchPortal flow

• prepare_voucher_execution_instructions — voucher execution with GraphQL proof query

MCP prompts

• debug_cartesi_issue — structured debugging using curated knowledge

• find_cartesi_docs — doc route discovery for a topic

• explain_repository_context — repository resource + status summary

Developer notes

• Agent-facing documentation, implementation tracker, and optimization plan live in .agents/ (git-ignored, local only). Start with .agents/INDEX.md.

• Before adding a new tool or resource, read .agents/MCP_CATALOG_MAINTENANCE.md — catalog entries must be kept in sync manually.

• The kind field on resources: "repository", "documentation", "article", "skill", "resource".