MotionMCP: Instructions file for Claude Code

CLAUDE.md

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

Motion MCP Server

MCP server bridging Motion's task management API with LLMs via the Model Context Protocol. Supports both local (stdio) and remote (Cloudflare Workers) deployment.

Common Commands

# Build & Run
npm run build              # Compile TypeScript to dist/
npm run mcp                # Start MCP server (compiled)
npm run mcp:dev            # Start MCP server (ts-node, no build needed)
npm run type-check         # Type checking without emitting files

# Testing (vitest)
npm test                   # Run all unit tests (node + worker projects)
npm test -- handlers.task  # Run a single test file by name fragment
npm test -- --reporter=verbose  # Run with verbose output
npm run test:worker        # Worker tests only: auth gate + stateless MCP handler (runs in workerd)
npm run test:integration   # Integration tests (requires MOTION_API_KEY in .env)

# Worker (Cloudflare)
npm run worker:dev             # Local Worker at http://localhost:8787
npm run worker:deploy          # Deploy to Cloudflare
npm run worker:type-check      # Type-check Worker code (separate tsconfig)

# Verify both entry points compile
npm run build && npm run worker:type-check

# Quick startup smoke test
timeout 3s npm run mcp

Releasing (version bump, tag, GitHub release, npm publish, Worker deploy) is documented step by step in DEVELOPER.md under "Releasing".

Testing

Uses vitest. vitest.config.mts defines two projects that both run under npm test:

• node — unit tests in tests/**/*.spec.ts, 10s timeout, mocked services, tests/setup.ts silences console.error
• worker — tests/worker/**/*.spec.ts, run inside workerd via @cloudflare/vitest-pool-workers

Integration tests live in tests/integration/**/*.integration.test.ts and use their own config.

• Integration tests: 60s timeout, sequential execution (rate limits), requires MOTION_API_KEY env var
• Handler tests mock MotionApiService and WorkspaceResolver; service returns use ListResult<T> shape ({ items, truncation })
• Worker tests cover src/worker.ts authentication. They must run in workerd, not Node: crypto.subtle.timingSafeEqual is a Workers extension Node does not implement, and the path rewrites depend on Workers Request/URL semantics. Bindings come from wrangler.toml with fake MOTION_API_KEY/MOTION_MCP_SECRET values injected in the config. The auth tests stub mcpTransport.handle so authorized requests are observable; a second block runs unstubbed through the real createMcpHandler (initialize, tools/list, schema rejection, 405 on GET/DELETE) and stops short of any tool call that would reach Motion.
• The config is .mts because @cloudflare/vitest-pool-workers is ESM-only and the package is CommonJS.