A Model Context Protocol (MCP) server that provides access to Swarmia's Export API for fetching metrics and reports including pull request metrics, DORA metrics, investment balance reports, software capitalization reports, and effort reporting.
The Swarmia MCP server provides 6 tools for fetching metrics and reports from Swarmia's API. All tools have descriptions and complete input schemas with proper JSON Schema formatting. However, there are significant gaps in parameter-level documentation, output schema documentation, and error handling guidance. Tool naming is clear and verb-based (get_*), which is good. Parameter descriptions exist but lack specificity about format constraints, valid ranges, and what downstream tools need. No documentation of return structures means LLMs cannot reliably chain tools or extract needed fields for follow-up calls. Output schema documentation is entirely absent, critical for agents planning multi-step operations. Error handling relies on raw HTTP responses without recovery guidance.
Get DORA metrics including deployment frequency, change lead time, change failure rate, etc.
Get effort reporting for authors and their FTE for each issue
Get investment balance statistics using the Effort model (monthly FTE data)
Get pull request metrics for the organization including cycle time, review rate, merge time, etc.
Get list of employees with FTE effort breakdown by month
Get software capitalization report
No output schema documentation. Tools return data from external API, but LLMs cannot see what fields are returned, preventing reliable downstream chaining and field extraction. This is a critical pattern violation.
Parameter descriptions lack actionable format constraints. 'timezone' accepts arbitrary strings with only example 'America/New_York'; no enum, no validation pattern. 'start_date' and 'end_date' have 'format: date' but descriptions don't explain YYYY-MM-DD requirement or validation errors. LLMs cannot reliably construct valid requests.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 56 | <=2025-11-25 | v2 |
No error recovery guidance. Source code shows httpx calls but no visible try-catch or error message formatting. If API returns 401 (invalid token), 404 (no data), or 500 (server error), LLMs receive raw HTTP errors with no hints about what to do next (e.g., 'Check SWARMIA_API_TOKEN is valid and has correct scope').
Timeframe and date parameters are mutually exclusive (timeframe OR start_date/end_date) but this dependency is not documented in parameter descriptions. LLMs may pass both, causing ambiguous or failing calls.
No result pagination, limit, or filtering guidance. Tools return all data for a timeframe with no documented way to cap results, offset, or page through large datasets. If Swarmia returns 1000+ records, context window explodes and LLM reasoning degrades.