zoo-mcp

Zoo Model Context Protocol（MCP）服务

一个包含各种 Zoo 构建工具的 MCP 服务

前提条件

1. Zoo 的 API 密钥，可在此处获取
2. 将环境变量 ZOO_API_TOKEN 设置为你的 API 密钥

   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 版本还附带独立的可执行文件（使用 PyInstaller 构建），适用于 Linux（x86_64、arm64）、macOS（arm64、x86_64）和 Windows（x86_64）——无需 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，我们会像这样将 zoo-mcp 与 ZooKeeper 搭配使用，以节省资源。每个 Agent 无需启动一个 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（规范化文件扩展名）等实用工具。

建模场景使用显式持久会话，每个服务进程最多只能打开一个会话。客户端重新连接后，可调用 get_modeling_sessions 找回会话 ID；如果没有会话，则调用 start_modeling_session。使用 execute_kcl、exec_kcl_project 或 import_cad_file 填充会话；将相同的 session_id 传给 snapshot 和建模工具；完成后调用 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 会保留完整报告，以兼容现有调用方。失败阶段还会公开 error_family，其中会包含会话超时时的 ZooMCPTimeoutError。 模拟错误或模拟执行中止时，会立即返回 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 仓库中提交 issue 或拉取请求。

PR 在合并前必须通过测试和代码检查。

使用 ruff 进行代码检查和格式化。

uvx ruff check
uvx ruff format

使用 ty 进行类型检查。

uvx ty check

测试

服务包含位于 tests 中的测试。运行测试请使用以下命令：

uv run pytest -n auto