[20260312_DOCS] Added stable anchor targets used by the current website and onboarding pages.

AI Assistant Integration¶

Learn how to get the most out of Code Scalpel with your AI assistant.

How It Works¶

Code Scalpel acts as an MCP server that AI assistants connect to:

┌─────────────┐     MCP Protocol     ┌──────────────┐
│ AI Assistant│ ◄──────────────────► │ Code Scalpel │
│   (Claude)  │    tool calls        │  MCP Server  │
└─────────────┘                      └──────────────┘
                                            │
                                            ▼
                                     ┌──────────────┐
                                     │  Your Code   │
                                     └──────────────┘

When you ask the AI to analyze code, it:

1. Determines which Code Scalpel tool to use
2. Calls the tool with appropriate parameters
3. Receives structured results
4. Explains the results to you

Claude Desktop¶

Configuration¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "code-scalpel": {
      "command": "code-scalpel",
      "args": ["serve"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/path/to/license.jwt"
      }
    }
  }
}

Restart Claude¶

After saving the config, restart Claude Desktop completely.

Verify Connection¶

Ask Claude:

"What Code Scalpel tools are available?"

You should see a list of tools like analyze_code, extract_code, etc.

VS Code with GitHub Copilot¶

Install MCP Extension¶

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "MCP Client"
4. Install the extension

Configure MCP Server¶

Create .vscode/mcp.json:

{
  "servers": {
    "code-scalpel": {
      "command": "code-scalpel",
      "args": ["serve"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "${env:CODE_SCALPEL_LICENSE_PATH}"
      }
    }
  }
}

Usage with Copilot Chat¶

In Copilot Chat, you can now reference Code Scalpel tools:

"@code-scalpel analyze this file" "@code-scalpel extract the calculate function from utils.py"

Cursor¶

Built-in MCP Support¶

Cursor has native MCP support. Configure in settings:

1. Open Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Add server configuration:

{
  "mcp.servers": {
    "code-scalpel": {
      "command": "code-scalpel",
      "args": ["serve"]
    }
  }
}

Using with Cursor¶

Simply ask questions and Cursor will use Code Scalpel automatically:

"Analyze the security of this file" "Extract the UserService class" "What are the dependencies of process_order?"

API Usage¶

If you're integrating Code Scalpel directly into your own automation, start with the Python API reference and then reuse the same MCP tool workflows shown in this guide.

• Python API - Direct and async usage examples
• MCP Protocol - Transport and protocol details
• Tool Responses - Response envelope and metadata reference

Best Prompting Practices¶

Be Specific About Tools¶

Instead of:

"Look at this code"

Say:

"Use analyze_code to show me the structure of utils.py"

Reference Files by Path¶

"Extract the calculate_total function from src/billing/calculator.py"

Chain Tools Logically¶

"First analyze app.py to understand the structure, then extract the main function, then scan it for security issues"

Ask for Explanations¶

"Analyze this code and explain what each function does"

Example Conversations¶

Code Understanding¶

You: "I'm new to this codebase. Help me understand the project structure."

AI: Uses get_project_map to show: - Package structure - Entry points - Complexity hotspots

Security Review¶

You: "Check this file for security vulnerabilities"

AI: Uses security_scan and explains: - Vulnerabilities found - Taint flow paths - Suggested fixes

Safe Refactoring¶

You: "Refactor the process_data function to be more efficient"

AI: 1. Uses extract_code to get current implementation 2. Creates improved version 3. Uses simulate_refactor to verify behavior preserved 4. Uses update_symbol to apply the change

Tool Selection Guide¶

Debugging AI Issues¶

"Tool not found"¶

Check that: 1. Code Scalpel is installed: code-scalpel --version 2. Server can start: code-scalpel serve 3. Config is correct in your AI's settings

"Analysis failed"¶

Ask the AI to: 1. Validate the path first: validate_paths 2. Show the error details 3. Try with a simpler file

AI Using Wrong Tool¶

Be explicit:

"Use the security_scan tool (not analyze_code) to check for vulnerabilities"

Advanced: Custom Workflows¶

Create a Security Audit Prompt¶

Run a complete security audit:
1. Use get_project_map to understand the structure
2. Use cross_file_security_scan on the entire project
3. Use scan_dependencies to check for vulnerable packages
4. Summarize all findings with severity levels

Create a Refactoring Prompt¶

Help me refactor the {function_name} function:
1. Extract it with extract_code
2. Show me the current implementation
3. Suggest improvements
4. Use simulate_refactor to verify changes
5. Only apply with update_symbol if safe

Limitations¶

What AI + Code Scalpel Can't Do¶

• Execute your code
• Access external APIs (without separate tools)
• Make decisions about business logic
• Guarantee 100% vulnerability detection

What to Watch For¶

• False positives: AI may over-report issues
• Missing context: AI may not understand business requirements
• Scope creep: AI may suggest unnecessary changes

Always review AI suggestions before applying them.

Next Steps¶

• Quick Start - Get started quickly
• Tools Reference - All available tools
• Tutorials - Hands-on learning