motion-mcp-server CLAUDE.md

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
npm test -- handlers.task  # Run a single test file by name fragment
npm test -- --reporter=verbose  # Run with verbose output
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

Testing

Uses vitest. Unit tests in tests/**/*.spec.ts, integration tests in tests/integration/**/*.integration.test.ts.

• Unit tests: 10s timeout, mocked services, tests/setup.ts silences console.error
• 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 })

Architecture

Entry Points

Both share all handlers, services, tools, and utilities — they differ only in transport and API key source.

• Stdio Server (src/mcp-server.ts): Uses Server from MCP SDK. API key from MOTION_API_KEY env var.
• Cloudflare Worker (src/worker.ts): Uses McpAgent from Cloudflare Agents SDK with Durable Objects. API key from Worker secret. Auth via secret token in URL path (/mcp/SECRET).