feat: Make Claude CLI timeout configurable, increase default, and bump version to 1.11.0

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   build:
@@ -15,17 +15,17 @@ jobs:
         node-version: [20.x, 22.x]
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
+      - 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: 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: Install dependencies
+        run: npm ci
 
-    - name: Build project
-      run: npm run build
+      - name: Build project
+        run: npm run build

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   test:
@@ -14,30 +14,30 @@ jobs:
         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
+      - 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

AGENT.md

@@ -51,7 +51,7 @@ The tool description can be found in `src/server.ts`. When asked to update the C
 - 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.
+- **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.
+  - 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.

CHANGELOG.md

@@ -5,6 +5,30 @@ 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.11.0] - YYYY-MM-DD
+
+### Added
+
+- Made Claude CLI execution timeout configurable via `CLAUDE_CLI_TIMEOUT_SECONDS` environment variable (defaults to 3600 seconds / 60 minutes).
+- Dynamically fetch and display Claude CLI version in the tool description. MCP server version is also displayed.
+
+### Changed
+
+- Increased default Claude CLI execution timeout from 30 minutes to 60 minutes.
+- Removed comment from JSON example in `README.md`.
+- Tool description newlines are preserved, and backticks are correctly escaped for markdown.
+- Improved error message in tool description if Claude CLI version cannot be fetched.
+
+### Removed
+
+- Removed the old mechanism of printing MCP server version on the first tool use.
+
+## [1.10.13] - 2025-05-20
+
+### Changed
+
+- Updated Claude tool description to mention statelessness.
+
 ## [1.10.12] - 2025-05-17
 
 - Fixed MCP server startup issue by ensuring process runs regardless of module detection
@@ -60,67 +84,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.9.5] - 2025-05-15
 
-### Changed  
+### 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).*
+_(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).
+  - 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.*
+
+_Older versions might not have detailed changelog entries._

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Peter Steinberger
+Copyright (c) 2026 Peter Steinberger
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,4 +1,4 @@
-# Claude Code MCP Server
+# Claude Code MCP 🧑‍💻 - One-shot MCP server for Claude Code (an agent inside your agent)
 
 <img src="assets/claude_code_mcp_logo.png" alt="Claude Code MCP Logo">
 
@@ -43,19 +43,20 @@ This MCP server provides one tool that can be used by LLMs to interact with Clau
   - Using custom Claude CLI wrappers
   - Testing with mocked binaries
   - Running multiple Claude CLI versions side by side
-  
+
   Supported formats:
   - Simple name: `CLAUDE_CLI_NAME=claude-custom` or `CLAUDE_CLI_NAME=claude-v2`
   - Absolute path: `CLAUDE_CLI_NAME=/path/to/custom/claude`
-  
+
   Relative paths (e.g., `./claude` or `../claude`) are not allowed and will throw an error.
-  
+
   When set to a simple name, the server will look for the specified binary in:
   1. The system PATH (instead of the default `claude` command)
-  
+
   Note: The local user installation path (`~/.claude/local/claude`) will still be checked but only for the default `claude` binary.
 
 - `MCP_CLAUDE_DEBUG`: Enable debug logging (set to `true` for verbose output)
+- `CLAUDE_CLI_TIMEOUT_SECONDS`: Configure the timeout for Claude CLI operations in seconds (default: `3600`). This sets how long the server will wait for a response from the Claude CLI before considering it a timeout.
 
 ## Installation & Usage
 
@@ -86,6 +87,22 @@ To use a custom Claude CLI binary name, you can specify the environment variable
     },
 ```
 
+To use a custom Claude CLI binary name and set a custom timeout:
+
+```json
+    "claude-code-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@steipete/claude-code-mcp@latest"
+      ],
+      "env": {
+        "CLAUDE_CLI_NAME": "claude-custom",
+        "CLAUDE_CLI_TIMEOUT_SECONDS": "1800"
+      }
+    },
+```
+
 ## Important First-Time Setup: Accepting Permissions
 
 **Before the MCP server can successfully use the `claude_code` tool, you must first run the Claude CLI manually once with the `--dangerously-skip-permissions` flag, login and accept the terms.**
@@ -95,6 +112,7 @@ This is a one-time requirement by the Claude CLI.
 ```bash
 npm install -g @anthropic-ai/claude-code
 ```
+
 ```bash
 claude --dangerously-skip-permissions
 ```
@@ -114,13 +132,15 @@ The configuration is typically done in a JSON file. The name and location can va
 #### 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`
@@ -138,11 +158,13 @@ This server exposes one primary tool:
 Executes a prompt directly using the Claude Code CLI with `--dangerously-skip-permissions`.
 
 **Arguments:**
+
 - `prompt` (string, required): The prompt to send to Claude Code.
 - `options` (object, optional):
   - `tools` (array of strings, optional): Specific Claude tools to enable (e.g., `Bash`, `Read`, `Write`). Common tools are enabled by default.
 
 **Example MCP Request:**
+
 ```json
 {
   "toolName": "claude_code:claude_code",
@@ -179,37 +201,37 @@ Here's an example of the Claude Code tool listing files in a directory:
 This server, through its unified `claude_code` tool, unlocks a wide range of powerful capabilities by giving your AI direct access to the Claude Code CLI. 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."`
+    - `"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'."`
+    - **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."`
+    - `"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."`
+    - `"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."`
+    - `"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."`
+    - 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."`
+    - `"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.'"`
+    - `"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."`
+    - `"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
 
@@ -279,4 +301,4 @@ Submit issues and pull requests to the [GitHub repository](https://github.com/st
 
 ## License
 
-MIT
+MIT