feat: MCP server — expose rules and config to AI coding agents #207

Summary

Build an MCP (Model Context Protocol) Server for Cora that allows AI coding agents (Claude Code, Cursor, Copilot, Windsurf, Codex, etc.) to query Cora's rules, project config, and review history in real-time. This transforms Cora from a post-commit review tool into a real-time coding guidance layer.

Motivation

• SonarQube just shipped MCP Server — this is where the market is going. AI agents need a way to query quality rules before generating code, not just get reviewed after.
• Shift-left on steroids — instead of "write code → review → fix", agents can "check rules → write correct code → review confirms"
• Cora becomes a platform — MCP makes Cora embeddable into any AI agent workflow. Every agent that supports MCP becomes a potential Cora user.
• Reduced review cycles — if agents already know the rules, they generate cleaner code, reducing review round-trips.

Current vs Proposed Flow

CURRENT (reactive):
  Developer → AI Agent → generates code → commits → PR → Cora Review → finds issues → fix → re-review
  
PROPOSED (proactive):
  Developer → AI Agent → queries Cora MCP → gets rules/context → generates cleaner code → commits → PR → Cora Review → confirms quality

MCP Tools to Expose

1. cora.list_rules

Returns all active rules for the current project (from .cora.yaml + built-in rules).

// Request
{ "method": "tools/call", "params": { "name": "cora.list_rules", "arguments": {} } }

// Response
{
  "rules": [
    { "id": "security/no-hardcoded-secrets", "severity": "critical", "description": "Never hardcode API keys..." },
    { "id": "rust/no-unwrap", "severity": "high", "description": "Avoid unwrap() in production code..." },
    { "id": "style/naming-convention", "severity": "low", "description": "Use snake_case for Rust functions..." }
  ],
  "total": 15,
  "project": "trapfall"
}

2. cora.check_snippet

Quick-check a code snippet against project rules without a full review.

// Request
{
  "method": "tools/call",
  "params": {
    "name": "cora.check_snippet",
    "arguments": {
      "code": "let val = data.unwrap();",
      "language": "rust",
      "context": "This is in the auth handler"
    }
  }
}

// Response
{
  "findings": [
    {
      "rule": "rust/no-unwrap",
      "severity": "high",
      "message": "unwrap() can panic at runtime. Use match or ? operator instead.",
      "suggestion": "let val = data.ok_or(AuthError::InvalidData)?;"
    }
  ],
  "snippet_ok": false
}

3. cora.get_quality_gate

Returns the project's quality gate configuration.

// Response
{
  "gate": {
    "max_critical": 0,
    "max_high": 3,
    "max_security": 0,
    "min_quality_score": 7.0,
    "categories": {
      "security": { "action": "block", "max_findings": 0 },
      "performance": { "action": "warn", "max_findings": 5 }
    }
  }
}

4. cora.get_recent_findings

Returns findings from the last N reviews for this project. Helps agents learn from past mistakes.

// Request
{
  "method": "tools/call",
  "params": {
    "name": "cora.get_recent_findings",
    "arguments": { "count": 5, "category": "security" }
  }
}

// Response
{
  "findings": [
    {
      "date": "2026-06-05",
      "file": "src/auth.rs",
      "message": "Hardcoded secret detected",
      "severity": "critical",
      "resolved": true
    }
  ],
  "patterns_to_avoid": [
    "Avoid using unwrap() in auth handlers — caused 2 findings",
    "Always validate input length — caused 1 finding"
  ]
}

5. cora.get_config

Returns the effective Cora configuration for this project.

// Response
{
  "config": {
    "language": "rust",
    "profile": "strict",
    "focus_areas": ["security", "error_handling"],
    "ignore_paths": ["**/test/**"]
  }
}

Architecture

src/
├── mcp/
│   ├── mod.rs               # NEW: MCP server entry point
│   ├── server.rs            # NEW: JSON-RPC server implementation
│   ├── tools.rs             # NEW: Tool handlers (list_rules, check_snippet, etc.)
│   ├── transport.rs         # NEW: stdio transport (for CLI integration)
│   └── protocol.rs          # NEW: MCP protocol types
├── commands/
│   └── mcp.rs               # NEW: `cora mcp` subcommand to start server
└── engine/
    ├── rules_engine.rs      # MODIFY: Expose rules for MCP queries
    └── secrets_scanner.rs   # MODIFY: Expose patterns for MCP queries

Transport

MCP uses stdio (stdin/stdout) for communication. The server runs as a long-lived process:

# Start MCP server (called by AI agent)
cora mcp

# The agent communicates via JSON-RPC over stdin/stdout

.cora.yaml Configuration

mcp:
  enabled: true
  # Which tools to expose
  tools:
    - list_rules
    - check_snippet
    - get_quality_gate
    - get_recent_findings
    - get_config
  # Rate limiting
  max_requests_per_minute: 60
  # check_snippet limits
  max_snippet_lines: 50

Integration Points

Claude Code

// claude_desktop_config.json or .mcp.json
{
  "mcpServers": {
    "cora": {
      "command": "cora",
      "args": ["mcp"]
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "cora": {
      "command": "cora",
      "args": ["mcp"]
    }
  }
}

VS Code (Copilot)

// .vscode/mcp.json
{
  "servers": {
    "cora": {
      "type": "stdio",
      "command": "cora",
      "args": ["mcp"]
    }
  }
}

Implementation Checklist

• Research MCP protocol spec (https://modelcontextprotocol.io/specification)
• Create src/mcp/ module with protocol types
• Implement JSON-RPC server with stdio transport
• Implement cora mcp subcommand
• Implement cora.list_rules tool handler
• Implement cora.check_snippet tool handler (lightweight, no LLM call)
• Implement cora.get_quality_gate tool handler
• Implement cora.get_recent_findings tool handler
• Implement cora.get_config tool handler
• Add .cora.yaml MCP config section
• Add rate limiting per tool
• Write unit tests for each tool handler
• Write integration test: full MCP session (start → query → response)
• Test with Claude Code (install locally, verify tool discovery)
• Test with Cursor (install locally, verify tool discovery)
• Create MCP integration docs for README
• Create example .mcp.json files for major agents

Phased Rollout

Out of Scope (Future)

• cora.learn — two-way MCP where agents submit new rules (v0.6+)
• SSE/HTTP transport (stdio is sufficient for MCP spec)
• Multi-project MCP server (single project per server instance is fine)
• Remote MCP (MCP is local-first by design)

References

• MCP Specification
• SonarQube MCP Server — competitive reference
• MCP TypeScript SDK — protocol reference