code-scalpel 3.2.8
MCP server toolkit for AI agents - surgical code analysis and modification
License: MIT
Requires Python: >=3.10
Keywords: ai-agents, ast, autogen, code-analysis, crewai, mcp, pdg, static-analysis, symbolic-execution

# Code Scalpel

[![PyPI version](https://badge.fury.io/py/code-scalpel.svg)](https://pypi.org/project/code-scalpel/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-4388%20passed-brightgreen.svg)](https://github.com/tescolopio/code-scalpel)
[![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)](release_artifacts/README.md)

**MCP Server Toolkit for AI Agents - v3.2.0 "Release Solidification"**

Code Scalpel enables AI assistants (Claude, GitHub Copilot, Cursor) to perform surgical code operations without hallucination. Extract exactly what's needed, modify without collateral damage, verify before applying.

## Installation

```bash
pip install code-scalpel
```

Or with [uv](https://docs.astral.sh/uv/) (recommended for MCP):
```bash
uvx code-scalpel --help
```

## Tier Configuration

Code Scalpel offers three tiers: **Community** (free), **Pro**, and **Enterprise**.

- **Community** (default): Free, full access to basic tools, limited project-wide analysis
- **Pro**: Unlimited project-wide analysis, deep crawling, no file/depth limits
- **Enterprise**: All Pro features plus governance and audit capabilities

**Configure your tier**:
```bash
# Community (default - no configuration needed)
code-scalpel mcp

# Pro (requires license)
export CODE_SCALPEL_TIER=pro
code-scalpel mcp

# Enterprise (requires license)
export CODE_SCALPEL_TIER=enterprise
code-scalpel mcp
```

**📖 Complete tier documentation**: [Tier Configuration Guide](docs/TIER_CONFIGURATION.md)

---

## First-Time Setup

After installation, initialize the configuration directory:

```bash
cd /your/project
code-scalpel init
```

This creates `.code-scalpel/` with governance configuration files:
- `config.yaml` - Unified governance configuration
- `policy.yaml` - OPA/Rego security policies (SQL injection, XSS blocking)
- `budgets.yaml` - Change budget limits (max files, lines, complexity)
- `dev-governance.yaml` - Development governance (AI agent behavior rules)
- `README.md` - Complete configuration guide

**Learn more:** [Governance Configuration](.code-scalpel/README.md) | [Policy Engine](src/code_scalpel/policy_engine/README.md)

---

## What's New in v3.2.0 🎉

### Surgical Extractor Enhancements
Token-efficient code extraction now even more powerful:
- ✅ **Accurate Token Counting** - tiktoken integration for GPT-4/3.5/Claude
- ✅ **Rich Metadata** - Extract docstrings, signatures, decorators, async/generator detection
- ✅ **LLM-Ready Prompts** - `to_prompt()` formats extractions for AI consumption
- ✅ **Token Budget Management** - `trim_to_budget()` intelligently fits token limits
- ✅ **Decorator Extraction** - Extract and analyze decorator definitions
- ✅ **Impact Analysis** - `find_callers()` discovers all code calling a function
- ✅ **Performance Caching** - 2.8x faster with LRU cache

**Example:**
```python
from code_scalpel.surgical_extractor import SurgicalExtractor

extractor = SurgicalExtractor.from_file("app.py")
result = extractor.get_function("process_payment")
print(f"Tokens: {result.token_estimate}")
print(f"Async: {result.is_async}, Generator: {result.is_generator}")
print(f"Decorators: {result.decorators}")

# Find who calls this function (impact analysis)
callers = extractor.find_callers("process_payment")
for name, typ, line in callers:
    print(f"{typ} {name} calls it at line {line}")

# Format for LLM with budget constraint
extraction = extractor.get_function_with_context("process_payment")
prompt = extraction.to_prompt("Add error handling")
trimmed = extraction.trim_to_budget(max_tokens=2000)
```

See [examples/surgical_extractor_enhanced_example.py](examples/surgical_extractor_enhanced_example.py) for full demos.

---

## Quick Start by Server Type

Code Scalpel supports multiple transport methods. Choose based on your use case:

| Transport | Best For | Command |
|-----------|----------|---------|
| **stdio** | Claude Desktop, VS Code, Cursor | `uvx code-scalpel mcp` |
| **HTTP** | Remote access, team servers | `code-scalpel mcp --http --port 8593` |
| **Docker** | Isolated environments, CI/CD | `docker run -p 8593:8593 code-scalpel` |

### Option 1: VS Code / GitHub Copilot (stdio)

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "code-scalpel": {
      "type": "stdio",
      "command": "uvx",
      "args": ["code-scalpel", "mcp", "--root", "${workspaceFolder}"]
    }
  }
}
```

Then in VS Code: `Ctrl+Shift+P` → "MCP: List Servers" → Start code-scalpel

### Option 2: Claude Desktop (stdio)

Add to `claude_desktop_config.json`:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["code-scalpel", "mcp", "--root", "C:\\Projects\\myapp"]
    }
  }
}
```

### Option 3: HTTP Server (Remote/Team)

```bash
# Start HTTP server on port 8593
code-scalpel mcp --http --port 8593

# With LAN access for team
code-scalpel mcp --http --port 8593 --allow-lan

# Health check endpoint (port 8594)
curl http://localhost:8594/health
```

Connect from VS Code:
```json
{
  "servers": {
    "code-scalpel": {
      "type": "http",
      "url": "http://localhost:8593/mcp"
    }
  }
}
```

### Option 4: Docker (Isolated/CI)

```bash
# Run with project mounted
docker run -d \
  --name code-scalpel \
  -p 8593:8593 \
  -p 8594:8594 \
  -v /path/to/project:/project \
  ghcr.io/tescolopio/code-scalpel:3.0.0

# Verify health
curl http://localhost:8594/health
# {"status":"healthy","version":"3.0.0","tools":19}

# Connect via HTTP transport
```

**Docker Compose:**
```yaml
services:
  code-scalpel:
    image: ghcr.io/tescolopio/code-scalpel:3.0.0
    ports:
      - "8593:8593"
      - "8594:8594"
    volumes:
      - ./:/project
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8594/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### Option 5: Cursor IDE

Add to Cursor settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["code-scalpel", "mcp"]
    }
  }
}
```

---

> **v3.0.0 "AUTONOMY" RELEASE** (December 18, 2025)  
> Comprehensive Coverage, Stability, and Autonomy Foundation
>
> | Component | Status | Notes |
> |-----------|--------|-------|
> | Languages | **4** | Python, TypeScript, JavaScript, Java |
> | Security Scanning | **17+ types** | SQL, XSS, NoSQL, LDAP, DOM XSS, Prototype Pollution |
> | Cross-File Analysis | **STABLE** | Import resolution, taint tracking, extraction |
> | MCP Protocol | **COMPLETE** | Health endpoint, Progress tokens, Roots capability |
> | Token Efficiency | **99%** | Surgical extraction vs full file |
> | Performance | **25,000+ LOC/sec** | Project-wide analysis |
> | MCP Tools | **19 tools** | analyze, extract, security, test-gen, cross-file, policy |
> | Test Suite | **4,033 tests** | 94.86% combined coverage |
>
> See [RELEASE_NOTES_v3.0.0.md](docs/release_notes/RELEASE_NOTES_v3.0.0.md) for full details.

---

## The Revolution: Code as Graph, Not Text

Most AI coding tools treat your codebase like a book—they "read" as much as possible to understand context. This hits a hard ceiling: the **Context Window**.

**Code Scalpel changes the game.** It stops treating code as "text" and starts treating it as a **graph**—a deterministic pre-processor for probabilistic models.

### Breaking the Context Window Tyranny

| The Old Way (RAG/Chat) | The Code Scalpel Way |
|------------------------|----------------------|
| "Here are all 50 files. Good luck." | "Here's the variable definition, 3 callers, and 1 test. Nothing else." |
| Retrieve similar text chunks (fuzzy) | Trace variable dependencies (precise) |
| Context limit is a hard wall | Context limit is irrelevant—we slice to fit |
| "I think this fixes it" | "I have mathematically verified this path" |

### Why This Matters

**1. Operate on Million-Line Codebases with 4K Token Models**

Instead of stuffing files into context, Code Scalpel's **Program Dependence Graph (PDG)** surgically extracts *only* the code that matters:

```
User: "Refactor the calculate_tax function"
Old Way: Send 10 files (15,000 tokens) → Model confused
Scalpel: Send function + 3 dependencies (200 tokens) → Precise fix
```

**2. Turn "Dumb" Local LLMs into Geniuses**

Local models (Llama, Mistral) are fast and private but struggle with complex reasoning. Code Scalpel offloads the thinking:

- **Before:** "Does path A allow null?" → Model guesses
- **After:** Symbolic Engine proves it → Model receives fact: "Path A impossible. Path B crashes."

A 7B model + Code Scalpel outperforms a 70B model flying blind.

**3. From Chatbot to Operator (OODA Loop)**

Code Scalpel transforms LLMs from "suggestion machines" into autonomous operators:

1. **Observe:** `analyze_code` → Map the structure
2. **Orient:** `extract_code` → Isolate the bug's ecosystem  
3. **Decide:** `symbolic_execute` → Verify fix mathematically
4. **Act:** `update_symbol` → Apply without breaking syntax

---

## Quick Comparison

| Feature | Traditional Tools | Code Scalpel |
|---------|------------------|--------------|
| Pattern matching (regex) | [COMPLETE] | **Taint tracking** through variables |
| Single file analysis | [COMPLETE] | **Cross-file** dependency graphs |
| Manual test writing | [COMPLETE] | **Z3-powered** test generation |
| Generic output | [COMPLETE] | **AI-optimized** structured responses |
| Context strategy | Stuff everything | **Surgical slicing** |

---

## Quick Demo

### 1. Security: Find Hidden Vulnerabilities

```python
# The SQL injection is hidden through 3 variable assignments
# Regex linters miss this. Code Scalpel doesn't.

code-scalpel scan demos/vibe_check.py
# → SQL Injection (CWE-89) detected at line 38
#   Taint path: request.args → user_id → query_base → final_query
```

### 2. Secret Scanning: Detect Hardcoded Secrets

```python
# Detects AWS Keys, Stripe Secrets, Private Keys, and more
# Handles bytes, f-strings, and variable assignments

code-scalpel scan demos/config.py
# → Hardcoded Secret (AWS Access Key) detected at line 12
# → Hardcoded Secret (Stripe Secret Key) detected at line 45
```

### 3. Analysis: Understand Complex Code

```python
from code_scalpel import CodeAnalyzer

analyzer = CodeAnalyzer()
result = analyzer.analyze("""
def loan_approval(income, debt, credit_score):
    if credit_score < 600:
        return "REJECT"
    if income > 100000 and debt < 5000:
        return "INSTANT_APPROVE"
    return "STANDARD"
""")

print(f"Functions: {result.metrics.num_functions}")
print(f"Complexity: {result.metrics.cyclomatic_complexity}")
```

### 4. Test Generation: Cover Every Path

```bash
# Z3 solver derives exact inputs for all branches
code-scalpel analyze demos/test_gen_scenario.py

# Generates:
# - test_reject: credit_score=599
# - test_instant_approve: income=100001, debt=4999, credit_score=700
# - test_standard: income=50000, debt=20000, credit_score=700
```

## MCP Tools Reference (20 Total)

> Note: the authoritative tool inventory is provided by MCP `list_tools` at runtime; this section is a quick overview.

**Core Tools (v1.0.0)**
| Tool | Description |
|------|-------------|
| `analyze_code` | Parse structure, extract functions/classes/imports |
| `security_scan` | Detect SQLi, XSS, command injection via taint analysis |
| `symbolic_execute` | Explore all execution paths with Z3 |
| `generate_unit_tests` | Create pytest/unittest from symbolic paths |
| `simulate_refactor` | Verify changes are safe before applying |
| `extract_code` | Surgically extract functions/classes with dependencies |
| `update_symbol` | Safely replace functions/classes in files |
| `crawl_project` | Discover project structure and file analysis |

**Context Tools (v1.5.0)**
| Tool | Description |
|------|-------------|
| `get_file_context` | Retrieve surrounding code for specific locations |
| `get_symbol_references` | Find all usages of a symbol across project |
| `get_call_graph` | Generate call graphs and trace execution flow |
| `get_project_map` | Build complete project map and entry points |
| `scan_dependencies` | Scan for vulnerable dependencies (OSV API) |

**Cross-File Tools (v1.5.1)**
| Tool | Description |
|------|-------------|
| `get_cross_file_dependencies` | Build import graphs and resolve symbols |
| `cross_file_security_scan` | Detect vulnerabilities spanning modules |

**v2.5.0+ Tools**
| Tool | Description |
|------|-------------|
| `unified_sink_detect` | Unified polyglot sink detection with confidence |
| `get_graph_neighborhood` | Extract k-hop subgraph around a node |
| `validate_paths` | Validate path accessibility for Docker |
| `verify_policy_integrity` | Cryptographic policy file verification |

## Features

### Polyglot Analysis
- **Python**: Full AST + PDG + Symbolic Execution
- **JavaScript**: Tree-sitter parsing + IR normalization
- **Java**: Enterprise-ready cross-file analysis

### Security Analysis
- SQL Injection (CWE-89)
- Cross-Site Scripting (CWE-79) - Flask/Django sinks
- Command Injection (CWE-78)
- Path Traversal (CWE-22)
- Code Injection (CWE-94) - eval/exec
- Insecure Deserialization (CWE-502) - pickle
- SSRF (CWE-918)
- Weak Cryptography (CWE-327) - MD5/SHA1
- Hardcoded Secrets (CWE-798) - 30+ patterns (AWS, GitHub, Stripe, private keys)
- NoSQL Injection (CWE-943) - MongoDB PyMongo/Motor
- LDAP Injection (CWE-90) - python-ldap/ldap3

### Governance & Policy System (v2.5.0+)
- **OPA/Rego Policies** - Declarative security rules for SQL injection, XSS, dangerous functions
- **Change Budgets** - Quantitative limits (max files, lines, complexity per operation)
- **Semantic Analysis** - Pattern-based vulnerability detection (Python, Java, JavaScript)
- **Unified Governance** - Single evaluation: policy + budget + semantic checks
- **Compliance Reporting** - Enterprise audit trails, security posture scoring
- **Tamper Resistance** - Cryptographic verification, HMAC-signed audit logs
- **Human Override** - TOTP-based approval system with justification
- **Development Governance** - Meta-policies for AI agent behavior (README requirements, architecture boundaries)

See [Policy Engine Documentation](src/code_scalpel/policy_engine/README.md) for details.

### API Contract & Cross-Service Analysis (v3.0.4)
- **Schema Drift Detection** - Protobuf, JSON Schema, GraphQL breaking change detection
- **gRPC Contract Analyzer** - Service definition parsing and validation
- **GraphQL Schema Tracker** - Schema evolution and drift detection
- **Kafka Taint Tracking** - Cross-service async message taint analysis
- **Frontend DOM Input Detection** - XSS risk analysis for React/Vue/Angular

### Performance
- **200x cache speedup** for unchanged files
- **5-second Z3 timeout** prevents hangs
- Content-addressable caching with version invalidation

## CLI Reference

```bash
# Analyze code structure
code-scalpel analyze app.py
code-scalpel analyze src/ --json

# Security scan
code-scalpel scan app.py
code-scalpel scan --code "cursor.execute(user_input)"

# Start MCP server
code-scalpel mcp                              # stdio (Claude Desktop)
code-scalpel mcp --http --port 8593           # HTTP (network)
code-scalpel mcp --root /project --allow-lan  # Team deployment
```

## Docker Deployment

```bash
# Build
docker build -t code-scalpel .

# Run MCP server
docker run -p 8593:8593 -v $(pwd):/app/code code-scalpel

# Connect at http://localhost:8593/mcp
```

## Documentation

### Quick Start
- **[Getting Started](docs/getting_started.md)** - Step-by-step setup and first steps
- **[Documentation Index](docs/INDEX.md)** - Master table of contents for all docs
- **[Examples](examples/)** - Runnable integration examples

### For Contributors
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development setup, workflow, and guidelines
- **[Development Roadmap](DEVELOPMENT_ROADMAP.md)** - Project roadmap and future plans

### Current Release (v3.0.4)
- [Release Notes v3.0.4](docs/release_notes/RELEASE_NOTES_v3.0.4.md) - Stage 3 API Contract & Cross-Service features
- [Release Notes v3.0.0](docs/release_notes/RELEASE_NOTES_v3.0.0.md) - Autonomy release
- [Migration Guide v2.5→v3.0](docs/MIGRATION_v2.5_to_v3.0.md) - Upgrade from v2.5.0
- [API Changes v3.0.0](docs/API_CHANGES_v3.0.0.md) - Complete API reference
- [Known Issues v3.0.0](docs/KNOWN_ISSUES_v3.0.0.md) - Limitations and workarounds

### Core Features
- **[Policy Engine](src/code_scalpel/policy_engine/README.md)** - Enterprise governance with OPA/Rego
- **[Governance System](src/code_scalpel/governance/README.md)** - Unified governance orchestration
- **[Change Budgets](src/code_scalpel/policy/README.md)** - Blast radius control
- **[Graph Engine](docs/graph_engine_guide.md)** - Unified graph analysis
- **[Polyglot Parsers](docs/parsers/DOCUMENTATION_INDEX.md)** - Multi-language support

### Integration & Deployment
- **[AI Agent Integration](docs/agent_integration.md)** - Autogen, CrewAI, LangChain
- **[Docker Quick Start](DOCKER_QUICK_START.md)** - Docker deployment
- **[Deployment Guides](docs/deployment/)** - Production deployment procedures

### Security & Compliance
- **[SECURITY.md](SECURITY.md)** - Security policies and vulnerability reporting
- **[Compliance Documentation](docs/compliance/)** - OWASP, CWE, NIST, PCI DSS, SOC2

## Ninja Warrior Acceptance Harness (Opt-in)

Code Scalpel includes an opt-in acceptance harness that validates MCP behavior across transports against the `Code-Scalpel-Ninja-Warrior` monorepo.

```bash
cd code-scalpel
. .venv/bin/activate

# Fast acceptance (stdio + HTTP + SSE)
RUN_NINJA_WARRIOR=1 \
NINJA_WARRIOR_ROOT=/absolute/path/to/Code-Scalpel-Ninja-Warrior \
python -m pytest -q -m ninja_warrior tests/test_ninja_warrior_acceptance_harness.py

# Heavy mode (adds crawl/map/call-graph)
RUN_NINJA_WARRIOR=1 RUN_NINJA_WARRIOR_HEAVY=1 \
NINJA_WARRIOR_ROOT=/absolute/path/to/Code-Scalpel-Ninja-Warrior \
python -m pytest -q -m ninja_warrior tests/test_ninja_warrior_acceptance_harness.py -k heavy
```

Evidence output:
- Default: `evidence/ninja-warrior/` (gitignored)
- Override: set `NINJA_WARRIOR_EVIDENCE_DIR=/path/to/output`
- Each run emits a JSON evidence report plus (for HTTP/SSE) server logs, including both repo git SHAs (best-effort) for traceability.

## MCP Contract Tests (All Tools, All Transports)

Code Scalpel includes a deterministic contract test that calls **all 20 MCP tools** over:
- `stdio`
- streamable HTTP (`/mcp`)
- SSE (`/sse`)

```bash
cd code-scalpel
. .venv/bin/activate
python -m pytest -q tests/test_mcp_all_tools_contract.py
```

Evidence output:
- Default: `evidence/mcp-contract/` (gitignored)
- Override: set `MCP_CONTRACT_ARTIFACT_DIR=/path/to/output`

Run a single transport (useful for CI or debugging):

```bash
MCP_CONTRACT_TRANSPORT=stdio python -m pytest -q tests/test_mcp_all_tools_contract.py
MCP_CONTRACT_TRANSPORT=streamable-http python -m pytest -q tests/test_mcp_all_tools_contract.py
MCP_CONTRACT_TRANSPORT=sse python -m pytest -q tests/test_mcp_all_tools_contract.py
```

CI also runs Pyright type checking:

```bash
pyright -p pyrightconfig.json
```

## Roadmap

See [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md) for the complete roadmap.

> [20251218_DOCS] Release notes pointer updated for v3.0.0 "Autonomy"

- Latest release notes: [docs/release_notes/RELEASE_NOTES_v3.0.0.md](docs/release_notes/RELEASE_NOTES_v3.0.0.md)

| Version | Status | Release Date | Highlights |
|---------|--------|--------------|------------|
| **v1.5.x** | Released | Dec 13, 2025 | Cross-file analysis, context tools, project intelligence |
| **v2.0.0** | Released | Dec 15, 2025 | **Polyglot** - TypeScript, JavaScript, Java support |
| **v2.5.0** | Released | Dec 17, 2025 | **Guardian** - Policy engine, governance controls |
| **v3.0.0** | Current | Dec 18, 2025 | **Autonomy** - Self-correction, 4033 tests, 94.86% coverage |
| **v3.1.1** | Released | Dec 22, 2025 | **Parser Unification** - Unified extractor, richer docs, init hotfix |
| **v3.2.0** | Planned | TBD | **Release Solidification** - MCP contract tests + blocking CI confidence gates |

**Strategic Focus:** MCP server toolkit enabling AI agents to perform surgical code operations without hallucination.

## Stats

- **4,033** tests passing (100% pass rate)
- **94.86%** combined coverage (statement + branch)
- **100%** coverage: PDG, AST, Symbolic Execution, Security Analysis, Cross-File Analysis
- **4** languages supported (Python, TypeScript, JavaScript, Java)
- **20** MCP tools for AI agents
- **17+** vulnerability types detected (SQL, XSS, NoSQL, LDAP, DOM XSS, Prototype Pollution, secrets)
- **30+** secret detection patterns (AWS, GitHub, Stripe, private keys)
- **200x** cache speedup
- **99%** token reduction via surgical extraction
- **Python 3.13** compatible

## License

MIT License - see [LICENSE](LICENSE)

"Code Scalpel" is a trademark of 3D Tech Solutions LLC.

---

**Built for the AI Agent Era** | [PyPI](https://pypi.org/project/code-scalpel/) | [GitHub](https://github.com/tescolopio/code-scalpel)

<!-- mcp-name: io.github.tescolopio/code-scalpel -->