Cartesi 知识 MCP 服务器

面向生产环境的 模型上下文协议 (Model Context Protocol) 服务器，通过可流式传输的 HTTP 向 AI 代理公开来自 PostgreSQL 的精选 Cartesi 开发者资源。

当前功能

• FastMCP (mcp[cli] 1.26.x) 配合 streamable_http_app() — 在生产环境中直接使用 FastMCP 的 Starlette 应用，以确保会话生命周期正常运行（参见 src/main.py 中的 create_app()）。

• 异步 SQLAlchemy + asyncpg，用于对知识数据库进行只读访问。

• 分层布局：配置和日志记录 (src/core/)、数据库会话和模型 (src/db/)、存储库、领域服务 (src/domain/resource_service.py)、模式、格式化程序以及 src/server/ 下的服务器模块。

• 传输安全：src/server/server.py 中的 DNS 重绑定保护以及可配置的 allowed_hosts / allowed_origins（请根据您的部署主机名进行扩展）。

• 纯 HTTP 健康检查：GET /healthz 与 MCP 路由一起返回 {"status":"ok"}。

知识响应为元数据和链接（标题、URI、canonical_url、文档路由）。它们不包含完整的抓取页面正文；当代理需要原始 HTML 或 Markdown 时，应自行获取外部 URL。

工作流工具 (prepare_cartesi_*、send_input_to_application、prepare_*_deposit_instructions、get_cartesi_app_logic_guidance) 仅返回针对用户机器的指令和命令模板。它们不会在此服务器上运行 Cartesi CLI、cast 或链上 RPC。

要求

• Python ≥ 3.11（参见 pyproject.toml；随附的 Dockerfile 使用 Python 3.12）。

• 一个已填充 src/db/models.py 和 ResourceService 所需精选资源模式的 PostgreSQL 数据库。

环境变量

将 .env.example 复制到 .env 并进行调整。默认值和字段名称定义在 src/core/config.py 中（特别是 DATABASE_URL、APP_HOST、APP_PORT、MCP_BASE_URL、分页限制）。

安装

使用 uv（推荐）：

uv sync

使用 pip：

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

运行

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

MCP 端点是可流式传输的 HTTP，地址为：

• http://<host>:<port>/mcp（默认：http://0.0.0.0:8000/mcp）

Docker

该存储库包含一个多阶段 Dockerfile，它使用 uv 安装依赖项并运行 python -m src.main。请在运行时设置 DATABASE_URL 和其他环境变量（例如通过 -e 或您的编排器）。

建议的客户端测试

使用 MCP Inspector 或任何兼容 MCP 的客户端并连接到：

http://localhost:8000/mcp

MCP 资源

MCP 工具（注册名称）

这些是客户端看到的 name= 值（Python 处理程序名称可能不同）。

知识

• summarize_knowledge_base — 覆盖范围、计数、导向

• get_knowledge_taxonomy — 已知的标签和来源标题

• search_knowledge_resources — 按查询、标签、来源、类型搜索

• get_resource_detail — 按 ID 获取单个资源，可选路由

• list_resource_doc_routes — 文档资源的路由

• search_documentation_routes — 跨资源搜索路由

• list_resources_for_tag / list_resources_for_source

• get_repository_sync_status

• build_debugging_context — 以问题为中心的资源和路由包

主机端 Cartesi 工作流（仅指令）

• prepare_cartesi_create_command — 稳定版 v1.5.x 与 alpha 版 v2.0 创建指南

• prepare_cartesi_build_command

• prepare_cartesi_run_command

• send_input_to_application — InputBox + cast 模板

• prepare_erc20_deposit_instructions — ERC20Portal 流程

• prepare_erc721_deposit_instructions — ERC721Portal 流程

• prepare_erc1155_deposit_instructions — ERC1155SinglePortal 流程

• get_cartesi_app_logic_guidance — 地址簿、门户、凭证、通知、报告

MCP 提示词

• debug_cartesi_issue — 使用精选知识进行结构化调试

• find_cartesi_docs — 主题的文档路由发现

• explain_repository_context — 存储库资源 + 状态摘要