# Spira MCP

Read-only Cursor MCP for daily Spira incident reviews against
`https://<OrgID>.spiraservice.net`.

## What it does

- **`incident_daily_digest`** — markdown digest of incidents filtered by product, status, owner, detected release, and optional incident IDs; includes description, last N comments, and attachment metadata (AttachmentIds)
- **`list_incident_filter_options`** — statuses, owners, and releases for picking filter labels
- **`list_incident_attachments`** — list documents on a single incident
- **`download_incident_attachment`** — download a file attachment into a local cache directory and return the absolute path (for agent `Read` / vision); URL attachments return the URL without writing a file

No create/update/delete/upload tools. Local filesystem writes are limited to the attachment cache.

## Install

```bash
pip install -e ".[dev]"
pytest
```

## Cursor MCP config

Add to `%USERPROFILE%\.cursor\mcp.json` (fill in org URL, username + RSS token):

```json
{
  "mcpServers": {
    "spira": {
      "command": "C:\\Program Files\\Python311\\python.exe",
      "args": ["-m", "spira_mcp"],
      "env": {
        "INFLECTRA_SPIRA_BASE_URL": "https://<OrgID>.spiraservice.net",
        "INFLECTRA_SPIRA_USERNAME": "YOUR_LOGIN",
        "INFLECTRA_SPIRA_API_KEY": "{YOUR-RSS-TOKEN}",
        "SPIRA_COMMENT_LIMIT": "5",
        "SPIRA_MAX_INCIDENTS": "50",
        "SPIRA_ATTACHMENT_MAX_BYTES": "5242880",
        "SPIRA_ATTACHMENT_ALLOW_LARGE_FS": "false"
      }
    }
  }
}
```

Optional:

- `"SPIRA_PRODUCT_ID": "123"` (numeric only) or `"SPIRA_PRODUCT_NAME": "My Product"` for a default product
- `"SPIRA_ATTACHMENT_CACHE_DIR": "D:\\spira-cache"` — override cache root (default: `{cwd}/.spira-attachments`, gitignored)
- `"SPIRA_ATTACHMENT_MAX_BYTES": "5242880"` — soft metadata gate and hard stream ceiling (default **5 MiB**)
- `"SPIRA_ATTACHMENT_ALLOW_LARGE_FS": "true"` — allow writing attachments larger than the soft cap (disables the hard stream ceiling)

Restart Cursor MCP (or reload) after saving.

## Example prompts

- “Run an incident digest for status Open, owner me, detected release 25.7”
- “Digest incident IDs 1201, 1205 for our default product”
- “Show filter options for the default Spira product”
- “List attachments on incident 1201, then download attachment 88 and summarize the screenshot”

## Design

See `docs/superpowers/specs/2026-07-28-incident-daily-digest-design.md`.