feat: MCP server for agent-native automation (read-first, RBAC-respecting)

Summary

Provide a first-class MCP (Model Context Protocol) server so AI agents (Claude Code, Cursor, IDE assistants, custom automations) can interact with gocdnext through a standard, typed tool surface — instead of ad-hoc curl/CLI/DB/log spelunking.

It ships as a thin adapter over the existing REST API, not new business logic: one MCP tool ≈ one API endpoint, so RBAC, audit and validation are inherited, not re-implemented.

Motivation

Agent-driven ops are already how people reach for these systems. Diagnosing a failed deploy today means, by hand: querying the DB for a run's cause_detail, tailing an archived job's logs, checking the running image via kubectl, cross-referencing DORA. Every one of those is a natural MCP read tool. Making them first-class:

• turns "why did this run fail / what's deployed / show me the failing job's tail" into a single agent round-trip;
• fits gocdnext's "modern CI/CD" positioning — agent-native interaction is a real differentiator vs. incumbents;
• is cheap, because the API + CLI already define the surface.

Guardrails (non-negotiable — the design must hold these)

1. Reuse RBAC + audit; never bypass them. The MCP server authenticates with a gocdnext API token that already carries a role (admin / maintainer / viewer). Every call goes through the SAME REST endpoints, so audit_events and role checks apply for free. No privileged side door, no parallel authorization path.
2. Read-first. Phase 1 is strictly read-only (status, logs, DORA, findings, environments, pipelines). Near-zero blast radius; ship it, prove value, then expand.
3. Writes are phased and gated. trigger / rerun / redeploy / rollback land in Phase 2, behind explicit server config and the token's role, and always audited.
4. Approval gates are NEVER agent-approvable. The whole point of a gate is human judgment. The MCP may surface what's pending and who can approve — it must not expose an "approve" tool. Human-in-the-loop stays human.
5. Secrets: name only, never value. Same contract as the rest of the system (reference model + LogMasks). The MCP must not become a secret-exfiltration route: it can list secret names and where they're used, never resolve a value.

Proposed scope

v1 — read-only (the 80% use: an agent investigating / reporting)

• get_run / list_runs — status, cause, counter, timings
• get_run_detail / get_job_logs — including archived logs (head + tail + omitted), tolerant of the cold-archive path
• dora_metrics — deployment frequency, lead time, CFR, MTTR (by project/label)
• security_findings — per-project SARIF rollup + triage state
• list_environments / current_deploy — what's deployed where
• get_pipeline — resolved pipeline definition / stage-job graph

v2 — write, gated (opt-in, role-checked, audited)

• trigger_pipeline, rerun_run, rerun_job, redeploy_current, rollback

Explicitly out of scope

• Approving/rejecting approval gates
• Reading secret values
• Any RBAC / user / token administration

Design notes / open questions

• Adapter, not a fork of the API. Tools should call the REST endpoints (which enforce RBAC/audit) rather than reach into the store, so the two can't drift.
• Transport: stdio for local dev; consider a hosted/streamable-HTTP variant later for shared/cloud agents (auth via the same API token).
• Token scoping: should the MCP honor a reduced token scope (e.g. read-only tokens) so an org can hand an agent a viewer-only token? Likely yes — lean on the existing api_tokens + role model.
• Rate limiting / pagination: reads over runs/logs need sane caps so an agent can't hammer the control plane.

Acceptance (v1)

• MCP server exposes the read tools above, authenticating via an API token.
• Every tool call resolves to an existing REST endpoint (RBAC + audit inherited).
• A viewer-scoped token can only read; no tool can mutate state or reveal a secret value.
• Docs page under docs/ covering setup + the tool catalog + the guardrails.

Start by inventorying the existing REST endpoints and API-token role checks that the adapter must reuse, then inspect the LogMasks and archived-log contracts mentioned in the issue. Define the read-only tool surface and stdio transport around those entry points, and add the required docs/ page. Done means every v1 tool maps to an audited REST call, viewer tokens cannot mutate or reveal secret values, and the acceptance list is covered.