ai-cli-mcp 2.0.0

package/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npm test:*)",
+      "Bash(npx vitest run:*)",
+      "Bash(rg:*)",
+      "Bash(grep:*)",
+      "Bash(chmod:*)",
+      "Bash(npx:*)",
+      "mcp__ccm__claude_code",
+      "mcp__ccm__get_claude_result",
+      "mcp__chat__agent_communication_list_rooms",
+      "mcp__chat__agent_communication_get_messages",
+      "mcp__ccm__list_claude_processes"
+    ],
+    "deny": []
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: Node.js CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build project
+      run: npm run build

package/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        
+    - name: Install dependencies
+      run: npm ci
+      
+    - name: Build
+      run: npm run build
+      
+    - name: Run unit tests only
+      run: npm run test:unit
+      
+    - name: Run all tests with coverage
+      run: npm run test:coverage
+      
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.node-version == '20.x'
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage/coverage-final.json
+        flags: unittests
+        name: codecov-umbrella

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "git.ignoreLimitWarning": true
+}

package/AGENT.md

@@ -0,0 +1,57 @@
+# AGENT.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Purpose
+
+This is the source code for the Claude Code MCP tool - a server that allows running Claude Code in one-shot mode with permissions bypassed automatically. When you're asked to edit the Claude Code tool description or behavior, update it in `src/server.ts`.
+
+## Key Files
+
+- `src/server.ts`: The main server implementation containing the Claude Code tool description and functionality
+- `package.json`: Package configuration and dependencies
+- `start.sh`/`start.bat`: Scripts to start the server
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Start the server
+npm run start
+
+# Development mode with auto-reloading
+npm run dev
+```
+
+## Tool Description
+
+The tool description can be found in `src/server.ts`. When asked to update the Claude Code tool description, look for the `description` field in the `setupToolHandlers` method.
+
+## Architecture Notes
+
+- This MCP server provides a single tool (`claude_code`) that executes Claude CLI with bypassed permissions
+- The server handles execution via the `spawnAsync` function that runs Claude CLI with appropriate parameters
+- Error handling and timeout management are implemented for reliability
+- Working directory can be specified via the `workFolder` parameter
+
+## Environment Variables
+
+- `CLAUDE_CLI_PATH`: Path to the Claude CLI executable
+- `MCP_CLAUDE_DEBUG`: Set to `true` for verbose debug logging
+
+## Best Practices
+
+- Always test changes locally before committing
+- Maintain compatibility with the Model Context Protocol spec
+- Keep error messages informative for troubleshooting
+- Document any changes to the API or configuration options
+- Pure updates to the readme and/or adding new images do not require a version bump.
+- **Comprehensive Staging for README Image Updates:** When updating `README.md` to include new images, ensure that prompts for `claude_code` explicitly instruct it to stage *both* the modified `README.md` file *and* all new image files (e.g., from the `assets/` directory). Committing the `README.md` without its new image assets is a common pitfall.
+- **Clarity in Multi-Step Git Prompts:** For complex, multi-step `claude_code` prompts involving Git operations (like creating branches, committing multiple files, and pushing/creating PRs):
+    - Clearly list all files to be staged in the commit (text files, new image assets, etc.).
+- **Automatic Push on PR Branches:** When the user asks to commit changes while on a pull request branch, Claude should automatically push the changes to the remote after committing. This ensures PR updates are immediately visible for review.

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.10.12] - 2025-05-17
+
+- Fixed MCP server startup issue by ensuring process runs regardless of module detection
+- Updated server version constant to match package version
+- Simplified entry point logic to prevent early exit
+
+## [1.10.11] - 2025-05-17
+
+- Restored package structure to v1.9.4 configuration after bundling issues
+- Removed bundling approach and dependencies (esbuild)
+- Fixed build by returning to simple TypeScript compilation with tsc
+- Kept ESLint in devDependencies where it belongs
+- Package now works correctly as MCP server again
+
+## [1.10.10] - 2025-05-17
+
+- Restored shipping TypeScript source files alongside compiled JavaScript
+- Returns to the pre-bundling approach of versions 1.5.0-1.9.x
+- Includes src/server.ts, tsconfig.json, and start scripts in package
+- Provides flexibility for users to run or modify the TypeScript version
+
+## [1.10.9] - 2025-05-17
+
+- Switched from bundling approach to TypeScript compilation like working MCP servers
+- Aligns with successful macos-automator-mcp package structure
+- Simpler build process with tsc instead of esbuild bundling
+
+## [1.10.8] - 2025-05-17
+
+- Fixed critical dependency issue by moving @eslint/js to devDependencies
+- This resolves the MCP server crash on initialization
+- Cleaner production bundle without unnecessary development dependencies
+
+## [1.10.7] - 2025-05-17
+
+- Fixed bundling configuration to properly include all native modules
+- Resolved MCP initialization errors in bundled version
+
+## [1.10.6] - 2025-05-17
+
+- Runs now from compiled dist, bundled. Faster startup & smaller package size.
+- Tool version and startup time print on first use
+
+## [1.10.0] - 2025-05-17
+
+- Support for `CLAUDE_CLI_NAME` environment variable to override the Claude CLI binary name
+- Support for absolute paths in `CLAUDE_CLI_NAME` (e.g., `/tmp/claude-test`)
+- Comprehensive unit and e2e tests for the server functionality
+- Test infrastructure with mocked Claude CLI for reliable testing
+- `CLAUDE_CLI_NAME` now supports both simple names and absolute paths
+- Relative paths in `CLAUDE_CLI_NAME` now throw an error (security improvement)
+- Removed test mock directory lookup when absolute path is provided
+
+## [1.9.5] - 2025-05-15
+
+### Changed  
+- Clarify that workingDir must be absolute.
+
+## [1.9.4] - 2025-05-15
+
+### Added
+- Enhanced `claude_code` tool description in `src/server.ts` to reflect multi-modal capabilities (image analysis), file content analysis, and provide more comprehensive prompt tips.
+
+### Changed
+- Resized example images in `README.md` for better display via HTML width attributes.
+
+## [1.9.3] - 2025-05-15
+
+### Changed
+- Better work directory management.
+
+## [1.9.1] - 2025-05-14
+
+### Changed
+- Increased the maximum execution timeout for the Claude Code tool from 5 minutes to 30 minutes.
+
+## [1.9.0] - 2025-05-14
+
+### Changed
+- Modified the input for the `claude_code` tool. The `workFolder` is now an optional explicit JSON parameter instead of being parsed from the `prompt` string. This improves clarity and simplifies prompt construction.
+
+## [1.8.0] - 2025-05-14
+
+### Changed
+- Improved startup stability by explicitly using `/bin/bash` for Claude CLI script execution and ensuring correct command-line arguments are used.
+
+## [1.7.0] - 2025-05-14
+
+### Changed
+- Renamed the primary MCP tool from `code` to `claude_code` for better clarity and consistency in UI (`src/server.ts`).
+- Updated `README.md` to reflect the new tool name.
+
+## [1.6.1] - 2025-05-14
+
+### Fixed
+- Amended previous commit on `feature/v1.6.0-updates` to include `dist/server.js` which was built but not staged.
+- Resolved merge conflicts by rebasing `release/v1.6.1` onto `main` before merge.
+
+*(Note: Version 1.6.1 was primarily a maintenance release for PR #6 hygiene after rebasing).*
+
+## [1.6.0] - 2025-05-14
+
+### Added
+- Integrated logic in `src/server.ts` to parse "Your work folder is..." directive from prompts to set the Current Working Directory (CWD) for the underlying `claude-code-cli`.
+- Default CWD for `claude-code-cli` is set to the user's home directory if no specific "Your work folder is..." directive is provided in the prompt.
+- Enhanced error messages for `claude-code-cli` execution failures, including attempts to append `stderr` and `stdout` from the failed process to the error message.
+
+### Fixed
+- Resolved various linting errors in `src/server.ts` related to:
+    - Correct access of request parameters (e.g., `args.params.name` for tool name, `args.params.arguments.prompt` for prompt).
+    - Correct usage of `ErrorCode` enum members from `@modelcontextprotocol/sdk` (e.g., `ErrorCode.MethodNotFound`, `ErrorCode.InvalidParams`, `ErrorCode.InternalError` for timeouts and general failures).
+- Ensured `npm run build` completes successfully after CWD logic integration and lint fixes.
+- Ensured the `--dangerously-skip-permissions` flag is passed correctly as one of the first arguments to `claude-code-cli`.
+
+### Changed
+- Set default execution timeout for `claude-code-cli` to 5 minutes (300,000 ms).
+
+---
+*Older versions might not have detailed changelog entries.*

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger (Original work)
+Copyright (c) 2025 mkXultra (Modified work)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# AI CLI MCP Server
+
+<img src="assets/claude_code_mcp_logo.png" alt="AI CLI MCP Logo">
+
+[![npm package](https://img.shields.io/npm/v/ai-cli-mcp)](https://www.npmjs.com/package/ai-cli-mcp)
+[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](/CHANGELOG.md)
+
+> **📦 Package Migration Notice**: This package was formerly `@mkxultra/claude-code-mcp` and has been renamed to `ai-cli-mcp` to reflect its expanded support for multiple AI CLI tools.
+
+An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude and Codex) in background processes with automatic permission handling.
+
+Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified `run` tool, enables multiple AI agents to handle your coding tasks more effectively.
+
+<img src="assets/screenshot.png" width="300" alt="Screenshot">
+
+## Overview
+
+This MCP server provides tools that can be used by LLMs to interact with AI CLI tools. When integrated with MCP clients, it allows LLMs to:
+
+- Run Claude CLI with all permissions bypassed (using `--dangerously-skip-permissions`)
+- Execute Codex CLI with automatic approval mode (using `--full-auto`)
+- Support multiple AI models: Claude (sonnet, opus, haiku) and Codex (gpt-5-low, gpt-5-medium, gpt-5-high)
+- Manage background processes with PID tracking
+- Parse and return structured outputs from both tools
+
+## Benefits
+
+- Claude/Windsurf often have trouble editing files. Claude Code is better and faster at it.
+- Multiple commands can be queued instead of direct execution. This saves context space so more important stuff is retained longer, fewer compacts happen.
+- File ops, git, or other operations don't need costy models. Claude Code is pretty cost effective if you sign up for Antropic Max. You can use Gemini or o3 in Max mode and save costs with offloading tasks to cheaper models.
+- Claude has wider system access and can do things that Cursor/Windsurf can't do (or believe they can't), so whenever they are stuck just ask them "use claude code" and it will usually un-stuck them.
+- Agents in Agents rules.
+
+<img src="assets/agents_in_agents_meme.jpg" alt="Agents in Agents Meme">
+
+## Prerequisites
+
+- Node.js v20 or later (Use fnm or nvm to install)
+- Claude CLI installed locally (run it and call /doctor) and `--dangerously-skip-permissions` accepted
+- Codex CLI installed (optional, for Codex support)
+
+## Configuration
+
+### Environment Variables
+
+- `CLAUDE_CLI_NAME`: Override the Claude CLI binary name or provide an absolute path (default: `claude`)
+- `CODEX_CLI_NAME`: Override the Codex CLI binary name or provide an absolute path (default: `codex`)
+- `MCP_CLAUDE_DEBUG`: Enable debug logging (set to `true` for verbose output)
+
+Both CLI name variables support:
+- Simple name: `CLAUDE_CLI_NAME=claude-custom` or `CODEX_CLI_NAME=codex-v2`
+- Absolute path: `CLAUDE_CLI_NAME=/path/to/custom/claude`
+
+Note: Relative paths are not allowed and will throw an error.
+
+## Installation & Usage
+
+The recommended way to use this server is by installing it by using `npx`.
+
+### Using npx in your MCP configuration:
+
+```json
+    "ai-cli-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ai-cli-mcp@latest"
+      ]
+    },
+```
+
+### Using Claude CLI mcp add command:
+
+```bash
+claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
+```
+
+### With custom CLI binaries:
+
+```json
+    "ai-cli-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ai-cli-mcp@latest"
+      ],
+      "env": {
+        "CLAUDE_CLI_NAME": "claude-custom",
+        "CODEX_CLI_NAME": "codex-custom"
+      }
+    },
+```
+
+## Important First-Time Setup
+
+### For Claude CLI:
+
+**Before the MCP server can use Claude, you must first run the Claude CLI manually once with the `--dangerously-skip-permissions` flag, login and accept the terms.**
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude --dangerously-skip-permissions
+```
+
+Follow the prompts to accept. Once this is done, the MCP server will be able to use the flag non-interactively.
+
+### For Codex CLI:
+
+**For Codex, ensure you're logged in and have accepted any necessary terms:**
+
+```bash
+codex login
+```
+
+macOS might ask for folder permissions the first time either tool runs. If the first run fails, subsequent runs should work.
+
+## Connecting to Your MCP Client
+
+After setting up the server, you need to configure your MCP client (like Cursor or others that use `mcp.json` or `mcp_config.json`).
+
+### MCP Configuration File
+
+The configuration is typically done in a JSON file. The name and location can vary depending on your client.
+
+#### Cursor
+
+Cursor uses `mcp.json`.
+- **macOS:** `~/.cursor/mcp.json`
+- **Windows:** `%APPDATA%\\Cursor\\mcp.json`
+- **Linux:** `~/.config/cursor/mcp.json`
+
+#### Windsurf
+
+Windsurf users use `mcp_config.json`
+- **macOS:** `~/.codeium/windsurf/mcp_config.json`
+- **Windows:** `%APPDATA%\\Codeium\\windsurf\\mcp_config.json`
+- **Linux:** `~/.config/.codeium/windsurf/mcp_config.json`
+
+(Note: In some mixed setups, if Cursor is also installed, these clients might fall back to using Cursor's `~/.cursor/mcp.json` path. Prioritize the Codeium-specific paths if using the Codeium extension.)
+
+Create this file if it doesn't exist. Add or update the configuration for `ai-cli-mcp`:
+
+## Tools Provided
+
+This server exposes the following tools:
+
+### `run`
+
+Executes a prompt using either Claude CLI or Codex CLI. The appropriate CLI is automatically selected based on the model name.
+
+**Arguments:**
+- `prompt` (string, optional): The prompt to send to the AI agent. Either `prompt` or `prompt_file` is required.
+- `prompt_file` (string, optional): Path to a file containing the prompt. Either `prompt` or `prompt_file` is required. Can be absolute path or relative to `workFolder`.
+- `workFolder` (string, required): The working directory for the CLI execution. Must be an absolute path.
+- `model` (string, optional): The model to use:
+  - Claude models: "sonnet", "opus", "haiku"
+  - Codex models: "gpt-5-low", "gpt-5-medium", "gpt-5-high"
+- `session_id` (string, optional): Optional session ID to resume a previous session. Supported for: haiku, sonnet, opus.
+
+### `list_processes`
+
+Lists all running and completed AI agent processes with their status, PID, and basic info.
+
+### `get_result`
+
+Gets the current output and status of an AI agent process by PID.
+
+**Arguments:**
+- `pid` (number, required): The process ID returned by the `run` tool.
+
+### `kill_process`
+
+Terminates a running AI agent process by PID.
+
+**Arguments:**
+- `pid` (number, required): The process ID to terminate.
+
+**Example with Claude:**
+```json
+{
+  "toolName": "run",
+  "arguments": {
+    "prompt": "Refactor the function foo in main.py to be async.",
+    "workFolder": "/Users/username/my_project",
+    "model": "sonnet"
+  }
+}
+```
+
+**Example with Codex:**
+```json
+{
+  "toolName": "run",
+  "arguments": {
+    "prompt": "Create a REST API with Express.js",
+    "workFolder": "/Users/username/my_project",
+    "model": "gpt-5-high"
+  }
+}
+```
+
+### Examples
+
+Here are some visual examples of the server in action:
+
+<img src="assets/claude_tool_git_example.png" alt="Claude Tool Git Example" width="50%">
+
+<img src="assets/additional_claude_screenshot.png" alt="Additional Claude Screenshot" width="50%">
+
+<img src="assets/cursor-screenshot.png" alt="Cursor Screenshot" width="50%">
+
+### Fixing ESLint Setup
+
+Here's an example of using the Claude Code MCP tool to interactively fix an ESLint setup by deleting old configuration files and creating a new one:
+
+<img src="assets/eslint_example.png" alt="ESLint file operations example" width="50%">
+
+### Listing Files Example
+
+Here's an example of the Claude Code tool listing files in a directory:
+
+<img src="assets/file_list_example.png" alt="File listing example" width="50%">
+
+## Key Use Cases
+
+This server, through its unified `run` tool, unlocks a wide range of powerful capabilities by giving your AI direct access to both Claude and Codex CLI tools. Here are some examples of what you can achieve:
+
+1.  **Code Generation, Analysis & Refactoring:**
+    -   `"Generate a Python script to parse CSV data and output JSON."`
+    -   `"Analyze my_script.py for potential bugs and suggest improvements."`
+
+2.  **File System Operations (Create, Read, Edit, Manage):**
+    -   **Creating Files:** `"Your work folder is /Users/steipete/my_project\n\nCreate a new file named 'config.yml' in the 'app/settings' directory with the following content:\nport: 8080\ndatabase: main_db"`
+    -   **Editing Files:** `"Your work folder is /Users/steipete/my_project\n\nEdit file 'public/css/style.css': Add a new CSS rule at the end to make all 'h2' elements have a 'color: navy'."`
+    -   **Moving/Copying/Deleting:** `"Your work folder is /Users/steipete/my_project\n\nMove the file 'report.docx' from the 'drafts' folder to the 'final_reports' folder and rename it to 'Q1_Report_Final.docx'."`
+
+3.  **Version Control (Git):**
+    -   `"Your work folder is /Users/steipete/my_project\n\n1. Stage the file 'src/main.java'.\n2. Commit the changes with the message 'feat: Implement user authentication'.\n3. Push the commit to the 'develop' branch on origin."`
+
+4.  **Running Terminal Commands:**
+    -   `"Your work folder is /Users/steipete/my_project/frontend\n\nRun the command 'npm run build'."`
+    -   `"Open the URL https://developer.mozilla.org in my default web browser."`
+
+5.  **Web Search & Summarization:**
+    -   `"Search the web for 'benefits of server-side rendering' and provide a concise summary."`
+
+6.  **Complex Multi-Step Workflows:**
+    -   Automate version bumps, update changelogs, and tag releases: `"Your work folder is /Users/steipete/my_project\n\nFollow these steps: 1. Update the version in package.json to 2.5.0. 2. Add a new section to CHANGELOG.md for version 2.5.0 with the heading '### Added' and list 'New feature X'. 3. Stage package.json and CHANGELOG.md. 4. Commit with message 'release: version 2.5.0'. 5. Push the commit. 6. Create and push a git tag v2.5.0."`
+
+    <img src="assets/multistep_example.png" alt="Complex multi-step operation example" width="50%">
+
+7.  **Repairing Files with Syntax Errors:**
+    -   `"Your work folder is /path/to/project\n\nThe file 'src/utils/parser.js' has syntax errors after a recent complex edit that broke its structure. Please analyze it, identify the syntax errors, and correct the file to make it valid JavaScript again, ensuring the original logic is preserved as much as possible."`
+
+8.  **Interacting with GitHub (e.g., Creating a Pull Request):**
+    -   `"Your work folder is /Users/steipete/my_project\n\nCreate a GitHub Pull Request in the repository 'owner/repo' from the 'feature-branch' to the 'main' branch. Title: 'feat: Implement new login flow'. Body: 'This PR adds a new and improved login experience for users.'"`
+
+9.  **Interacting with GitHub (e.g., Checking PR CI Status):**
+    -   `"Your work folder is /Users/steipete/my_project\n\nCheck the status of CI checks for Pull Request #42 in the GitHub repository 'owner/repo'. Report if they have passed, failed, or are still running."`
+
+### Correcting GitHub Actions Workflow
+
+<img src="assets/github_actions_fix_example.png" alt="GitHub Actions workflow fix example" width="50%">
+
+### Complex Multi-Step Operations
+
+This example illustrates the AI agent handling a more complex, multi-step task, such as preparing a release by creating a branch, updating multiple files (`package.json`, `CHANGELOG.md`), committing changes, and initiating a pull request, all within a single, coherent operation.
+
+<img src="assets/claude_code_multistep_example.png" alt="AI agent multi-step example" width="50%">
+
+**CRITICAL: Remember to provide Current Working Directory (CWD) context in your prompts for file system or git operations (e.g., `"Your work folder is /path/to/project\n\n...your command..."`).**
+
+## Troubleshooting
+
+- **"Command not found" (claude-code-mcp):** If installed globally, ensure the npm global bin directory is in your system's PATH. If using `npx`, ensure `npx` itself is working.
+- **"Command not found" (claude or ~/.claude/local/claude):** Ensure the Claude CLI is installed correctly. Run `claude/doctor` or check its documentation.
+- **Permissions Issues:** Make sure you've run the "Important First-Time Setup" step.
+- **JSON Errors from Server:** If `MCP_CLAUDE_DEBUG` is `true`, error messages or logs might interfere with MCP's JSON parsing. Set to `false` for normal operation.
+- **ESM/Import Errors:** Ensure you are using Node.js v20 or later.
+
+**For Developers: Local Setup & Contribution**
+
+If you want to develop or contribute to this server, or run it from a cloned repository for testing, please see our [Local Installation & Development Setup Guide](./docs/local_install.md).
+
+## Testing
+
+The project includes comprehensive test suites:
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run e2e tests (with mocks)
+npm run test:e2e
+
+# Run e2e tests locally (requires Claude CLI)
+npm run test:e2e:local
+
+# Watch mode for development
+npm run test:watch
+
+# Coverage report
+npm run test:coverage
+```
+
+For detailed testing documentation, see our [E2E Testing Guide](./docs/e2e-testing.md).
+
+## Configuration via Environment Variables
+
+The server's behavior can be customized using these environment variables:
+
+- `CLAUDE_CLI_PATH`: Absolute path to the Claude CLI executable.
+  - Default: Checks `~/.claude/local/claude`, then falls back to `claude` (expecting it in PATH).
+- `MCP_CLAUDE_DEBUG`: Set to `true` for verbose debug logging from this MCP server. Default: `false`.
+
+These can be set in your shell environment or within the `env` block of your `mcp.json` server configuration (though the `env` block in `mcp.json` examples was removed for simplicity, it's still a valid way to set them for the server process if needed).
+
+## Contributing
+
+Contributions are welcome! Please refer to the [Local Installation & Development Setup Guide](./docs/local_install.md) for details on setting up your environment.
+
+Submit issues and pull requests to the [GitHub repository](https://github.com/mkXultra/claude-code-mcp).
+
+## License
+
+MIT