Skip to content

README.md

Latest commit

 

History

History
177 lines (122 loc) · 7.71 KB

README.md

File metadata and controls

177 lines (122 loc) · 7.71 KB

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

Resource type Body delivery Agent action needed
Skills Inline — body stored in DB Call get_skill(id) — no URL fetch
Articles Inline — body stored in DB Call get_article_content(id) — no URL fetch
Documentation Metadata + external links Fetch canonical_url / route url separately
Repositories Metadata + external links Fetch canonical_url separately

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

URI Purpose
cartesi://health Server name, environment, MCP_BASE_URL, read-only flag, capabilities, content policy
cartesi://resources Catalog: index of resource URIs, tool names, prompts, tool groups, and suggested agent flow
cartesi://resources/{resource_id} Normalized resource metadata
cartesi://docs/{resource_id} Documentation resource view
cartesi://docs/routes/{route_id} Single doc route with parent context
cartesi://repositories/{resource_id} Repository sync / freshness metadata
cartesi://collections/tag/{tag} Resources grouped by tag
cartesi://collections/source/{source} Resources grouped by source
cartesi://skills List all available skills for discovery
cartesi://skills/{resource_id} Skill body inline (no external fetch required)
cartesi://articles/{resource_id} Article body inline (no external fetch required)

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".