Cartesi Knowledge MCP Server

PostgreSQLから厳選されたCartesi開発者リソースを、ストリーミング可能なHTTP経由でAIエージェントに公開する、本番環境を意識したModel Context Protocolサーバーです。

現在の機能

• FastMCP (mcp[cli] 1.26.x) と streamable_http_app() — セッションの寿命が正しく実行されるよう、FastMCPのStarletteアプリを本番環境で直接使用します（src/main.pyの create_app() を参照）。

• 知識データベースへの読み取り専用アクセスのための Async SQLAlchemy + asyncpg。

• 階層化レイアウト: 設定とログ (src/core/)、DBセッションとモデル (src/db/)、リポジトリ、ドメインサービス (src/domain/resource_service.py)、スキーマ、フォーマッタ、および src/server/ 下のサーバーモジュール。

• トランスポートセキュリティ: DNSリバインディング保護、および src/server/server.py で設定可能な allowed_hosts / allowed_origins（デプロイ先のホスト名に合わせて拡張してください）。

• プレーンHTTPヘルスチェック: MCPルートと並行して GET /healthz が {"status":"ok"} を返します。

知識のレスポンスはメタデータとリンク（タイトル、URI、canonical_url、ドキュメントルート）です。これらには取得されたページ本文全体は含まれません。エージェントが生のHTMLやマークダウンを必要とする場合は、外部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

このリポジトリには、uv で依存関係をインストールし、python -m src.main を実行するマルチステージの Dockerfile が含まれています。実行時に 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による1つのリソース、オプションのルート

• 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対アルファ版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 — リポジトリリソース + ステータスサマリー