Servidor MCP de Conocimiento de Cartesi

Servidor del Protocolo de Contexto de Modelo (MCP) orientado a producción que expone recursos curados para desarrolladores de Cartesi desde PostgreSQL a agentes de IA a través de HTTP transmitible.

Capacidades actuales

• FastMCP (mcp[cli] 1.26.x) con streamable_http_app() — utiliza la aplicación Starlette de FastMCP directamente en producción para que la vida útil de la sesión se ejecute correctamente (ver create_app() en src/main.py).

• Async SQLAlchemy + asyncpg para acceso de solo lectura a la base de datos de conocimiento.

• Diseño en capas: configuración y registro (src/core/), sesión y modelos de BD (src/db/), repositorios, servicio de dominio (src/domain/resource_service.py), esquemas, formateadores y módulos de servidor bajo src/server/.

• Seguridad de transporte: protección contra rebinding de DNS y allowed_hosts / allowed_origins configurables en src/server/server.py (extiéndalo para el nombre de host de su despliegue).

• Salud HTTP simple: GET /healthz devuelve {"status":"ok"} junto con la ruta MCP.

Las respuestas de conocimiento son metadatos y enlaces (títulos, URIs, canonical_url, rutas de documentos). No incluyen cuerpos de página completos obtenidos; los agentes deben obtener URLs externas cuando necesiten HTML o markdown sin procesar.

Las herramientas de flujo de trabajo (prepare_cartesi_*, send_input_to_application, prepare_*_deposit_instructions, get_cartesi_app_logic_guidance) solo devuelven instrucciones y plantillas de comandos para la máquina del usuario. No ejecutan la CLI de Cartesi, cast o RPC de cadena desde este servidor.

Related MCP server: read-docs-mcp

Requisitos

• Python ≥ 3.11 (ver pyproject.toml; el Dockerfile incluido utiliza Python 3.12).

• Una base de datos PostgreSQL poblada con el esquema de recursos curados esperado por src/db/models.py y ResourceService.

Variables de entorno

Copie .env.example a .env y ajuste. Los valores predeterminados y los nombres de los campos se definen en src/core/config.py (notablemente DATABASE_URL, APP_HOST, APP_PORT, MCP_BASE_URL, límites de paginación). Para URLs de PostgreSQL, postgres://... se normaliza a postgresql+asyncpg://..., y sslmode se traduce a ssl compatible con asyncpg (por ejemplo, sslmode=disable se convierte en ssl=false).

Instalación

Usando uv (recomendado):

uv sync

Usando pip:

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

Ejecución

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

El endpoint MCP es HTTP transmitible en:

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

Docker

El repositorio incluye un Dockerfile de múltiples etapas que instala dependencias con uv y ejecuta python -m src.main. Establezca DATABASE_URL y otras variables de entorno en tiempo de ejecución (por ejemplo, mediante -e o su orquestador).

Prueba de cliente sugerida

Utilice el Inspector MCP o cualquier cliente compatible con MCP y conéctese a:

http://localhost:8000/mcp

Recursos MCP

Herramientas MCP (nombres registrados)

Estos son los valores de name= que ven los clientes (los nombres de los manejadores de Python pueden diferir).

Conocimiento

• summarize_knowledge_base — cobertura, conteos, orientación

• get_knowledge_taxonomy — títulos conocidos de etiquetas y fuentes

• search_knowledge_resources — búsqueda por consulta, etiqueta, fuente, tipo

• get_resource_detail — un recurso por ID, rutas opcionales

• list_resource_doc_routes — rutas para un recurso de documentación

• search_documentation_routes — búsqueda de rutas a través de recursos

• list_resources_for_tag / list_resources_for_source

• get_repository_sync_status

• build_debugging_context — paquete de recursos y rutas enfocado en problemas

Flujo de trabajo de Cartesi en el host (solo instrucciones)

• prepare_cartesi_create_command — orientación de creación para v1.5.x estable vs v2.0 alfa

• prepare_cartesi_build_command

• prepare_cartesi_run_command

• send_input_to_application — plantillas de InputBox + cast

• prepare_erc20_deposit_instructions — flujo de ERC20Portal

• prepare_erc721_deposit_instructions — flujo de ERC721Portal

• prepare_erc1155_deposit_instructions — flujo de ERC1155SinglePortal

• get_cartesi_app_logic_guidance — libreta de direcciones, portales, vales, avisos, informes

Prompts MCP

• debug_cartesi_issue — depuración estructurada utilizando conocimiento curado

• find_cartesi_docs — descubrimiento de rutas de documentos para un tema

• explain_repository_context — resumen de recurso de repositorio + estado