SprintLens MCP
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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data