feat: add --proxy mode for transparent HTTP MCP interception

[nikitaclicks]

Summary

• Adds --proxy <url> flag to context-cutter-mcp — makes it a transparent stdio↔HTTP proxy in front of any HTTP MCP server
• Large tool responses (≥ --proxy-threshold, default 2 KB) are stored as handles and replaced with a compact preview; query_handle is injected alongside the upstream tools
• --proxy-token-file delegates auth to a token file (e.g. Claude Code's saved OAuth token), with automatic browser-based re-authentication via OAuth 2.0 + PKCE when the token expires
• MCP server starts immediately so the client handshake completes at once; upstream OAuth + tool discovery runs in the background
• Normal mode (no flags) is completely unchanged

Usage

{
  "clickup": {
    "command": "npx",
    "args": [
      "-y", "context-cutter-mcp",
      "--proxy", "https://mcp.clickup.com/mcp",
      "--proxy-token-file", "~/.claude/clickup-token"
    ]
  }
}

With explicit auth header instead of a token file:

{ "args": ["...", "--proxy-header", "Authorization: Bearer $TOKEN"] }

What Claude sees for large responses

[context-cutter] Response stored (18.3 KB → handle: hdl_a1b2c3d4e5f6)

Preview:
  id: "86cxyz123"
  name: "Fix login bug"
  status: "in progress"
  assignees: Array[2]
  custom_fields: Array[8]

Call query_handle("hdl_a1b2c3d4e5f6", "$.field") to extract specific fields.

CLI flags added

Flag	Default	Description
--proxy <url>	—	Upstream HTTP MCP URL
--proxy-threshold <bytes>	2048	Interception threshold
--proxy-header <K: V>	—	Extra upstream header (repeatable)
--proxy-token-file <path>	—	Bearer token file; re-read per request, auto-OAuth on expiry

Test plan

• cargo test — all Rust unit tests pass
• pytest — Python tests pass including 2 new integration tests (mock HTTP MCP server)
• Normal mode (context-cutter-mcp with no flags) unchanged
• --help shows all proxy flags
• Tested against a real HTTP MCP endpoint — large responses intercepted, query_handle extracted specific fields

🤖 Generated with Claude Code