API Reference — Code Scalpel

MCP Protocol

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

Server Startup

# Start MCP server
codescalpel mcp

# With custom options
codescalpel mcp --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

Code Scalpel can also be used directly as a Python library for custom integrations.

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"
)