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を実行することはありません。

Related MCP server: read-docs-mcp

要件

• 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、ページネーション制限）。PostgreSQLのURLについては、postgres://... は postgresql+asyncpg://... に正規化され、sslmode はasyncpg互換の ssl に変換されます（例: sslmode=disable は ssl=false になります）。

インストール

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 — リポジトリリソース + ステータスの概要