diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..54f5346 --- /dev/null +++ b/.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: [18.x, 20.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index f5600f5..da6f041 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ - Managing complex multi-step workflows. - **CRITICAL:** Added explicit guidance and examples on the necessity for the user's prompt to provide Current Working Directory (CWD) context (e.g., "Your work folder is /path/to/project") when operations depend on it. - Added an "Advanced Usage Tip" explaining how to use temporary files to pass large text inputs to Claude, avoiding JSON formatting issues. + - Added GitHub interaction examples (creating PRs, checking CI status) to the `code` tool description in `src/server.ts` and `README.md`. + - Removed 'options.tools' from all documentation. - Updated `README.md` to remove references to `magic_file` and reflect the new, comprehensive `code` tool description. ## [1.3.0] - 2025-05-13 diff --git a/README.md b/README.md index c3c01e9..3132d20 100644 --- a/README.md +++ b/README.md @@ -181,16 +181,11 @@ Once installed and connected to an MCP client, you can invoke the tools using th { "tool_name": "code", "params": { - "prompt": "Your prompt to Claude Code here", - "options": { - "tools": ["Bash", "Read", "Write"] - } + "prompt": "Your prompt to Claude Code here" } } ``` -If no tools are specified, the server enables common tools by default. - #### Prompting Best Practices The more detailed, clear, and well-structured your prompt, the better Claude can understand and execute your intent. For complex tasks, breaking them down into numbered steps within the prompt is highly effective. @@ -237,26 +232,36 @@ Here's a multi-step task: - ``` "Your work folder is /path/to/project - + The 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 + + Create 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 + + Check 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." + ``` + +**Prompting Best Practices:** The more detailed, clear, and well-structured your prompt, the better Claude can understand and execute your intent. For complex tasks, breaking them down into numbered steps within the prompt is highly effective. + ## Tool Descriptions The server provides one tool: 1. **Tool name**: `code` - - **Description**: "**Highly Versatile & Powerful:** Executes a given prompt directly with the Claude Code CLI, bypassing ALL permission checks (`--dangerously-skip-permissions`). This tool is **not limited to simple commands; it can orchestrate complex, multi-step workflows** based on a single, detailed natural language prompt. This includes, but is not limited to: - - Advanced code generation, analysis, and refactoring. - - Performing web searches and summarizing content. - - Executing arbitrary terminal commands (e.g., opening applications, URLs, or files). - - **Sophisticated file system operations:** such as identifying, copying, and moving files (even from outside the immediate project workspace, like the user's Desktop, if precise paths are provided or can be reasonably inferred from the prompt). - - **Comprehensive Git workflows:** including staging specific files, committing with detailed messages, and pushing to remote repositories. - - **Automated file modifications:** like updating READMEs, configuration files, or source code based on instructions. -Essentially, if you can describe a sequence of operations clearly, this tool can attempt to execute it. **Do not hesitate to use this tool for ambitious, multi-step tasks, even if they seem complex.** Best results are achieved with well-structured, detailed prompts. The server **does NOT automatically inject 'Your work folder is...'** context. If the `prompt` requires specific CWD context (for file operations, relative paths, git commands, etc.), the **`prompt` itself MUST explicitly start with 'Your work folder is /path/to/your/project_root'.** Claude executes within the server's CWD, so relative paths in prompts without explicit CWD context will resolve against the server's CWD. Using absolute paths in prompts is often safest if not providing explicit CWD context. Refer to the 'Example: Complex Multi-step Task' below for a concrete demonstration of its capabilities. `options.tools` can be used to specify internal Claude tools (e.g., `Bash`, `Read`, `Write`); common tools are enabled by default if this is omitted." + - **Description**: "Executes a complex **prompt** directly using the Claude Code CLI, bypassing its internal permission checks (`--dangerously-skip-permissions`). This leverages Claude's ability to understand the prompt, reason about the task, and utilize its **internal tools** (like web search, file reading/writing, and bash execution) to achieve the goal. Ideal for complex code generation, analysis, refactoring, running build/test/lint commands (e.g., `npm test`, `pytest`), managing version control (e.g., `git status`, `git commit`), executing multi-step workflows (e.g., '''search for library updates and apply them'''), or performing other tasks requiring integrated reasoning and execution based on a single natural language instruction. Essentially, if you can describe a sequence of operations clearly, this tool can attempt to execute it. **Do not hesitate to use this tool for ambitious, multi-step tasks, even if they seem complex.** Best results are achieved with well-structured, detailed prompts. The server **does NOT automatically inject 'Your work folder is...'** context. If the `prompt` requires specific CWD context (for file operations, relative paths, git commands, etc.), the **`prompt` itself MUST explicitly start with 'Your work folder is /path/to/your/project_root'.** Claude executes within the server's CWD, so relative paths in prompts without explicit CWD context will resolve against the server's CWD. Using absolute paths in prompts is often safest if not providing explicit CWD context. Refer to the 'Example: Complex Multi-step Task' below for a concrete demonstration of its capabilities." - **Parameters**: - `prompt` (required): The prompt to send to Claude Code - - `options.tools` (optional): Array of specific tools to enable - **Implementation**: Uses `claude --dangerously-skip-permissions` (invoked via `child_process.spawn`) to bypass all permission checks. The server locates the Claude CLI by first checking the `CLAUDE_CLI_PATH` environment variable, then looking in `~/.claude/local/claude`, and finally falling back to `claude` in the system PATH. ## Example Screenshots diff --git a/package-lock.json b/package-lock.json index e8325cc..4c04cc0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,13 +1,15 @@ { "name": "claude-mcp-server", - "version": "1.0.0", + "version": "1.4.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "claude-mcp-server", - "version": "1.0.0", + "version": "1.4.0", + "license": "MIT", "dependencies": { + "@eslint/js": "^9.26.0", "@modelcontextprotocol/sdk": "^1.11.2", "zod": "^3.24.4" }, @@ -442,6 +444,15 @@ "node": ">=18" } }, + "node_modules/@eslint/js": { + "version": "9.26.0", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.26.0.tgz", + "integrity": "sha512-I9XlJawFdSMvWjDt6wksMCrgns5ggLNfFwFvnShsleWruvXM514Qxk8V246efTw+eo9JABvVz+u3q2RiAowKxQ==", + "license": "MIT", + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + } + }, "node_modules/@modelcontextprotocol/sdk": { "version": "1.11.2", "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.11.2.tgz", diff --git a/src/server.ts b/src/server.ts index c7da209..72a07b7 100644 --- a/src/server.ts +++ b/src/server.ts @@ -64,9 +64,6 @@ function findClaudeCli(debugMode: boolean): string { */ interface ClaudeCodeArgs { prompt: string; - options?: { - tools?: string[]; - }; } // Ensure spawnAsync is defined correctly *before* the class @@ -189,11 +186,15 @@ The server **does NOT automatically inject 'Your work folder is...'** into your 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."\` -**Prompting Best Practices:** The more detailed, clear, and well-structured your prompt, the better Claude can understand and execute your intent. For complex tasks, breaking them down into numbered steps within the prompt is highly effective. +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."\` -**Advanced Usage Tip:** When working with the \\\`code\\\` tool, you can set up complex workflows by using explicit step-by-step instructions. For example, instead of just asking \\\`"Fix the bugs in my code"\\\`, try: \\\`"Your work folder is /path/to/project\\n\\n1. Run the test suite to identify failing tests\\n2. Examine the failing tests to understand what's breaking\\n3. Check the relevant source files and fix the issues\\n4. Run the tests again to verify your fixes worked\\n5. Explain what you changed and why"\\\` +**Prompting Best Practices:** The more detailed, clear, and well-structured your prompt, the better Claude can understand and execute your intent. For complex tasks, breaking them down into numbered steps within the prompt is highly effective. -\`options.tools\` can be used to specify which internal Claude tools (e.g., \`Bash\`, \`Read\`, \`Write\`) are allowed for the execution; common tools are enabled by default if this is omitted.`, +**Advanced Usage Tip:** When working with the \\\`code\\\` tool, you can set up complex workflows by using explicit step-by-step instructions. For example, instead of just asking \\\`"Fix the bugs in my code"\\\`, try: \\\`"Your work folder is /path/to/project\\n\\n1. Run the test suite to identify failing tests\\n2. Examine the failing tests to understand what's breaking\\n3. Check the relevant source files and fix the issues\\n4. Run the tests again to verify your fixes worked\\n5. Explain what you changed and why"\\\``, inputSchema: { type: 'object', properties: { @@ -201,19 +202,6 @@ The server **does NOT automatically inject 'Your work folder is...'** into your type: 'string', description: 'The detailed natural language prompt for Claude to execute.', }, - options: { - type: 'object', - properties: { - tools: { - type: 'array', - items: { - type: 'string' - }, - description: 'Optional internal Claude tools to enable (e.g., Bash, Read, Write).', - } - }, - description: 'Additional options for Claude Code execution.', - }, }, required: ['prompt'], }, @@ -241,9 +229,6 @@ The server **does NOT automatically inject 'Your work folder is...'** into your } finalCommandArgs = [...baseCommandArgs]; - if (args.options?.tools) { - finalCommandArgs.push('--tools', args.options.tools.join(',')); - } finalCommandArgs.push('-p', claudePrompt); } else {