arcade-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Arcade MCP is a Python platform for building tool servers that speak two protocols from the same process:

1. MCP (Model Context Protocol) — the open standard for AI tool integration (JSON-RPC 2.0 over stdio or HTTP+SSE). Used by Claude Desktop, Cursor, VS Code, etc.
2. Arcade Worker — Arcade's internal REST+JWT protocol for managed tool execution by the Arcade Engine (/worker/* endpoints).

Both protocols share the same tool catalog. A single MCPApp definition serves both.

Monorepo with 5 interdependent libraries and a CLI. Python 3.10+. Build system: Hatchling. Package manager: uv (always use uv run, never bare pip or python).

Commands

Task	Command
Install all packages	make install (runs uv sync --extra all --extra dev + pre-commit install)
Run all lib tests	make test
Run a single test	uv run pytest libs/tests/core/test_toolkit.py::TestClass::test_method
Lint + type check	make check (pre-commit + mypy per-lib)
Build all wheels	make build

Library Dependency Graph

arcade-core          (base: config, errors, catalog, schema, auth definitions, telemetry)
├── arcade-tdk       (@tool decorator, error adapter chain, auth providers)
├── arcade-serve     (Arcade Worker protocol: /worker/* REST endpoints, JWT auth, OpenTelemetry)
│   └── arcade-mcp-server  (MCPApp, MCPServer, Context, transports, resource server auth)
│       └── arcade-mcp CLI (typer-based: new, login, configure, deploy, server, secret, evals)
└── arcade-evals     (evaluation framework, critics, test suites)

Each lib under libs/arcade-*/ has its own pyproject.toml and version, except arcade-cli and arcade-evals which use the root pyproject.toml. The root pyproject.toml defines the uv workspace members and the arcade CLI entry point.

Versioning Rules