Frequently Asked Questions¶

Quick answers to common questions about Code Scalpel.

General¶

What is Code Scalpel?¶

Code Scalpel is an MCP (Model Context Protocol) server that provides AI assistants with surgical code analysis and modification tools. Instead of AI reading entire files and guessing line numbers, Code Scalpel enables precise extraction, analysis, and modification by symbol name.

What AI assistants work with Code Scalpel?¶

Code Scalpel works with any MCP-compatible AI assistant:

• Claude (Desktop and API)
• VS Code GitHub Copilot (via MCP extension)
• Cursor (built-in MCP support)
• Any MCP client (custom integrations)

What languages are supported?¶

Is Code Scalpel free?¶

Yes! The Community tier is free forever and includes:

• Code analysis and extraction
• Basic security scanning
• Symbol updates and renames
• Path validation

Pro and Enterprise tiers add advanced features. See Tier Comparison.

Installation¶

How do I install Code Scalpel?¶

pip install codescalpel

docker pull ghcr.io/codescalpel/code-scalpel

See Installation Guide for platform-specific instructions.

Do I need Python installed?¶

For pip installation, yes (Python 3.10+). For Docker, no—everything is containerized.

How do I configure my AI assistant?¶

Each platform has specific setup:

• Claude Desktop
• VS Code
• Cursor

Tools & Features¶

Why use extract_code instead of reading the file?¶

Traditional file reading has problems:

What's the difference between security_scan and cross_file_security_scan?¶

What is symbolic execution?¶

Symbolic execution explores all possible paths through code by treating variables as symbols:

def example(x):
    if x > 0:
        return "positive"
    else:
        return "non-positive"

Instead of testing x=5, symbolic execution finds:

• Path 1: x > 0 → "positive"
• Path 2: x <= 0 → "non-positive"

See Symbolic Execution Tutorial.

Can I add custom security rules?¶

Yes, with Enterprise tier:

# governance.yaml
compliance:
  custom_rules:
    - id: no-eval
      pattern: "\\beval\\s*\\("
      severity: critical

Tiers & Licensing¶

What's included in each tier?¶

All 22 tools are available at all tiers. What differs are the limits and features:

See Tier Details.

Are certain tools only available in Pro or Enterprise?¶

No. All 22 Code Scalpel tools are available at all tiers (Community, Pro, and Enterprise).

What differs by tier are: - Limits: max_depth, max_nodes, max_files, max_paths per tool - Features: cross-file analysis scope, confidence scoring, custom rules - Results: truncation, precision, scope

For example, symbolic_execute is available in Community (10 paths, depth 3), Pro (100 paths, depth 10), and Enterprise (unlimited).

How do licenses work?¶

Pro and Enterprise licenses are JWT files:

export CODE_SCALPEL_LICENSE_PATH=/path/to/license.jwt

Licenses are: - Cryptographically signed - Time-limited (renewable) - Organization-bound (Enterprise)

Can I try Pro features?¶

Contact us for a trial license:

Request Trial

Security & Privacy¶

Does Code Scalpel send my code anywhere?¶

No. All analysis runs locally. Code Scalpel:

• Does not transmit code to external servers
• Does not require internet for analysis
• Stores results only where you configure

How do I verify policies haven't been tampered with?¶

Use verify_policy_integrity:

{
  "tool": "verify_policy_integrity",
  "parameters": {}
}

This cryptographically verifies .code-scalpel/ files.

Is Code Scalpel safe to use in production?¶

Yes. Code Scalpel:

• Never executes analyzed code
• Creates backups before modifications
• Validates syntax before writing
• Supports air-gapped deployments

Troubleshooting¶

"Symbol not found" error¶

The symbol name doesn't match. Code Scalpel will suggest corrections:

{
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "suggestions": ["calculate", "calculate_total"]
  }
}

Fix: Check spelling or use analyze_code first.

"File not found" error¶

The file path is wrong or doesn't exist.

Fix: Use validate_paths to check:

{
  "tool": "validate_paths",
  "parameters": {
    "paths": ["src/module.py"]
  }
}

Slow analysis¶

Large projects take longer. Try:

1. Add exclude patterns to config.json
2. Reduce max_depth or max_files limits
3. Use Pro tier for better limits
4. Focus on specific directories

License not detected¶

Check:

1. CODE_SCALPEL_LICENSE_PATH environment variable
2. License file permissions
3. License expiration date

code-scalpel license info

Integration¶

Can I use Code Scalpel in CI/CD?¶

Yes! See CI/CD Integration Guide.

# Example GitHub Action
- name: Security Scan
  run: |
    pip install code-scalpel
    code-scalpel scan --security ./src

Can I use Code Scalpel programmatically?¶

Yes, via the Python API:

from code_scalpel import analyze_code

result = analyze_code("path/to/file.py")
print(result.functions)

Or via MCP protocol directly.

Does Code Scalpel work with monorepos?¶

Yes. Configure include/exclude patterns:

{
  "analysis": {
    "include_patterns": [
      "packages/api/src/**/*.py",
      "packages/web/src/**/*.ts"
    ]
  }
}

More Questions?¶

• Troubleshooting Guide - Common issues and solutions
• Community Forum - Ask the community
• GitHub Issues - Report bugs