zoo-mcp

Zoo Model Context Protocol (MCP) サーバー

さまざまな Zoo 製ユーティリティを備えたMCP サーバーです。

前提条件

1. Zoo の API キー。 こちらから取得できます。
2. API キーを設定した環境変数 ZOO_API_TOKEN

   export ZOO_API_TOKEN="your_api_key_here"
   

インストール

1. uv がインストールされていることを確認します

2. uv 環境を作成します

   uv venv
   

3. uv 環境を有効化します（任意）

4. GitHub からパッケージをインストールします

   uv pip install git+ssh://[email protected]/KittyCAD/mcp.git
   

サーバーの実行

uvxを使用してサーバーを起動できます。

uvx zoo-mcp

uv と zoo_mcp モジュールを使用して、ローカルでサーバーを起動できます。

uv run -m zoo_mcp

mcp パッケージを使用してサーバーを実行することもできます。

uv run mcp run src/zoo_mcp/server.py

Streamable HTTP

サーバーはデフォルトで stdio を使用します。同じツールを Streamable HTTP 経由で提供するには、次のようにします。

uvx zoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# From a local checkout:
uv run -m zoo_mcp --transport streamable-http

MCP クライアントを http://127.0.0.1:8000/mcp に接続します。SDK が HTTP セッションとストリーミングレスポンスを管理します。--host と --port で HTTP リスナーを設定できます。デフォルト値はそれぞれ 127.0.0.1 と 8000 です。

Python から認証情報を渡す

ローカルのエントリポイントは、起動時に Zoo MCP がインポートされた時点で認証情報を取得します。ZOO_API_TOKEN、KITTYCAD_API_TOKEN、またはレジストリのエイリアス ZOO_TOKEN と、API の接続先として ZOO_HOST または KITTYCAD_HOST を指定できます。

アプリケーションでは、プロセス環境を変更したり、MCP ツールに認証引数を追加したりせずに、認証情報を明示的に渡すことができます。

from zoo_mcp.credentials import ZooCredentials, use_credentials
from zoo_mcp.server import mcp

with use_credentials(ZooCredentials(token=api_token, base_url=api_origin)):
    result = await mcp.call_tool("list_org_datasets", {})

このコンテキストは、同じトークンと接続先を KittyCAD SDK および KCL のセッションコンストラクターに渡し、終了時に以前の設定を復元します。新しい呼び出しでは、更新された認証情報を使用できます。認証情報のコンテキストを終了する前に、子タスクを完了させてください。

認証情報のコンテキストは、下流の呼び出しを設定します。異なる所有者にサービスを提供するアプリケーションでは、プロセス全体に適用されるモデリングセッションとワークスペースも分離する必要があります。

ビルド済みバイナリ

各GitHub リリースには、Linux（x86_64、arm64）、macOS（arm64、x86_64）、Windows（x86_64）向けのスタンドアロン実行ファイル（PyInstaller でビルド）も添付されています。Python ツールチェーンは不要です。お使いのプラットフォーム用のバイナリをダウンロードし、ZOO_API_TOKEN を設定して、次のように直接実行します。

ZOO_API_TOKEN="your_api_key_here" ./zoo-mcp-linux-x86_64

バイナリはコード署名されていないため、初回実行時に macOS Gatekeeper や Windows SmartScreen の警告が表示される場合があります。

統合

サーバーを実行するか、Python コードに直接インポートして、そのまま使用できます。

from zoo_mcp.server import mcp

mcp.run()

個々のツールを独自の Python コードで使用することもできます。Zoo ではリソースを節約するため、ZooKeeper とともに zoo-mcp を次のように使用しています。エージェントごとに MCP サーバーを起動する代わりに、各エージェントが独自のランタイムにサーバーを「埋め込む」形で使用します。これにより、共有状態を防げるという追加の利点もあります。

from mcp.server.mcpserver import MCPServer
from zoo_mcp.zoo_tools import ResultZooExecuteKcl, zoo_execute_kcl

mcp = MCPServer(name="My Example Server")


@mcp.tool()
async def my_execute_kcl(kcl_code: str) -> ResultZooExecuteKcl:
    """
    Example tool that uses the zoo_execute_kcl function from zoo_mcp.zoo_tools
    """
    return await zoo_execute_kcl(kcl_code=kcl_code)

次のコマンドを使用して、Claude desktop と統合できます。

uv run mcp install src/zoo_mcp/server.py

次のコマンドを使用して、Claude Code と統合することもできます。

claude mcp add --scope project "Zoo-MCP" uv -- --directory "$PWD"/src/zoo_mcp run server.py

MCP Inspectorを使用してサーバーをテストすることもできます。

uv run mcp dev src/zoo_mcp/server.py

codex-cliで実行する場合

codex \
  -c 'mcp_servers.zoo.command="uvx"' \
  -c 'mcp_servers.zoo.args=["zoo-mcp"]' \
  -c mcp_servers.zoo.env.ZOO_API_TOKEN="$ZOO_API_TOKEN"

このリポジトリに含まれるヘルパースクリプトも使用できます。

./codex-zoo.sh

このスクリプトはリクエストの入力を求め、Zoo MCP サーバーとともに Codex を実行し、トークン使用量を含む JSONL の記録を codex-run-<timestamp>.jsonl に保存します。

アーキテクチャ

ツールは src/zoo_mcp/*.py で定義され、そこから src/zoo_mcp/server.py にインポートされて、実際の @mcp.tool() デコレーター付き関数に紐付けられます。

src/zoo_mcp/zoo_tools.py は、Zoo の KCL およびエンジン機能を操作するための大規模なツールセットとして機能します。このソースファイルには、parse_unit や normalize_ext（ファイル拡張子の正規化）などのユーティリティも含まれています。

モデリングシーンでは明示的な永続セッションを使用し、サーバープロセスごとに開けるセッションは最大1つです。クライアントの再接続後にセッション ID を復元するには get_modeling_sessions を呼び出し、セッションが存在しない場合は start_modeling_session を呼び出してください。execute_kcl、exec_kcl_project、または import_cad_file でセッションにデータを追加します。snapshot およびモデリングツールには同じ session_id を渡し、作業が終わったら stop_modeling_session を呼び出してください。

KCL の実行と永続モデリングセッションでは、CPU エンジンプールを使用します。分離された KCL スナップショットでは、一時的に CPU レンダリングが有効になります。永続セッションでは、最初のスナップショット、選択、ハイライト、またはカメラツールの呼び出し時にレンダリングが初期化され、セッションを停止するまで維持されるため、呼び出し間で視覚状態が保たれます。エクスポート、測定、ジオメトリクエリではグラフィックスは初期化されません。

KCL サンプルツールは、Zoo API から公開 Aquarium プロジェクトの一覧を取得し、検索します。返された name（公開プロジェクト ID）を get_kcl_sample に渡すと、その KCL ソースをダウンロードできます。ファイル名にはサブディレクトリを含むプロジェクト相対パスが保持されます。これらの公開ツールでは API トークンは不要です。一覧表示／検索結果の multipleFiles フィールドは、プロジェクトがダウンロードされるまではヒントとして扱われます。

0.28.0 以降、execute_kcl と exec_kcl_project は実際の実行の前にモック実行を行い、mock_preflight と real_execution という個別のオブジェクトを返します。それぞれに status（succeeded、failed、または not_run）、message、および重大度別にグループ化された diagnostics が含まれます。ステージメッセージは短い要約です。トップレベルの message には、既存の呼び出し元との互換性のため、完全なレポートが保持されます。失敗したステージには、セッションのタイムアウトを示す ZooMCPTimeoutError などの error_family も含まれます。モックエラーが発生した場合、またはモック実行が中止された場合は、ok: false および real_execution.status: "not_run" を返して直ちに終了します。実際の実行が失敗した場合でも、モックの警告は mock_preflight.diagnostics に保持されます。既知の planeOf モックエンジンの制限は警告として報告され、実際のエンジンで評価できるようにします。それ以外のモックエラーがある場合は、引き続き実行がブロックされます。セッションのレスポンスにはモックの診断情報が含まれます。エンジンはセッション実行について実行ステージの診断情報を返しません。

パス入力では、エントリポイントと、その推移的なインポート（リンクされたモジュールや glTF バッファーを含む）、および project.toml を一度だけ取り込みます。両方のステージでこのコピーを使用し、格納ディレクトリ内の無関係なファイルはスキャンしません。依存関係とシンボリックリンクの参照先は、エントリポイントのディレクトリ内に収まる必要があります。外部パスは、ファイル読み込みや実行の前に拒否されます。一時的なローカル実行エラーが発生した場合は、モック実行を繰り返さず、同じコピーを使用して回数を制限した再試行を行います。診断情報では元のソースパスを参照します。インラインの kcl_code では、自己完結したコードと標準ライブラリのインポートを使用できます。ファイルシステムからのインポートでは、明示的なディレクトリ内で依存関係を取り込むために kcl_path が必要です。 exec_kcl_project はパス文字列ではなく、この構造化された結果を返すようになりました。ok を確認し、セッションが成功した場合は path_artifact_graph を参照してください。スタンドアロンの mock_execute_kcl ツールは、引き続き既存のブール値とメッセージのペアを返します。

コントリビューション

コントリビューションを歓迎します！GitHub リポジトリでイシューを作成するか、プルリクエストを送信してください。

マージ前に、PR はテストとリンティングに合格する必要があります。

リンティングとフォーマットには ruff を使用します。

uvx ruff check
uvx ruff format

型チェックには ty を使用します。

uvx ty check

テスト

サーバーには tests にテストが含まれています。テストを実行するには、次のコマンドを使用してください。

uv run pytest -n auto