MCP Server

Table of Contents

1. Transport
2. Tools
- 2.1. Action tools (write, gated + audited)
3. Connecting Claude
4. Authentication
5. Configuration

UniTrack ships a built-in Model Context Protocol (MCP) server so AI assistants (Claude and others) can query its data directly — "what’s flaky in project X?", "did coverage drop on the last run?", "summarize this run’s failures" — answered straight from UniTrack.

It is built on Spring AI's MCP server starter and exposes a set of read-only tools backed by the same services the UI and REST API use. No mutations are possible through MCP.

1. Transport

The server speaks MCP over HTTP+SSE, served by the running web app:

Endpoint Purpose

Endpoint	Purpose
`GET /sse`	Opens the SSE stream; its first event carries the per-session message URI.
`POST /mcp/message`	Client → server JSON-RPC messages (`?sessionId=…`).

GET /sse

Opens the SSE stream; its first event carries the per-session message URI.

POST /mcp/message

Client → server JSON-RPC messages (?sessionId=…).

2. Tools

Tool Description

Tool	Description
`listProjects`	All projects with id, name, repo URL and run count.
`getProjectRuns`	Recent runs for a project (by id or name): status, totals, coverage, commit.
`getRunDetail`	One run’s summary, quality-gate verdict, coverage, and failing tests.
`getQualityGate`	The gate verdict for a run (passed/failed + each rule’s detail).
`getCoverage`	Line/branch coverage percentages and counts for a run.
`getFlakyTests`	Flaky tests for a project (failure rate + status).
`getFailureClusters`	Recent failures grouped by signature, most frequent first.
`summarizeRun`	Triage a red run: gate verdict, total failing, which failures are new vs the baseline (real regressions), and which are already known-flaky (likely noise).
`compareRuns`	Diff two runs (head vs base): newly-failing / fixed / still-failing tests + pass-rate, coverage and duration deltas.

listProjects

All projects with id, name, repo URL and run count.

getProjectRuns

Recent runs for a project (by id or name): status, totals, coverage, commit.

getRunDetail

One run’s summary, quality-gate verdict, coverage, and failing tests.

getQualityGate

The gate verdict for a run (passed/failed + each rule’s detail).

getCoverage

Line/branch coverage percentages and counts for a run.

getFlakyTests

Flaky tests for a project (failure rate + status).

getFailureClusters

Recent failures grouped by signature, most frequent first.

summarizeRun

Triage a red run: gate verdict, total failing, which failures are new vs the baseline (real regressions), and which are already known-flaky (likely noise).

compareRuns

Diff two runs (head vs base): newly-failing / fixed / still-failing tests + pass-rate, coverage and duration deltas.

summarizeRun and compareRuns are analysis tools — they synthesize UniTrack’s unified test/coverage/flaky/regression data so an assistant can explain a build rather than re-derive it from raw stack traces.

Project-scoped tools accept either the numeric id or the exact project name; run-scoped tools take a run id (discover both with listProjects / getProjectRuns).

2.1. Action tools (write, gated + audited)

These tools change state. They are off by default and only become usable when an operator sets unitrack.mcp.writes-enabled=true. Each one requires an authenticated caller with write access to the project, verifies the target actually exists (it won’t act on a hallucinated test or cluster), and appends a row to the audit_entry table recording who did what, where, and via which channel.

Tool Description

Tool	Description
`quarantineFlakyTest`	Set a flaky test’s status to `QUARANTINED`, `RESOLVED` or `ACTIVE` (mute/unmute it against the build).
`createTriageRule`	Create a rule that auto-categorizes failures whose text matches a regex/substring.
`ackFailureCluster`	Acknowledge a failure cluster by routing its signature to a triage category.

quarantineFlakyTest

Set a flaky test’s status to QUARANTINED, RESOLVED or ACTIVE (mute/unmute it against the build).

createTriageRule

Create a rule that auto-categorizes failures whose text matches a regex/substring.

ackFailureCluster

Acknowledge a failure cluster by routing its signature to a triage category.

Every action is recorded in an append-only audit trail. Admins can review it at /audit (linked as Audit in the top nav) — who did what, on which project, through which channel — with an optional per-project filter.

For AI clients, mint a dedicated ACTION-scoped token (Profile → API tokens): it authenticates only on the MCP transport (/sse, /mcp/*) and is rejected everywhere else, so a leaked copilot token can’t browse the UI or REST API — it can only drive these tools, within the owner’s project permissions. A FULL token works too. Writes stay disabled until the server-level flag is on, so the model can *propose an action while a human keeps the final say.

3. Connecting Claude

Point an MCP client at the SSE endpoint. For a self-hosted instance at https://unitrack.example:

{
  "mcpServers": {
    "unitrack": {
      "url": "https://unitrack.example/sse"
    }
  }
}

4. Authentication

The MCP endpoints follow the app’s normal security (see Accounts & API Tokens):

In open mode (the default) they are reachable without credentials.
When open mode is off, send a personal API token on the SSE/message requests — Authorization: Bearer <token> or X-UniTrack-Token: <token>, the same tokens the REST API uses.

5. Configuration

unitrack:
  mcp:
    writes-enabled: false   # set true to expose the gated action tools (off by default)

spring:
  ai:
    mcp:
      server:
        name: unitrack
        version: 0.1.0
        instructions: >-
          Guidance shown to the assistant on how to use the tools.