Skip to main content
Glama
README.md
# SprintLens MCP

**A sprint-health lens for AI assistants: Jira sprint health — burndown anomalies, scope creep, blocked items, capacity risk — exposed as read-only MCP tools.**

Built for **Atlassian Codegeist 2026** — category *Apps for Software Teams*, bonus target *Best app with Atlassian MCP*.

SprintLens is a Forge app whose `rovo:mcp` module exposes two tools that any MCP-compatible AI assistant (Rovo Studio agents, or third-party clients such as Claude once an admin enables external exposure) can call:

- **`get_sprint_health`** — a structured health snapshot of a sprint: overall level (`healthy` / `at-risk` / `critical`), a 0–100 score, progress and scope statistics, and every finding from the rule engine, each citing the issues behind it.
- **`list_risks`** — just the risk findings, filterable by minimum severity and by rule.

Both tools are **read-only** (the app requests only `read:jira-work`) and every number they return is computed by a deterministic rule engine over live Jira data — never hard-coded, never guessed. Where Jira cannot answer a question (per-member capacity), SprintLens says so in the result instead of assuming everything is fine.

> Status: **skeleton (built ahead of the M3 slot in the project plan)**. The rule engine, tool layer, manifest and Forge wiring are in place and unit-tested locally against constructed data. Deploying needs an Atlassian developer site — see "Deploy once accounts exist" below.

## Why

"How is the sprint going?" is asked in every standup, and answered from a burndown screenshot and a feeling. The signals that actually predict a blown sprint — scope quietly growing after the start, work blocked behind one bottleneck issue, one developer loaded at 180% of capacity, nothing completing for four days — are all sitting in Jira, unassembled. SprintLens assembles them into a verdict an AI assistant can quote with citations, so a team can ask its assistant the question and get an answer with receipts.

## Architecture

```
manifest.yml                  Forge app declaration
├─ modules.rovo:mcp           exposes the two actions below as MCP tools
├─ modules.action             get-sprint-health / list-risks (the tool implementations)
└─ modules.function           action handlers -> src/index.ts

src/core/                     PLATFORM-AGNOSTIC health engine (pure functions)
├─ types.ts                   SprintInput / SprintHealthResult / Finding ...
├─ config.ts                  thresholds + validation (tunable, never hard-coded)
├─ evaluate.ts                rule engine: burndown vs calendar, stall, scope creep,
│                             blocked items, capacity, unassigned/unestimated work,
│                             endgame crunch, stale work -> level + score + findings
└─ report.ts                  plain-text rendering carried in tool responses

src/mcp/                      TOOL LAYER (the MCP contract)
└─ tools.ts                   tool definitions (names, descriptions, JSON Schemas)
                              + handlers over the SprintSource interface

src/data/                     DATA SEAM
├─ sprintSource.ts            SprintSource interface + sprint selector
└─ mockSource.ts              constructed-data source for demo/tests

src/forge/                    Atlassian-facing layer (only place that knows Jira payloads)
├─ jiraSprintClient.ts        JiraSprintSource: Jira Agile REST -> SprintInput
└─ handlers.ts                Forge action handlers (payload -> tool layer)

src/demo/                     constructed data + CLI demo (no account needed)
test/                         node:test unit tests for the engine and the tool layer
skill.md                      open-source guide teaching third-party agents to use the tools
```

**Design rule** (shared with the sibling app ReleaseGate): the health logic never touches `@forge/api`. A `SprintSource` maps Jira data into `SprintInput`; the core returns a `SprintHealthResult`. That is what makes the engine fully testable offline and the thresholds honestly configurable instead of demo-hard-coded.

### Rules (defaults; all thresholds live in `src/core/config.ts`)

| Rule | Default behaviour |
|---|---|
| `burndown-behind` | Done-ratio lags the elapsed-time ratio by > 15% → warning; > 35% → **blocker** |
| `burndown-stalled` | No completion for > 2 days once ≥ 40% of the sprint has elapsed → warning |
| `scope-creep` | Points added after sprint start > 10% of the original commitment → warning; > 25% → **blocker** |
| `blocked-item` | Open blocked issue → warning; **blocker** if it carries blocker priority or blocks ≥ 2 other issues |
| `capacity-overload` | A member's open load > 100% of remaining capacity → warning; > 125% → **blocker** |
| `capacity-unverified` | No capacity data supplied → info (Jira tracks none natively; reported, never assumed fine) |
| `unassigned-work` | Open issues without an assignee beyond tolerance (default 0) → warning |
| `unestimated-work` | > 20% of issues have no story-point estimate → warning |
| `endgame-crunch` | In the final 2 days, > 30% of work still open → warning; > 50% → **blocker** (also fires on an overrun sprint still marked active) |
| `stale-in-sprint` | Open issue untouched for > 3 days during an active sprint → warning |
| `no-issues` | Empty sprint → info |

Level: any blocker → **CRITICAL**; else any warning → **AT RISK**; else **HEALTHY**. Score = 100 − 35·blockers − 10·warnings (informational; info findings never deduct).

## Run it locally (no Atlassian account needed)

```bash
npm test     # unit tests over the health engine and the tool layer (node --test)
npm run demo # CLI demo: both tools over constructed data via the mock source
```

The demo runs two constructed sprints:

- **Sprint 24 "Payments platform"** — 64% elapsed, 71% of points done, no scope change, nobody overloaded → **HEALTHY, 100/100**, zero findings.
- **Sprint 25 "Checkout revamp"** — burndown 66 points of lag, nothing completed for 5 days, 52% scope creep, a blocked bottleneck, one developer at 180% load, unassigned and unestimated work, one day left with 72% still open → **CRITICAL** with the full cited findings list, plus the `list_risks` blocker-only view.

## Deploy once accounts exist

Prerequisites (user steps, from the project plan): a **Devpost account** and an **Atlassian account with a free Cloud developer site** (developer.atlassian.com/cloud). Nothing here registers accounts on anyone's behalf.

```bash
npm install -g @forge/cli        # >= 13.3.0 required (rovo:mcp tutorials)
forge login                      # user's Atlassian account
forge register                   # replaces the placeholder app.id in manifest.yml
forge deploy
forge install                    # into the developer site
```

After install, the tools are immediately available to custom agents in Rovo Studio. To let third-party MCP clients connect, a site/org admin enables external exposure for the installation; clients then reach the tools at `https://mcp.atlassian.com/forge/<appId>` (the UUID part of `app.id`). See `skill.md` for the agent-side usage guide.

Known skeleton-stage TODOs (also flagged inline as `TODO(verify-at-deploy)` / `TODO(M2)`): the story-points and flagged field ids are site-specific and must be resolved per site; sprint scope-change and completion timestamps are approximated from `created`/`updated` until the changelog mapping lands; per-member capacity has no Jira source yet, so the engine reports it as unverified.