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 (extender para el nombre de host de su despliegue).
Salud HTTP simple: GET /healthz devuelve {"status":"ok"} junto a 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; 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.

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 están definidos en src/core/config.py (notablemente DATABASE_URL, APP_HOST, APP_PORT, MCP_BASE_URL, límites de paginación).

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

URI	Propósito
`cartesi://health`	Nombre del servidor, entorno, `MCP_BASE_URL`, flag de solo lectura, capacidades, política de contenido
`cartesi://resources`	Catálogo: índice de URIs de recursos, nombres de herramientas, prompts y flujo de agente sugerido
`cartesi://resources/{resource_id}`	Metadatos de recursos normalizados
`cartesi://docs/{resource_id}`	Vista de recurso de documentación (misma forma; los IDs que no son documentos dan error)
`cartesi://docs/routes/{route_id}`	Ruta de documento única con contexto padre
`cartesi://repositories/{resource_id}`	Metadatos de sincronización / frescura del repositorio
`cartesi://collections/tag/{tag}`	Recursos agrupados por etiqueta
`cartesi://collections/source/{source}`	Recursos agrupados por fuente

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 — guía 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, vouchers, 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 — recurso de repositorio + resumen de estado

Cartesi Knowledge MCP Server