Skip to content

[20260312_DOCS] Fixed root-relative docs links and added a stable get_capabilities anchor.

API Reference

Technical reference for all Code Scalpel interfaces.

MCP Protocol

Code Scalpel implements the Model Context Protocol (MCP) for AI assistant integration.

Server Startup

# Start MCP server
code-scalpel serve

# With custom options
code-scalpel serve --log-level debug --config /path/to/config

Connection

AI assistants connect via stdio:

{
  "command": "code-scalpel",
  "args": ["serve"],
  "transport": "stdio"
}

Tool Response Format

All tools return a ToolResponseEnvelope:

{
  "data": { ... },           // Tool-specific results
  "error": null,             // Error details if failed
  "tier_applied": "pro",     // Tier used for this call
  "duration_ms": 123,        // Execution time
  "metadata": { ... }        // Additional metadata
}

Error Format

{
  "data": null,
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'calculte' not found in module.py",
    "suggestions": ["calculate", "calculate_total"],
    "details": { ... }
  },
  "tier_applied": "community",
  "duration_ms": 15
}

Error Codes

Code Description
SYMBOL_NOT_FOUND Symbol doesn't exist in file
FILE_NOT_FOUND File path doesn't exist
SYNTAX_ERROR Invalid syntax in code
TIER_LIMIT Operation exceeds tier limits
LICENSE_INVALID License missing or invalid
TIMEOUT Operation timed out
PARSE_ERROR Failed to parse file

Python API

Direct Usage

from code_scalpel import (
    analyze_code,
    extract_code,
    security_scan,
    get_call_graph
)

# Analyze a file
result = analyze_code("src/module.py")
print(result.functions)
print(result.classes)

# Extract a function
code = extract_code(
    file_path="src/module.py",
    target_type="function",
    target_name="process_data"
)
print(code.code)
print(code.dependencies)

# Security scan
vulns = security_scan("src/module.py")
for vuln in vulns.vulnerabilities:
    print(f"{vuln.type}: {vuln.message}")

# Call graph
graph = get_call_graph(
    project_root="./src",
    depth=5
)
print(graph.nodes)
print(graph.edges)

Async API

import asyncio
from code_scalpel.async_api import (
    analyze_code_async,
    cross_file_security_scan_async
)

async def main():
    # Async analysis
    result = await analyze_code_async("src/module.py")

    # Async security scan
    scan = await cross_file_security_scan_async(
        project_root="./src",
        max_depth=5
    )

    print(f"Found {len(scan.vulnerabilities)} issues")

asyncio.run(main())

Tool Specifications

analyze_code

analyze_code(
    file_path: str,              # Path to file
    code: str = None,            # Or provide code directly
    language: str = "auto"       # python, javascript, typescript, java
) -> AnalysisResult

Response:

{
  "file_path": "module.py",
  "language": "python",
  "functions": [
    {
      "name": "func_name",
      "line_start": 10,
      "line_end": 25,
      "parameters": ["arg1", "arg2"],
      "docstring": "Description",
      "complexity": 5
    }
  ],
  "classes": [...],
  "imports": [...]
}

extract_code

extract_code(
    file_path: str,              # Path to file
    target_type: str,            # "function", "class", "method"
    target_name: str,            # Symbol name
    include_context: bool = False,
    include_cross_file_deps: bool = False
) -> ExtractionResult

Response:

{
  "target_type": "function",
  "target_name": "process_data",
  "code": "def process_data(...):\n    ...",
  "line_start": 45,
  "line_end": 78,
  "dependencies": ["helper_func", "DataClass"],
  "token_estimate": 150
}

security_scan

security_scan(
    file_path: str = None,       # Path to file
    code: str = None,            # Or provide code directly
    confidence_threshold: float = 0.7
) -> SecurityResult

Response:

{
  "vulnerabilities": [
    {
      "type": "SQL_INJECTION",
      "severity": "CRITICAL",
      "cwe": "CWE-89",
      "line": 45,
      "function": "get_user",
      "source": "user_id (parameter)",
      "sink": "cursor.execute(query)",
      "taint_flow": [...],
      "confidence": 0.95
    }
  ],
  "summary": {
    "critical": 1,
    "high": 0,
    "medium": 0,
    "low": 0
  }
}

update_symbol

update_symbol(
    file_path: str,              # Path to file
    target_type: str,            # "function", "class", "method"
    target_name: str,            # Symbol name
    new_code: str,               # New implementation
    create_backup: bool = True
) -> UpdateResult

Response:

{
  "file_path": "module.py",
  "target_name": "process_data",
  "status": "updated",
  "backup_path": "module.py.bak",
  "lines_changed": {
    "before": [45, 78],
    "after": [45, 85]
  }
}

get_call_graph

get_call_graph(
    project_root: str = None,    # Project directory
    entry_point: str = None,     # Starting function
    depth: int = 10,             # Max traversal depth
    include_circular_import_check: bool = True
) -> CallGraphResult

Response:

{
  "nodes": [
    {
      "id": "module::function::main",
      "name": "main",
      "file": "app.py",
      "line": 10,
      "type": "function"
    }
  ],
  "edges": [
    {
      "source": "module::function::main",
      "target": "module::function::process",
      "type": "calls"
    }
  ],
  "entry_points": [...],
  "circular_imports": [],
  "mermaid_diagram": "graph TD\n..."
}

CLI Reference

# General
code-scalpel --version
code-scalpel --help

# Serve MCP
code-scalpel serve
code-scalpel serve --log-level debug

# Analyze
code-scalpel analyze <path>
code-scalpel analyze --complexity <path>
code-scalpel analyze --project-map <path>

# Scan
code-scalpel scan --security <path>
code-scalpel scan --dependencies requirements.txt

# Config
code-scalpel config validate
code-scalpel config show

# License
code-scalpel license info
code-scalpel license verify

Configuration Files

config.json Schema

{
  "$schema": "https://codescalpel.dev/schemas/config.json",
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "language": { "type": "string" },
    "license": {
      "type": "object",
      "properties": {
        "path": { "type": "string" },
        "auto_discover": { "type": "boolean" }
      }
    },
    "analysis": {
      "type": "object",
      "properties": {
        "max_file_size_mb": { "type": "number" },
        "exclude_patterns": { "type": "array", "items": { "type": "string" } },
        "include_patterns": { "type": "array", "items": { "type": "string" } }
      }
    },
    "security": {
      "type": "object"
    },
    "output": {
      "type": "object"
    }
  }
}

get_capabilities

Use get_capabilities to inspect the tools, limits, and tier metadata currently exposed by the server.

{
  "tool": "get_capabilities",
  "parameters": {}
}

Use this first when you need to confirm tier-specific limits before running deeper analysis workflows.

Next Steps