claude-mcp copilot-instructions.md

AI agent quickstart and rules for this repo

Purpose: This MCP server bridges AI tools to the Claude Code CLI with sync/async execution and conversation continuity via Response IDs. Keep behavior compatible with existing tests and CLI output expectations.

Architecture and responsibilities

• Entrypoints: server.js → src/server/setup.js (creates McpServer, registers tools, stdio transport, signal cleanup).
• Services:
  • src/services/ClaudeService.js: Finds CLI (CLAUDE_CLI_NAME or ~/.claude/local/claude or PATH), builds args, runs sync (--output-format json) and async (--output-format stream-json --verbose), parses JSON; if stdout isn’t JSON, falls back to plain text and extracts Response ID: … from stderr.
  • src/services/TaskService.js: Async task lifecycle (pending/running/completed/failed/cancelled), cancellation (kill process group), periodic cleanup, optional MCP notifications, macOS notifications via osascript + afplay, parent-process watchdog to auto-cancel.
• Tools (MCP): src/tools/{start,resume,status,cancel}.js, wired via src/tools/index.js. Schemas with zod; handlers close over (claudeService, taskService).
• Utils: src/utils/{validation,errors,logger}.js for workingDirectory checks, standardized text responses, and debug logging gated by MCP_CLAUDE_DEBUG.

Developer workflows

• Tests (Vitest E2E): npm test. Tests spawn server.js over stdio and assert text content (not JSON RPC payloads directly).
• Run server: npm start. Verbose logs: MCP_CLAUDE_DEBUG=true npm start.
• One-time setup: run claude --dangerously-skip-permissions once to accept permissions.

Behavioral contracts (must match tests)

• Sync response shape (start/resume): return MCP text content that ends with a line Response ID: <uuid>.
  • Example: { content: [{ type: "text", text: ${result.result}\n\nResponse ID: ${result.session_id} }] }.
• Async start/resume: return Task started successfully. Use status with task ID: <uuid> then track via status.
• status output (text) must include: Task , Status, Elapsed, Working Directory, Created/Updated timestamps. If completed, include Result, Response ID, Cost, Duration. If failed, include Error.
• resume requires previousResponseId (zod schema enforces). It uses the original conversation’s working directory; don’t allow overriding it on resume.