feat(mcp): HTTP transport, Devin pack, verified fix, sampling/roots

[alxxjohn]

Overview

This branch turns codeguard into a more complete MCP-capable agent integration surface.
It adds a production-ready MCP server with stdio and Streamable HTTP transports, expands the MCP API beyond basic scan/explain flows, and introduces verified auto-fix workflows that can generate, verify, and optionally apply changes safely.

What’s New

MCP server expansion

• Adds codeguard serve --mcp support for a broader MCP surface:
  • tools: scan, validate_config, validate_patch, explain, list_rules, verify_fix, propose_fix, apply_fix
  • resources: codeguard://rules, codeguard://config, codeguard://rules/{rule_id}
  • prompts: review-diff, triage-findings, explain-rule
• Adds protocol negotiation support for current and compatibility MCP versions.
• Adds tool annotations and structured output schemas so hosts can reason about destructive vs read-only actions.

Verified auto-fix flow

• Adds verify_fix to validate a caller-supplied unified diff in an isolated workspace.
• Adds propose_fix to generate a candidate fix and then verify it before returning it.
• Adds apply_fix to verify a diff and only then write it to disk.
• Adds fail-closed behavior for verification failures, including structured failure payloads with attempted diffs and remaining findings.
• Adds optional user confirmation for apply_fix through MCP elicitation when the host supports it.

Server-initiated MCP client capabilities

• Adds support for server-to-client sampling, roots, and elicitation.
• Uses sampling to generate fixes via the connected client’s LLM when available.
• Uses roots to widen allowed config_path confinement safely.
• Caches client roots per connection and invalidates them on notifications/roots/list_changed.

Streamable HTTP transport

• Adds codeguard serve --mcp --http for remote and cloud-hosted agents.
• Supports:
  • JSON-RPC POST
  • SSE streaming for tools/call progress and server-initiated requests
  • session lifecycle via Mcp-Session-Id
  • optional bearer auth
  • request size and concurrency limits
  • health checks via /healthz
  • graceful shutdown

Agent and host integrations

• Adds Devin integration examples and host scripts for both HTTP and stdio MCP setups.
• Expands integration docs for MCP usage, transport behavior, and verified fix workflows.
• Updates agent-facing docs to reflect the larger MCP feature set and supported host patterns.

Implementation Notes

• Refactors the MCP CLI implementation into smaller transport-, tool-, prompt-, resource-, and fix-specific files.
• Separates transport-neutral dispatch logic from HTTP/session/stream handling.
• Adds shared client bridge, request correlation, progress, and path-confinement helpers.

Testing

• Adds and expands MCP smoke coverage for:
  • stdio request/response flows
  • resources and prompts discovery
  • scan progress streaming
  • verified fix fail-closed behavior
• Adds HTTP transport tests for:
  • initialize and capabilities
  • auth enforcement
  • SSE tool streaming
  • resource and prompt access
  • server-initiated sampling and roots
• Adds helper-driven MCP tests to keep the end-to-end coverage readable and maintainable.

User Impact

• Local editor and CLI-hosted agents can use codeguard as an MCP server over stdio.
• Remote/cloud agents such as Devin can connect over HTTP.
• Agents can now:
  • scan repos
  • validate candidate diffs before applying them
  • fetch rule/config resources directly
  • use built-in prompt workflows
  • request verified fixes with optional host-provided LLM support

Validation

• MCP CLI package tests pass locally.
• MCP integration tests pass, including HTTP transport coverage when run with localhost port binding available.