Cartesi Knowledge MCP Server

Produktionsorientierter Model Context Protocol-Server, der kuratierte Cartesi-Entwicklerressourcen aus PostgreSQL für KI-Agenten über streamable HTTP bereitstellt.

Aktuelle Funktionen

• FastMCP (mcp[cli] 1.26.x) mit streamable_http_app() — verwendet die Starlette-App von FastMCP direkt in der Produktion, damit die Sitzungslebensdauer korrekt abläuft (siehe create_app() in src/main.py).

• Async SQLAlchemy + asyncpg für schreibgeschützten Zugriff auf die Wissensdatenbank.

• Layered Layout: Konfiguration und Logging (src/core/), DB-Sitzung und Modelle (src/db/), Repositories, Domain-Service (src/domain/resource_service.py), Schemas, Formatierer und Server-Module unter src/server/.

• Transportsicherheit: Schutz vor DNS-Rebinding und konfigurierbare allowed_hosts / allowed_origins in src/server/server.py (für Ihren Deployment-Hostname zu erweitern).

• Einfaches HTTP-Healthcheck: GET /healthz gibt {"status":"ok"} neben der MCP-Route zurück.

Wissensantworten sind Metadaten und Links (Titel, URIs, canonical_url, Dokumentationsrouten). Sie enthalten keine vollständig abgerufenen Seiteninhalte; Agenten sollten externe URLs abrufen, wenn sie rohes HTML oder Markdown benötigen.

Workflow-Tools (prepare_cartesi_*, send_input_to_application, prepare_*_deposit_instructions, get_cartesi_app_logic_guidance) geben nur Anleitungen und Befehlsvorlagen für den Rechner des Benutzers zurück. Sie führen keine Cartesi-CLI, cast oder Chain-RPC von diesem Server aus.

Anforderungen

• Python ≥ 3.11 (siehe pyproject.toml; das enthaltene Dockerfile verwendet Python 3.12).

• Eine PostgreSQL-Datenbank, die mit dem kuratierten Ressourcenschema befüllt ist, das von src/db/models.py und ResourceService erwartet wird.

Umgebungsvariablen

Kopieren Sie .env.example nach .env und passen Sie diese an. Standardwerte und Feldnamen sind in src/core/config.py definiert (insbesondere DATABASE_URL, APP_HOST, APP_PORT, MCP_BASE_URL, Paginierungslimits).

Installation

Mit uv (empfohlen):

uv sync

Mit pip:

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

Ausführung

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

Der MCP-Endpunkt ist streamable HTTP unter:

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

Docker

Das Repository enthält ein mehrstufiges Dockerfile, das Abhängigkeiten mit uv installiert und python -m src.main ausführt. Setzen Sie DATABASE_URL und andere Umgebungsvariablen zur Laufzeit (zum Beispiel über -e oder Ihren Orchestrator).

Empfohlener Client-Test

Verwenden Sie den MCP Inspector oder einen beliebigen MCP-kompatiblen Client und verbinden Sie sich mit:

http://localhost:8000/mcp

MCP-Ressourcen

MCP-Tools (registrierte Namen)

Dies sind die name=-Werte, die Clients sehen (Python-Handler-Namen können abweichen).

Wissen

• summarize_knowledge_base — Abdeckung, Anzahl, Orientierung

• get_knowledge_taxonomy — bekannte Tag- und Quelltitel

• search_knowledge_resources — Suche nach Abfrage, Tag, Quelle, Art

• get_resource_detail — eine Ressource nach ID, optionale Routen

• list_resource_doc_routes — Routen für eine Dokumentationsressource

• search_documentation_routes — Suche nach Routen über Ressourcen hinweg

• list_resources_for_tag / list_resources_for_source

• get_repository_sync_status

• build_debugging_context — problemorientiertes Bündel von Ressourcen und Routen

Host-seitiger Cartesi-Workflow (nur Anleitungen)

• prepare_cartesi_create_command — Anleitung zur Erstellung: stabil v1.5.x vs. Alpha v2.0

• prepare_cartesi_build_command

• prepare_cartesi_run_command

• send_input_to_application — InputBox + cast-Vorlagen

• prepare_erc20_deposit_instructions — ERC20Portal-Ablauf

• prepare_erc721_deposit_instructions — ERC721Portal-Ablauf

• prepare_erc1155_deposit_instructions — ERC1155SinglePortal-Ablauf

• get_cartesi_app_logic_guidance — Adressbuch, Portale, Vouchers, Notices, Reports

MCP-Prompts

• debug_cartesi_issue — strukturiertes Debugging unter Verwendung von kuratiertem Wissen

• find_cartesi_docs — Entdeckung von Dokumentationsrouten für ein Thema

• explain_repository_context — Repository-Ressource + Statuszusammenfassung