MCP IDE Server Integration

MCP IDE Server Integration

Kazma includes a native Model Context Protocol (MCP) IDE Server (kazma_gateway/mcp_server.py) running over stdio JSON-RPC 2.0. This allows developer environments like VS Code, Cursor, and Claude Desktop to leverage Kazma’s code search, file operations, and test runner directly inside the editor.

---

Exposed MCP Tools

The IDE server exposes 4 high-leverage development tools:

Tool Name	Risk Tier	Description
search_code	Read-only	Fast regex search with glob filtering (*.py, *.ts) and a 50-result cap.
read_file	Read-only	Line-numbered file reading with offset and limit support (capped at 1MB).
write_file	Danger / HITL	Safe file writer with path traversal protection and 1MB size limit.
run_tests	Danger / HITL	Pytest runner with configurable keyword filters and execution timeouts.

---

Configuration & Setup

1. Enabling in kazma.yaml

Configure the IDE server root and file size caps in your kazma.yaml:

mcp:
  ide_server:
    enabled: true
    root: .                # Project root (defaults to cwd)
    max_file_size: 1048576 # 1 MB maximum file read limit

2. Connecting Claude Desktop / Cursor

Add the following to your claude_desktop_config.json or Cursor MCP settings:

{
  "mcpServers": {
    "kazma-ide": {
      "command": "python",
      "args": ["-m", "kazma_gateway.mcp_server"],
      "env": {
        "KAZMA_SECRET": "your-secure-shared-secret",
        "KAZMA_MCP_IDE_ENABLED": "true"
      }
    }
  }
}

---

Security & Danger Tool Gating

[!IMPORTANT] The MCP IDE server is hardened with fail-closed security guarantees:

1. Secret Key Verification: Danger tools (write_file and run_tests) require a matching KAZMA_SECRET environment variable and parameter token. If unset or mismatched, the operation is immediately rejected.
2. Path Traversal Protection: All paths are resolved and verified to stay within the designated project root. Attempts to navigate outside (e.g. ../../etc/passwd) raise an access violation.
3. Safety Middleware Mapping: Danger operations route through Kazma’s internal SafetyMiddleware.check_sync() to enforce permission policies.