feat: add MCP server mode for native agent integration

[dean0x]

MCP Server Mode for Native Agent Integration

Parent: #19 (Phase B)
Category: B6 — Platform Integration

Context

AI coding agents increasingly support MCP (Model Context Protocol) for tool discovery and invocation. GRANITE's entire architecture relies on PreToolUse shell hooks — a fragile mechanism that:

• Can't intercept native tools (Read/Grep/Glob bypass Bash, ~60% of file ops invisible)
• Requires per-agent hook scripts (9 different formats)
• Introduces shell injection risk via sh -c
• Bypasses agent deny rules (GRANITE issue #260)

An MCP server lets agents call skim directly as a native tool, not through Bash interception. This eliminates the hook architecture entirely for agents that support MCP.

Design

MCP Tool Definitions

{
  "tools": [
    {
      "name": "skim_read",
      "description": "Read source code with structural transformation. Returns function signatures, types, and structure without implementation details. 60-80% token reduction.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "File path or glob pattern" },
          "mode": { "type": "string", "enum": ["structure", "signatures", "types", "full"], "default": "structure" },
          "max_tokens": { "type": "integer", "description": "Token budget for output" }
        },
        "required": ["path"]
      }
    },
    {
      "name": "skim_run",
      "description": "Run a command with output compression. Structured parsing for test runners, git, and build tools.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "command": { "type": "string", "description": "Command to execute" },
          "args": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["command"]
      }
    }
  ]
}

Implementation

Use the mcp-server crate (or equivalent) to serve skim as a stdio-based MCP server:

# Start MCP server
skim mcp

# In Claude Code settings.json:
{
  "mcpServers": {
    "skim": {
      "command": "skim",
      "args": ["mcp"]
    }
  }
}

Why This Beats Hooks

Dimension	Hook Architecture	MCP Server
Agent support	Per-agent hook scripts	Any MCP-compatible agent
Security	Hook can bypass deny rules	Agent controls permissions
Shell injection	Risk via sh -c	No shell involved
Native tool access	Can't intercept Read/Grep	IS the native tool
Setup complexity	Hook script + settings patch	One JSON config entry
Maintenance	Hook version tracking needed	Binary version = server version

Subcommand

skim mcp              # Start MCP server on stdio
skim mcp --transport stdio  # Explicit stdio (default)

Key Files

• New crates/rskim/src/cmd/mcp.rs — MCP server implementation
• Extend crates/rskim/src/main.rs — Add mcp subcommand

Dependencies

• mcp-server crate (or implement minimal JSON-RPC over stdio)
• Existing skim-core library for all transformation logic

Acceptance Criteria

• skim mcp starts stdio MCP server
• skim_read tool works with single files and glob patterns
• skim_read supports all 4 modes (structure/signatures/types/full)
• skim_read supports max_tokens budget
• skim_run tool works for Phase B command compression (cargo test, git status, etc.)
• Server responds to initialize, tools/list, tools/call MCP methods
• Works with Claude Code MCP configuration
• Works with any MCP-compatible agent without custom hooks

Size: M

Depends on: B0-1 (#39)

Blocks: nothing (additive)