Skip to content

API Reference

Complete technical reference for the Code Scalpel API, including MCP protocol details, response formats, and error handling.

Overview

Code Scalpel exposes its functionality through the Model Context Protocol (MCP). This section provides detailed documentation for integrating with Code Scalpel programmatically.

Sections

  • MCP Protocol

    Understand the Model Context Protocol and how Code Scalpel implements it.

    Protocol Details

  • Tool Responses

    Standard response format, envelope structure, and data schemas.

    Response Format

  • Error Codes

    Complete error code reference with causes and solutions.

    Error Reference

  • Oracle Middleware

    Automatic error recovery and resilience for AI agents.

    Oracle Middleware

Quick Reference

MCP Server Connection

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

Response Envelope

All tools return a standard envelope:

{
  "data": { ... },           // Tool-specific result data
  "tier_applied": "string",  // community | pro | enterprise
  "duration_ms": 123,        // Execution time in milliseconds
  "error": null              // Error details if failed
}

Error Response

{
  "data": null,
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'process_ordder' not found",
    "suggestion": "Did you mean 'process_order'?",
    "recovery_options": ["process_order", "process_orders"]
  }
}