{"_id":"@artipyheart/claude-code-mcp","name":"@artipyheart/claude-code-mcp","dist-tags":{"latest":"2.3.2"},"versions":{"2.3.2":{"name":"@artipyheart/claude-code-mcp","version":"2.3.2","description":"An MCP server that allows AI tools to interact with Claude Code programmatically with session continuity and async execution support.","author":{"name":"Evgenij","email":"belodedevgenij@gmail.com","url":"Eugene"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ArtiPyHeart/claude-code-mcp.git"},"homepage":"https://github.com/ArtiPyHeart/claude-code-mcp#readme","keywords":["mcp","model-context-protocol","claude-code","ai","llm","agent","async","conversation-continuity","code-analysis"],"type":"module","main":"server.js","bin":{"claude-code-mcp":"server.js"},"scripts":{"start":"node server.js","test":"vitest run"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.22.2"},"devDependencies":{"@types/node":"^22.15.17","@vitest/ui":"^3.1.3","typescript":"^5.0.0","vitest":"^3.1.3"},"gitHead":"19454a266229193ff949c281371c00dd6cef27fc","_id":"@artipyheart/claude-code-mcp@2.3.2","bugs":{"url":"https://github.com/ArtiPyHeart/claude-code-mcp/issues"},"_nodeVersion":"24.12.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-Ez97twzNvSr9pv9ScAR+kq90dB3jiTF/LBhB96LeZ5Y7ixIxGnUB/ZlQyUbILkeoKo/EkireM3Bba9+UhRdLUg==","shasum":"12a60f3f2f0af7c583b8c29fe6e185fbc633af7d","tarball":"https://registry.npmjs.org/@artipyheart/claude-code-mcp/-/claude-code-mcp-2.3.2.tgz","fileCount":16,"unpackedSize":68132,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAeTc4So4njekCF8uQbSmdGjqWm8UHKXGUf5q8xtOCMgAiEA2Oqr7jePZoysQG6nm2CLkkPfZLQ5qumVfo6B+iBgIYM="}]},"_npmUser":{"name":"artipyheart","email":"wwwyqy618@gmail.com"},"directories":{},"maintainers":[{"name":"artipyheart","email":"wwwyqy618@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-code-mcp_2.3.2_1770372854297_0.20588278911609814"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-06T10:14:14.232Z","2.3.2":"2026-02-06T10:14:14.449Z","modified":"2026-02-06T10:14:14.656Z"},"maintainers":[{"name":"artipyheart","email":"wwwyqy618@gmail.com"}],"description":"An MCP server that allows AI tools to interact with Claude Code programmatically with session continuity and async execution support.","homepage":"https://github.com/ArtiPyHeart/claude-code-mcp#readme","keywords":["mcp","model-context-protocol","claude-code","ai","llm","agent","async","conversation-continuity","code-analysis"],"repository":{"type":"git","url":"git+https://github.com/ArtiPyHeart/claude-code-mcp.git"},"author":{"name":"Evgenij","email":"belodedevgenij@gmail.com","url":"Eugene"},"bugs":{"url":"https://github.com/ArtiPyHeart/claude-code-mcp/issues"},"license":"MIT","readme":"# Claude Code MCP Server\n\nAn MCP (Model Context Protocol) server that allows AI tools to interact with Claude Code programmatically, enabling powerful agent-in-agent workflows with conversation continuity and asynchronous execution support.\n\n## Overview\n\nThis MCP server provides a bridge between AI tools and Claude Code, allowing other AI systems to execute prompts via Claude Code while maintaining session state for conversation continuity. It supports both synchronous and asynchronous execution patterns, making it suitable for quick queries and long-running operations.\n\n## Features\n\n- **Fresh conversations** - `start` tool for starting new conversations (sync/async)\n- **Resume conversations** - `resume` tool for continuing existing conversations (sync/async)\n- **Working directory support** - Execute Claude Code in any directory (fresh conversations only)\n- **Task management** - Monitor tasks with elapsed time, cancel operations, and retrieve results\n- **Conversation branching** - Resume from any previous response ID to branch conversations\n- **Robust CLI detection** - Automatically finds Claude Code installation\n- **Configurable permissions** - Supports `--permission-mode` or legacy bypass flag\n- **Environment configuration** - Customizable via environment variables\n- **Debug logging** - Optional verbose logging for troubleshooting\n- **Modular architecture** - Clean, maintainable codebase with separation of concerns\n- **Automated publishing** - GitHub Actions workflow for releases\n- **System notifications** - macOS notifications for task start/completion with distinct sounds\n- **Process cleanup** - Automatic cleanup of orphaned processes when MCP server disconnects\n\n## Design Decisions\n\nThis MCP server makes intentional design choices for clarity and practical use:\n\n### Response ID vs Session ID\nWe use **\"Response ID\"** terminology instead of \"Session ID\" because:\n- Each conversation turn generates a new Response ID\n- You can branch conversations from any previous Response ID\n- The term \"session\" incorrectly implies a continuous session, when in reality each response is a new branching point\n\n### No `--continue` Flag Support\nWe intentionally do **not** support Claude Code's `--continue` flag because:\n- With multiple agents running in parallel, \"most recent conversation\" is ambiguous\n- Each agent typically handles independent tasks\n- Use the `resume` tool with an explicit Response ID for precise conversation control\n\n### Permission Mode\nBy default this server uses `--dangerously-skip-permissions` for backward compatibility.  \nIf you set `CLAUDE_PERMISSION_MODE`, the server uses `--permission-mode <value>` instead, enabling:\n- `plan` mode for read-only code analysis\n- `acceptEdits` for auto-accepting file changes while confirming dangerous operations\n- `default` for standard interactive prompts\n- `bypassPermissions` for maintaining current behavior (all permissions granted)\n\n## Prerequisites\n\n- Node.js 18+ runtime\n- Claude Code CLI installed and configured\n- Claude Code must be run once with `--dangerously-skip-permissions` to accept terms\n\n## Installation & Setup\n\n### Option 1: NPX (No Installation)\n\nUse directly with npx:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude\": {\n      \"command\": \"npx\",\n      \"args\": [\"@artipyheart/claude-code-mcp\", \"--claude-cli-path\", \"/absolute/path/to/claude\"]\n    }\n  }\n}\n```\n\n### Option 2: Local Development\n\n1. **Clone and install:**\n\n   ```bash\n   git clone https://github.com/ArtiPyHeart/claude-code-mcp.git\n   cd claude-code-mcp\n   npm install\n   ```\n\n2. **Use in MCP config:**\n   ```json\n   {\n     \"mcpServers\": {\n       \"claude\": {\n          \"command\": \"node\",\n          \"args\": [\"/path/to/claude-code-mcp/server.js\", \"--claude-cli-path\", \"/absolute/path/to/claude\"]\n        }\n      }\n   }\n   ```\n\n`--claude-cli-path` expects an **absolute path** to the Claude executable.\n\n### First-time Claude Code Setup\n\n**Important:** Before using the setup above, run Claude Code once to accept permissions:\n\n```bash\nclaude --dangerously-skip-permissions\n```\n\nAccept the terms when prompted (one-time requirement).\n\n## Configuration\n\n### MCP Client Configuration\n\nAdd the configuration to your MCP configuration file:\n\n- **Cursor:** `~/.cursor/mcp.json`\n- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`\n\n### Startup Arguments\n\n- `--claude-cli-path`: Absolute path to Claude CLI executable (recommended)\n\n### Environment Variables\n\n- `CLAUDE_CLI_NAME`: Override Claude CLI binary name (default: \"claude\")\n- `CLAUDE_PERMISSION_MODE`: Use modern Claude permission mode (`plan`, `default`, `acceptEdits`, `bypassPermissions`)\n- `CLAUDE_EXEC_TIMEOUT_MS`: Execution timeout in milliseconds for sync/async runs (default: `1800000`)\n- `MCP_CLAUDE_DEBUG`: Set to \"true\" for verbose debug logging\n- `MCP_NOTIFICATIONS`: Set to \"false\" to disable macOS system notifications\n\n## Tools\n\n### `start` - Fresh Conversations\n\nStart fresh conversations with Claude Code. Supports both synchronous and asynchronous execution.\n\n**Parameters:**\n\n- `message` (string, required): The message to send to the agent. Be specific about what you want - mention file paths, desired output format, and any constraints.\n- `workingDirectory` (string, optional): Working directory to execute from. Use absolute paths or relative to current directory. Useful for different projects or git worktrees.\n- `appendSystemPrompt` (string, optional): Text to append to the default system prompt.\n- `async` (boolean, optional): Whether to execute asynchronously. Defaults to true.\n\n**Example (Synchronous):**\n\n```javascript\n// Simple query in current directory\nstart({\n  message: \"What's 2 + 2?\",\n  async: false,\n})\n\n// Analyze specific code in project directory\nstart({\n  message:\n    \"Analyze the authentication logic in src/auth.js and list security vulnerabilities as bullet points\",\n  workingDirectory: \"/path/to/project\",\n  async: false,\n})\n```\n\n**Response Format (Sync):**\n\n```\n4\n\nResponse ID: 938c8c6d-1897-4ce4-a727-d001a628a279\n```\n\n**Example (Asynchronous):**\n\n```javascript\nstart({\n  message:\n    \"Analyze the entire codebase for performance bottlenecks, focusing on database queries and API endpoints. Provide specific recommendations with file locations.\",\n})\n\nstart({\n  message:\n    \"Review all React components in src/components/ for accessibility issues and generate a detailed report with WCAG compliance suggestions\",\n  workingDirectory: \"/path/to/frontend-project\",\n})\n```\n\n**Response (Async):**\n\n```\nTask started successfully. Use status with task ID: 550e8400-e29b-41d4-a716-446655440000\n```\n\n### `resume` - Continue Conversations\n\nContinue an existing conversation with Claude Code. Supports both synchronous and asynchronous execution. Uses the original conversation's working directory.\n\n**Parameters:**\n\n- `message` (string, required): The message to send to the agent. Reference previous context when needed - the agent remembers the conversation history.\n- `previousResponseId` (string, required): Response ID from a previous agent response. Use to branch or continue any conversation.\n- `async` (boolean, optional): Whether to execute asynchronously. Defaults to true.\n\n**Example (Synchronous):**\n\n```javascript\nresume({\n  message: \"What did I just ask you?\",\n  previousResponseId: \"938c8c6d-1897-4ce4-a727-d001a628a279\",\n  async: false,\n})\n```\n\n**Response Format (Sync):**\n\n```\nYou asked me about 2 + 2.\n\nResponse ID: b2c3d4e5-f6g7-8901-bcde-f23456789012\n```\n\n**Example (Asynchronous):**\n\n```javascript\nresume({\n  message: \"Continue that analysis with more detail\",\n  previousResponseId: \"938c8c6d-1897-4ce4-a727-d001a628a279\",\n})\n```\n\n**Response (Async):**\n\n```\nTask started successfully. Use status with task ID: 661f9511-e30c-41e5-a927-556677889900\n```\n\n### `status` - Task Status Monitoring\n\nCheck the status and progress of an asynchronous task.\n\n**Parameters:**\n\n- `taskId` (string, required): The task ID returned by async `start`/`resume`\n\n**Example:**\n\n```javascript\nstatus({\n  taskId: \"550e8400-e29b-41d4-a716-446655440000\",\n})\n```\n\n**Response (Running):**\n\n```\nTask 550e8400-e29b-41d4-a716-446655440000:\nStatus: running\nElapsed: 45s\nWorking Directory: /Users/yourname/Code/claude-code-mcp\nCreated: 2025-05-28T21:15:30.123Z\nUpdated: 2025-05-28T21:16:15.456Z\n```\n\n**Response (Completed):**\n\n```\nTask 550e8400-e29b-41d4-a716-446655440000:\nStatus: completed\nElapsed: 1m 52s\nWorking Directory: /Users/yourname/Code/claude-code-mcp\nCreated: 2025-05-28T21:15:30.123Z\nUpdated: 2025-05-28T21:17:22.789Z\n\nResult: [Claude's comprehensive analysis here...]\nResponse ID: 938c8c6d-1897-4ce4-a727-d001a628a279\nCost: $0.045\nDuration: 112456ms\n```\n\n### `cancel` - Task Cancellation\n\nCancel a running asynchronous task.\n\n**Parameters:**\n\n- `taskId` (string, required): The task ID to cancel\n\n**Example:**\n\n```javascript\ncancel({\n  taskId: \"550e8400-e29b-41d4-a716-446655440000\",\n})\n```\n\n**Response:**\n\n```\nTask 550e8400-e29b-41d4-a716-446655440000 cancelled successfully\n```\n\n## Architecture\n\nThe server follows a modular architecture for maintainability:\n\n```\nclaude-code-mcp/\n├── server.js                    # Main entry point & orchestration\n├── src/\n│   ├── server/\n│   │   └── setup.js             # MCP server setup and signal handling\n│   ├── services/\n│   │   ├── TaskService.js       # Async task lifecycle & notification management\n│   │   └── ClaudeService.js     # Claude CLI execution logic\n│   ├── tools/\n│   │   └── (MCP tool definitions)\n│   └── utils/\n│       ├── errors.js            # Error handling utilities\n│       ├── logger.js            # Debug logging utilities\n│       └── validation.js       # Input validation utilities\n└── tests/\n    └── *.e2e.test.ts            # End-to-end tests\n```\n\n### Component Responsibilities\n\n- **TaskService**: Handles async task creation, tracking, progress monitoring, cancellation, cleanup, and system notifications\n- **ClaudeService**: Manages Claude CLI discovery and execution for both sync and async patterns with process group management\n- **Setup**: MCP server initialization, signal handling, and graceful shutdown coordination\n- **Tools**: Six MCP tools registered directly in server.js using MCP SDK pattern\n- **Server**: Minimal orchestration layer that wires components together\n\n## Development\n\n### Testing\n\n```bash\nnpm test\n```\n\nThe test suite includes:\n\n- Synchronous execution with session management\n- Asynchronous task creation and status monitoring\n- Task cancellation capabilities\n- Error handling for edge cases\n\n### Debug Mode\n\nSet `MCP_CLAUDE_DEBUG=true` to enable verbose logging:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/claude-code-mcp/server.js\"],\n      \"env\": {\n        \"MCP_CLAUDE_DEBUG\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Local Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Start in debug mode\nMCP_CLAUDE_DEBUG=true npm start\n```\n\n### STDIO logging (important)\n\nThis server communicates over STDIO. Do not write regular logs to stdout—doing so corrupts JSON-RPC. All logs go to stderr via the `logger` utility. See the MCP quickstart guidance on logging: https://modelcontextprotocol.io/quickstart/server.md\n\n## Use Cases\n\n### Fresh Conversations (`start`)\n\n- Starting new conversations or analysis\n- Working with different codebases (using `workingDirectory`)\n- Quick queries and immediate responses (sync mode)\n- Long-running operations that need to be non-blocking (async mode)\n- Analyzing projects in separate directories or git worktrees\n- Custom system prompts for specialized behavior\n\n### Resume Conversations (`resume`)\n\n- Continuing existing conversations and context\n- Building on previous responses or analysis\n- Following up with questions about prior context\n- Branching conversations from any previous response\n- Maintaining conversation continuity within the same working directory\n- Both sync and async execution modes\n\n## Writing Effective Prompts\n\nEach tool provides detailed message guidance in its parameter descriptions to help you get the best results from Claude Code. The key principles are:\n\n- **Be specific** about what you want analyzed or created\n- **Mention file paths** and directories to focus Claude's attention\n- **Specify output format** (bullet points, JSON, code snippets, etc.)\n- **Include constraints** and focus areas (performance, security, accessibility, etc.)\n- **For resume tools**: Reference previous context and build incrementally\n\nSee the tool parameter descriptions for comprehensive guidance and examples.\n\n## Publishing\n\nThis project uses GitHub Actions for automated publishing:\n\n- **Releases**: Create a GitHub release to automatically publish to npm\n- **Manual**: Use the \"Publish to npm\" workflow dispatch for manual publishing\n\n## License\n\nMIT\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Troubleshooting\n\n### Claude CLI Not Found\n\n- Ensure Claude CLI is installed and in your PATH\n- Set `--claude-cli-path /absolute/path/to/claude` in your MCP server args\n- Make sure `--claude-cli-path` uses an absolute path (relative paths are rejected)\n- Or set `CLAUDE_CLI_NAME` if using a custom command name\n- Check that the CLI works: `claude --version`\n\n### Permission Errors\n\n- Run `claude --dangerously-skip-permissions` once to accept terms\n- Ensure the MCP server has permission to execute the Claude CLI\n\n### Conversation Continuity Issues\n\n- Response IDs are returned in each response - save them for continuation\n- Conversations may expire after extended periods of inactivity\n- Each new conversation without a previousResponseId starts fresh\n- You can branch conversations from any previous response ID\n\n### Async Task Issues\n\n- Tasks are automatically cleaned up after 1 hour of completion\n- Use `status` to monitor long-running tasks\n- Tasks can be cancelled with `cancel` if needed\n- Check debug logs if tasks appear stuck\n- Tasks are automatically cancelled when MCP server disconnects\n\n### System Notifications\n\n- macOS notifications show task start (\"Agent Task Started\") and completion (\"Agent Task Completed\")\n- Different sounds for start (Tink) vs completion (Glass/Basso/Funk based on result)\n- Disable with `MCP_NOTIFICATIONS=false` environment variable\n- Notifications include truncated prompt text for context\n\n### Performance Considerations\n\n- Async tasks don't block the MCP server\n- Multiple async tasks can run concurrently\n- Monitor task progress to avoid resource exhaustion\n- Consider task cancellation for very long operations\n- Parent process monitoring prevents orphaned processes\n","readmeFilename":"README.md","_rev":"1-f71da1aa63d588593d4dbe5cd75d31cf"}