MCP-сервер знаний Cartesi

Сервер Model Context Protocol, ориентированный на промышленное использование, который предоставляет ИИ-агентам доступ к курируемым ресурсам для разработчиков Cartesi из PostgreSQL через потоковый HTTP.

Текущие возможности

• FastMCP (mcp[cli] 1.26.x) с streamable_http_app() — используйте приложение Starlette из FastMCP напрямую в продакшене, чтобы время жизни сессии работало корректно (см. create_app() в src/main.py).

• Async SQLAlchemy + asyncpg для доступа к базе знаний только для чтения.

• Многоуровневая структура: конфигурация и логирование (src/core/), сессия БД и модели (src/db/), репозитории, доменный сервис (src/domain/resource_service.py), схемы, форматировщики и серверные модули в src/server/.

• Безопасность транспорта: защита от DNS-ребиндинга и настраиваемые allowed_hosts / allowed_origins в src/server/server.py (расширьте для вашего хостнейма развертывания).

• Простая проверка работоспособности HTTP: GET /healthz возвращает {"status":"ok"} наряду с маршрутом MCP.

Ответы с базой знаний представляют собой метаданные и ссылки (заголовки, URI, canonical_url, маршруты документации). Они не включают полные тела загруженных страниц; агенты должны сами запрашивать внешние URL, если им нужен «сырой» HTML или markdown.

Инструменты рабочего процесса (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).

• База данных PostgreSQL, заполненная схемой курируемых ресурсов, ожидаемой src/db/models.py и ResourceService.

Переменные окружения

Скопируйте .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 — ресурс репозитория + сводка состояния