@codesherlock/codesherlock-alpha-mcp-server 0.0.28 → 0.1.3

package/.env

@@ -3,7 +3,6 @@
 # Backend API Configuration
 BACKEND_API_URL=https://api.dev.codesherlock.ai
 
-
 # Application Insights Configuration
 APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=9a687b23-0384-4345-abaa-4e7065b0d103;IngestionEndpoint=https://eastus-8.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus.livediagnostics.monitor.azure.com/;ApplicationId=9e40bff2-07af-4326-be55-f5dc98e9e9c3"
 

package/README.md

@@ -1,19 +1,28 @@
-# CodeSherlock MCP Server - Setup & Usage Guide
+# CodeSherlock MCP Server – Setup & Usage Guide
 
-**Key Features:**
-- Analyze uncommitted changes (staged and unstaged files)
-- Analyze committed changes (from your latest commit)
-- Perform security analysis using OWASP Top 10 and CWE frameworks
-- Integration with AI assistants like Claude Desktop, Cline, and other MCP-compatible tools
+Configure the Model Context Protocol server once and keep every commit and working tree scan consistent across your team.
 
----
+## Key Features
+
+### Analyze Uncommitted Changes
+Scan staged and unstaged files before you commit so surprises never reach your repo.
+
+### Analyze Committed Changes
+Review your latest commit to spot issues before pushing to remote or opening a PR.
+
+### Security Framework Coverage
+Run checks aligned to OWASP Top 10 and the CWE catalog for focused security feedback.
+
+### Works With Your AI Assistant
+Connects to AI assistants like Claude Code, Cursor, Windsurf, Cline, VS Code and other MCP-compatible tools via a lightweight server.
 
 ## Prerequisites
 
-Before you begin, ensure you have:
-- Node.js (version [INSERT VERSION HERE]) and npm installed on your system
+Quick checklist to confirm before you start:
+
+- Node.js (version 18.0.0 or higher) and npm installed on your system
 - A Git repository with code you want to analyze
-- An AI coding assistant that supports MCP (e.g., Claude Desktop, Cline, or similar)
+- An AI coding assistant that supports MCP (e.g., Claude Code, Cursor, VS Code, Cline, or similar)
 
 The CodeSherlock MCP Server is available on the npm registry and can be used directly with `npx`.
 
@@ -21,58 +30,264 @@ The CodeSherlock MCP Server is available on the npm registry and can be used dir
 
 ## Step 1: Get Your API Key
 
-CodeSherlock requires an API key to analyze your code. This API Key is used to authenticate your requests to the CodeSherlock API.
-
-### Obtaining Your API Key
+### How to obtain it
 
-1. Visit the CodeSherlock API Key page: **[https://codesherlock.ai/mcp-api-key](https://codesherlock.ai/mcp-api-key)**
-2. Sign in or create an account if you haven't already
-3. Generate a new API key
-4. **Copy and store your API key securely** - you'll need to provide it when prompted
+1. Visit the API key page: [codesherlock.ai/codesherlock-mcp-server/mcp/api/key](https://codesherlock.ai/codesherlock-mcp-server/mcp/api/key)
+2. Sign in or create an account.
+3. Generate a new API key.
+4. Copy and store the key securely—you will be prompted for it by the MCP server.
 
-### Important Security Notes
+### Important security notes
 
-- **Never share your API key** with others
-- **Never commit your API key** to version control
-- Store it in a secure location (password manager recommended)
-- If your key is compromised, regenerate it immediately from the CodeSherlock dashboard
+- Never share your API key or commit it to version control.
+- Store it in a password manager or environment variable.
+- If a key is compromised, regenerate it immediately from your dashboard.
 
 ---
 
 ## Step 2: Configure Your AI Assistant
 
-You need to add the CodeSherlock MCP Server configuration to your AI assistant's settings. Below given are the documentation links for popular AI assistants to setup MCP server:
+You need to add the CodeSherlock MCP Server configuration to your AI assistant's settings. Follow the instructions for your preferred IDE/assistant below.
+
+**Quick Navigation:**
+- [Cursor](#cursor)
+- [Antigravity](#antigravity)
+- [Windsurf](#windsurf)
+- [Claude Code](#claude-code)
+- [VS Code - Co Pilot](#vs-code)
+- [Cline](#cline)
+
+---
 
-- [Cluade Code](https://code.claude.com/docs/en/mcp#option-3%3A-add-a-local-stdio-server)
-- [Cursor](https://cursor.com/docs/context/mcp#using-mcpjson)
-- [VS Code / GitHub Copilot](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+### Cursor
 
-<br/>
+#### Steps to Configure
 
-The general pattern is to specify:
-- **Command**: `npx`
-- **Args**: `[-y, codesherlock-mcp-server]`
-- **Server Name**: `codesherlock`
+1. Click the **Settings** (gear icon) on the top right corner
+2. Settings panel opens as a new tab in the center of the screen
+3. In the settings sidebar, navigate to **Tools & MCP** section
+4. Click on **New MCP Server/Add a custom MCP Server** button
+5. This opens the `mcp.json` config file
+6. Add the configuration below and save
+7. Restart Cursor
+8. Verify the installation: You should see the **CodeSherlock MCP Server** listed with 1 tools **Enabled** and  in the **Tools & MCP** section .
+9. Troubleshooting installation issues: If CodeSherlock MCP Server does not show up in Cursor under Settings → Tools & MCP, or if it appears there but is not enabled or fails to start, open your system terminal and run npx -y @codesherlock/codesherlock-mcp-server manually. This helps confirm that the package can be downloaded and executed successfully outside of Cursor. If this command fails, the issue is likely related to your local Node.js / npm / npx setup, network access, or package resolution rather than Cursor itself. If the command runs successfully in the terminal but the server still does not work inside Cursor, re-check your mcp.json configuration for formatting issues, save the file again, and restart Cursor before trying once more.
 
-#### MCP Configuration JSON:
+#### Configuration
 
 ```json
 {
   "mcpServers": {
     "codesherlock": {
-      "name": "CodeSherlock alpha MCP Server",
-      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
+      "name": "CodeSherlock MCP Server",
+      "description": "CodeSherlock is an AI- based code analysis tool that validates unstaged changes and commits directly inside IDEs and AI Agents. It helps developers catch security, quality, and design issues early by combining deep analysis with compliance-aware checks OWASP, CWE, SOC-2 at the moment code is written. CodeSherlock also performs other security vulnerability reviews along with Maintainability, Reliability and Scalability checks. Use CodeSherlock to review and validate code especially generated via AI.",
       "command": "npx",
-      "args": ["-y", "@codesherlock/codesherlock-alpha-mcp-server"],
+      "args": [
+        "-y",
+        "@codesherlock/codesherlock-mcp-server"
+      ],
       "env": {
-        "CODESHERLOCK_API_KEY": "your-api-key-here"
+        "MCP_API_KEY": "your-api-key-here"
       }
     }
   }
 }
 ```
 
-*After adding the configuration, restart your AI assistant to load the MCP server.*
+---
+
+### Antigravity
+
+#### Steps to Configure
+
+1. In the Antigravity agent chat window, click the **three dots (...)** menu.
+2. This opens the **Manage MCP Servers** page.
+3. On the Manage MCP Servers page, click **View raw config**.
+4. Paste the JSON configuration below into the raw config and save.
+5. Click the **Refresh** button on the same **Manage MCP Servers** page.
+6. Restart Antigravity if needed.
+7. Verify the installation: Open the Antigravity chat and you should see the **CodeSherlock MCP Server** tools available when you type `@`. Additionally, you can check the **Manage MCP Servers** page to see if it's listed and connected.
+
+#### Configuration
+
+```json
+{
+  "mcpServers": {
+    "codesherlock": {
+      "name": "CodeSherlock MCP Server",
+      "description": "CodeSherlock is an AI- based code analysis tool that validates unstaged changes and commits directly inside IDEs and AI Agents. It helps developers catch security, quality, and design issues early by combining deep analysis with compliance-aware checks OWASP, CWE, SOC-2 at the moment code is written. CodeSherlock also performs other security vulnerability reviews along with Maintainability, Reliability and Scalability checks. Use CodeSherlock to review and validate code especially generated via AI.",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesherlock/codesherlock-mcp-server"
+      ],
+      "env": {
+        "MCP_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Windsurf
+
+#### Steps to Configure
+
+1. Click on the **Settings** (gear icon) on the top right corner and select **Windsurf Settings** (or press `Ctrl+,`)
+2. In the settings search box, type **mcp**
+3. Find the **MCP Servers** section
+4. Click on **Open MCP Marketplace**
+5. In the MCP Marketplace, click the **Settings** (gear icon) to add a custom server
+6. This opens the `mcp_config.json` config file
+7. Add the configuration below and save
+8. Restart Windsurf
+9. Verify the installation: Go to **Windsurf Settings** > **MCP Servers** and ensure the **CodeSherlock MCP Server** is listed and shows a connected or active status.
+
+#### Configuration
+
+```json
+{
+  "mcpServers": {
+    "codesherlock": {
+      "name": "CodeSherlock MCP Server",
+      "description": "CodeSherlock is an AI- based code analysis tool that validates unstaged changes and commits directly inside IDEs and AI Agents. It helps developers catch security, quality, and design issues early by combining deep analysis with compliance-aware checks OWASP, CWE, SOC-2 at the moment code is written. CodeSherlock also performs other security vulnerability reviews along with Maintainability, Reliability and Scalability checks. Use CodeSherlock to review and validate code especially generated via AI.",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesherlock/codesherlock-mcp-server"
+      ],
+      "env": {
+        "MCP_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Claude Code
+
+#### Steps to Configure
+
+1. Run the following command in your terminal:
+
+```bash
+claude mcp add --transport stdio codesherlock --env MCP_API_KEY=cs_mcp_abcdef -- cmd /c npx -y @codesherlock/codesherlock-mcp-server
+```
+
+2. Verify the configuration by running:
+
+```bash
+claude mcp list
+```
+
+3. If the connection is successful, start Claude. If `claude mcp list` fails to connect, try reopening your terminal as an optional troubleshooting step.
+
+**Other useful commands:**
+
+```bash
+claude mcp remove codesherlock   # Remove a server
+```
+
+#### Configuration
+
+**Manually add to config file (optional):**
+
+```json
+{
+  "mcpServers": {
+    "codesherlock": {
+      "name": "CodeSherlock MCP Server",
+      "description": "CodeSherlock is an AI- based code analysis tool that validates unstaged changes and commits directly inside IDEs and AI Agents. It helps developers catch security, quality, and design issues early by combining deep analysis with compliance-aware checks OWASP, CWE, SOC-2 at the moment code is written. CodeSherlock also performs other security vulnerability reviews along with Maintainability, Reliability and Scalability checks. Use CodeSherlock to review and validate code especially generated via AI.",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesherlock/codesherlock-mcp-server"
+      ],
+      "env": {
+        "MCP_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+### VS Code
+
+#### Steps to Configure
+
+*Requires GitHub Copilot extension installed*
+
+1. Press `Ctrl+Shift+P` (Windows) or `Cmd+Shift+P` (macOS) to open Command Palette
+2. Type **MCP:Open User Configuration**
+3. This opens the MCP configuration file
+4. Add the configuration below and save
+5. Restart VS Code
+6. Verify the installation: Open the GitHub Copilot Chat panel and type `@`. You should see the **CodeSherlock MCP Server** tools listed and available for use.
+
+#### Configuration
+
+```json
+{
+  "servers": {
+    "codesherlock": {
+      "name": "CodeSherlock MCP Server",
+      "description": "CodeSherlock is an AI- based code analysis tool that validates unstaged changes and commits directly inside IDEs and AI Agents. It helps developers catch security, quality, and design issues early by combining deep analysis with compliance-aware checks OWASP, CWE, SOC-2 at the moment code is written. CodeSherlock also performs other security vulnerability reviews along with Maintainability, Reliability and Scalability checks. Use CodeSherlock to review and validate code especially generated via AI.",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesherlock/codesherlock-mcp-server"
+      ],
+      "env": {
+        "MCP_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Cline
+
+*Cline is a VS Code extension. Install it from the VS Code marketplace or other supported IDEs.*
+
+#### Steps to Configure
+
+1. Open Cline panel in VS Code
+2. Click on **Manage MCP Servers**
+3. Click on the **Settings** (gear icon)
+4. Click on **Configure MCP Servers** button
+5. This opens the `cline_mcp_settings.json` config file
+6. Add the configuration below and save
+7. Restart VS Code
+8. Verify the installation: Open the Cline panel and go to the **MCP Servers** section. You should see the **CodeSherlock MCP Server** listed with a green status indicator, confirming it is connected and active.
+
+#### Configuration
+
+```json
+{
+  "mcpServers": {
+    "codesherlock": {
+      "name": "CodeSherlock MCP Server",
+      "description": "CodeSherlock is an AI- based code analysis tool that validates unstaged changes and commits directly inside IDEs and AI Agents. It helps developers catch security, quality, and design issues early by combining deep analysis with compliance-aware checks OWASP, CWE, SOC-2 at the moment code is written. CodeSherlock also performs other security vulnerability reviews along with Maintainability, Reliability and Scalability checks. Use CodeSherlock to review and validate code especially generated via AI.",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesherlock/codesherlock-mcp-server"
+      ],
+      "env": {
+        "MCP_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
 
 ---
 
@@ -82,34 +297,37 @@ Once configured, you can start using CodeSherlock by prompting your AI assistant
 
 ### Analysis Types
 
-CodeSherlock supports three analysis factors:
+CodeSherlock supports four analysis factors:
 
 | Factor | Description |
 |--------|-------------|
-| **power analysis** | A A full-spectrum scan that covers the most essential and critical issues |
+| **power_analysis** | A full-spectrum scan that covers the most essential and critical issues |
 | **owasp** | Security analysis based on OWASP Top 10 vulnerabilities |
-| **cwe** | Analyzes code against Common Weakness Enumeration (CWE) framework |
+| **cwe_mitre** | Analyzes code against Common Weakness Enumeration (CWE) MITRE framework |
+| **cwe_kev** | Analyzes code against CWE Known Exploited Vulnerabilities (KEV) catalog |
 
 ---
 
 ## Example Prompts
 
-Here are practical examples of how to prompt your AI assistant to perform code analysis:
+Drop these into your AI assistant to kick off a scan:
 
 ```
 "Review my uncommitted changes using CodeSherlock"
 ```
 
 ```
-"Use CodeSherlock to check my uncommitted code for CWE vulnerabilities"
+"Use CodeSherlock to check my uncommitted code for CWE MITRE vulnerabilities"
 ```
 
 ```
 "Analyze my latest commit for OWASP vulnerabilities using CodeSherlock"
 ```
+
 ```
-"Check the last commit in my current repo for CWE issues with CodeSherlock"
+"Check the last commit in my current repo for CWE KEV issues with CodeSherlock"
 ```
+
 ---
 
 ## Understanding the Results
@@ -128,52 +346,109 @@ The AI assistant will present the analysis results in a readable format, typical
 
 ## Troubleshooting
 
-### Common Issues
+### "Server not found" or "MCP server failed to start"
+
+If the server does not show up in your IDE or fails to start, follow these steps:
+
+1. **Manual Verification**: Run `npx -y @codesherlock/codesherlock-mcp-server` in your system terminal.
+   - **If this fails**: The issue is with your local Node.js/npm configuration or network access, rather than the IDE itself.
+   - **If this succeeds**: The issue is likely with your IDE's MCP configuration.
+2. **Check Configuration**: Ensure your configuration file (e.g., `mcp.json`, `cline_mcp_settings.json`) is valid JSON and matches the format provided in the instructions above.
+3. **Restart your IDE**: Most AI assistants and IDEs require a full restart to pick up changes in MCP configuration files.
 
-#### "Server not found" or "MCP server failed to start"
-**Solution:**
 - Verify the configuration file path is correct
 - Check that Node.js and npm are properly installed
 
-#### "Authentication failed" or "Invalid API key"
-**Solution:**
+### "Authentication failed" or "Invalid API key"
+
 - Verify your API key is correctly added to the configuration
 - Check for any extra spaces or characters in the API key
 - Regenerate your API key from the CodeSherlock dashboard
 - Ensure you've restarted your AI assistant after adding the key
 
-#### "Not a Git repository"
-**Solution:**
+### "Not a Git repository"
+
 - Ensure you're analyzing a directory that contains a `.git` folder
 - Initialize a Git repository if needed: `git init`
 
-#### "No changes to analyze"
-**Solution:**
+### "No changes to analyze"
+
 - For uncommitted analysis: Make sure you have modified files
 - For commit analysis: Verify the commit exists using `git log`
 - Check that you're in the correct Git repository
 
-#### Analysis takes too long or times out
-**Solution:**
+### Analysis takes too long or times out
+
 - Start with analyzing specific files or smaller changesets
 - Check your internet connection
 - Break large changes into smaller commits for analysis
 
+### General MCP host installation/run issues
+
+If you encounter errors while installing or running the CodeSherlock MCP Server in any MCP host (Cursor, VS Code, etc.), try the following steps:
+
+1. **Clear NPX cache**
+
+   Remove the cached package to force a fresh download:
+
+   - **macOS/Linux**
+
+     ```bash
+     rm -rf ~/.npm/_npx
+     ```
+
+   - **Windows (PowerShell)**
+
+     ```powershell
+     Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
+     ```
+
+2. **Restart the MCP host**
+
+   Close and reopen your MCP host application (Cursor, VS Code, etc.) to ensure all connections are reset and the server is reloaded properly.
+
+3. **Verify Node.js version**
+
+   Ensure you have Node.js v18 or higher installed:
+
+   ```bash
+   node --version
+   ```
+
+4. **Contact support**
+
+   If the issue persists after trying the above steps, please contact us at [contact@fintechglobal.center](mailto:contact@fintechglobal.center).
+
+### Debugging NPX Execution
+
+If you need to troubleshoot how the MCP client executes the server, understanding the internal `npx` behavior can be helpful:
+
+- **Execution Flow:** The MCP client runs `npx -y @codesherlock/codesherlock-mcp-server`. The `-y` flag ensures non-interactive execution by automatically skipping installation prompts.
+- **Cache Location:** `npx` does not install the package globally. Instead, it downloads and caches it temporarily:
+  - **Windows:** `%LOCALAPPDATA%\npm-cache\_npx\`
+  - **Mac/Linux:** `~/.npm/_npx/`
+- **Executable Resolution:** `npx` reads the downloaded package's `bin` field and maps it to execute `build/index.js` under the hood.
+- **Environment Variables:** The `MCP_API_KEY` configured in your client settings is securely injected into the isolated Node.js process at runtime.
+
 ---
 
 ## Best Practices
 
 ### 1. Integrate into Your Workflow
+
 - **Before committing**: Analyze uncommitted changes to catch issues early
 - **After committing**: Review commits before pushing to remote
 - **During code review**: Use analysis results to supplement manual reviews
 
 ### 2. Choose the Right Analysis Factor
+
 - **Use OWASP** Best for web applications and APIs; focuses on the OWASP Top 10 and other common web security risks.
-- **Use CWE** Ideal when you need deeper, classification-based coverage of software weaknesses across all domains.
+- **Use CWE MITRE** Ideal when you need deeper, classification-based coverage of software weaknesses across all domains.
+- **Use CWE KEV** Best for identifying known exploited vulnerabilities that are actively being used in attacks.
 - **Use Power Analysis** A broad, high-coverage analysis designed to catch the most essential and critical issues across any type of project (web, mobile, backend, etc.)
 
 ### 3. Act on Results
+
 - Prioritize **Critical** and **High** severity issues immediately
 - Create tickets for **Medium** severity issues
 - Document **Low** severity issues for future refactoring
@@ -182,4 +457,4 @@ The AI assistant will present the analysis results in a readable format, typical
 
 ## Getting Help
 
-If you face any issues, please send us a mail at [support@codesherlock.ai](mailto:support@codesherlock.ai). We will help you resolve the issue as soon as possible.
+If you face any issues, please send us a mail at [support@codesherlock.ai](mailto:support@codesherlock.ai). We will help you resolve the issue as soon as possible.