mcp: Instructions file for Codex

Development Commands

Before committing any code, ensure all tests pass, formatting is good, linting is clean, and type checks succeed.

Environment Setup

• uv venv - Create virtual environment
• uv pip install -e . - Install package in development mode
• export ZOO_API_TOKEN="your_api_key_here" - Set required Zoo API token

Running the Server

• uv run -m zoo_mcp - Start the MCP server locally
• uv run mcp run src/zoo_mcp/server.py - Alternative method using mcp package
• uv run mcp dev src/zoo_mcp/server.py - Run server with MCP Inspector for testing

Testing and Quality

• uv run pytest -n auto - Run all tests (includes live tests that hit zoo.dev)
• uv run pytest -n auto -m "not live" - Run all tests except those that hit live external services (use this when offline or to avoid network calls)
• uv run pytest tests/test_server.py - Run specific test file
• uv run ruff check - Run linter
• uv run ruff format - Format code
• uv run ty check - Type check source code

Integration Commands

• uv run mcp install src/zoo_mcp/server.py - Install server for Claude Desktop integration

Architecture

This is a Model Context Protocol (MCP) server that exposes Zoo CAD and KCL utility tools to AI assistants. The architecture consists of:

Core Components

• src/zoo_mcp/server.py - MCPServer (mcp 2.x) server that defines the MCP interface and registers all @mcp.tool() entry points (KCL execution, snapshots, physical-property calculations, KCL docs/samples lookup, org datasets, etc.). Owns the lifespan hook that lazily populates the KCL docs/samples indexes.
• src/zoo_mcp/zoo_tools.py - Implementations of the CAD-oriented tools that talk to Zoo's KittyCAD API (executing/exporting KCL, file conversion, snapshots, physical properties, sketch constraint status, lint-and-fix, org dataset listing/semantic search, etc.).
• src/zoo_mcp/kcl_docs.py - Fetches and indexes KCL documentation from zoo.dev (via the sitemap, with Accept: text/markdown) and exposes list/search/get helpers backed by a lazily-initialized index.
• src/zoo_mcp/kcl_samples.py - Indexes public Aquarium projects through the Zoo API and exposes list/search/get helpers. Sample names are public project IDs; KCL files are read from ZIP downloads on demand, preserving relative paths.
• src/zoo_mcp/utils/data_retrieval_utils.py - Shared helpers for fetching zoo.dev pages safely (path validation, redirect-blocking fetches, markdown excerpting) used by kcl_docs.py and kcl_samples.py.
• src/zoo_mcp/utils/image_utils.py - Image utilities used by the snapshot tool (encoding to MCP ImageContent, saving to disk, tiling up to four views into a collage, resizing).
• src/zoo_mcp/__init__.py - Package initialization: configures logging and the shared TLS context, and defines ZooMCPException and ZooMCPTimeoutError.
• src/zoo_mcp/__main__.py - python -m zoo_mcp entry point; delegates to server.main.