Cartesi Knowledge MCP Server

Production-minded Model Context Protocol server that exposes curated Cartesi developer resources from PostgreSQL to AI agents over streamable HTTP.

Current capabilities

• FastMCP (mcp[cli] 1.26.x) with streamable_http_app() — use FastMCP’s Starlette app 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 (extend for your deployment hostname).

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

Knowledge responses are metadata and links (titles, URIs, canonical_url, doc routes). They do not include full fetched page bodies; agents should fetch external URLs when they need raw HTML or markdown.

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

Requirements

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

• A PostgreSQL database populated with the curated resource schema expected by src/db/models.py and ResourceService.

Environment variables

Copy .env.example to .env and adjust. Defaults and field names are defined in src/core/config.py (notably DATABASE_URL, APP_HOST, APP_PORT, MCP_BASE_URL, pagination limits).

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

The repository includes a multi-stage Dockerfile that installs dependencies with uv and runs python -m src.main. Set DATABASE_URL and other env vars at runtime (for example via -e or your orchestrator).

Suggested client test

Use MCP Inspector or any MCP-compatible client and connect to:

http://localhost:8000/mcp

MCP resources

MCP tools (registered names)

These are the name= values clients see (Python handler names may differ).

Knowledge

• summarize_knowledge_base — coverage, counts, orientation

• get_knowledge_taxonomy — known tag and source titles

• search_knowledge_resources — search by query, tag, source, kind

• get_resource_detail — one resource by ID, optional routes

• list_resource_doc_routes — routes for a documentation resource

• search_documentation_routes — search routes across resources

• list_resources_for_tag / list_resources_for_source

• get_repository_sync_status

• build_debugging_context — issue-focused bundle of resources and routes

Host-side Cartesi workflow (instructions only)

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

• prepare_cartesi_build_command

• prepare_cartesi_run_command

• 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

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

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