Swarmia Docs MCP

Active documentation for Swarmia – directly in your IDE

Static knowledge bases are dead. Developer tooling grows increasingly complex – and traditional knowledge bases are not cutting it. Today, when developers face integration or troubleshooting issues with platforms like Swarmia, they are forced to break their workflow, context-switch to a web browser, click through documentation. This traditional "pull" model of support relies entirely on the developer to find instructions and translate them into their specific local environment. It's slow, inefficient, and highlights the need for documentation that converges with tooling.

This project introduces a singular Skill, backed by a custom MCP Server. You shift gears: from static documentation to interactive workflow. Invoke /swarmia directly within your IDE. The MCP server actively assesses your local environment – git history, branch names, CI/CD configuration – and provides actionable solutions:

• Check commit hygiene – verify branches and commits contain issue tracker IDs, validate against Linear API
• Scaffold deployment tracking – detect your CI/CD framework and generate Swarmia webhook config
• Answer Swarmia questions – query bundled documentation contextually, no browser needed

Scenario 1:

I'm unsure what to do. /swarmia shows me what to fix:	It works. (regular UI)	It works. (rich UI)	Is my Linear API key ok? Let's check:

Scenario 2:

I just joined the team. Is my local setup ready? (standard UI)	I just joined the team. Is my local setup ready? (rich UI)	/swarmia Check my last 5 commits for compliance (rich UI)

Usage

TO DO: sort by IDE, currently VS Code only.

1. Prerequisites

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Optional: add a Linear API key for full issue validation
echo 'LINEAR_API_KEY=lin_api_yourkey' > .env

2. Add the MCP server to your project

Add .vscode/mcp.json to your project. It tells VS Code how to start the MCP server.

Option A: Install from GitHub (recommended for your project):

{
  "servers": {
    "swarmia": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/YOUR_ORG/Swarmia_MCP", "swarmia-mcp"],
      "env": {
        "PATH": "${env:HOME}/.local/bin:${env:PATH}"
      }
    }
  }
}

uvx fetches the package directly from GitHub, builds it in an isolated environment, and runs the swarmia-mcp entry point. No cloning required – just commit this mcp.json to your repo and every developer gets the server automatically.

Option B: Local development (of this repo):

{
  "servers": {
    "swarmia": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "swarmia_mcp"],
      "env": {
        "PATH": "${env:HOME}/.local/bin:${env:PATH}"
      }
    }
  }
}

When you invoke /swarmia in the chat, VS Code spawns the server as a child process and connects to it over stdio. No manual server startup needed – uv resolves dependencies and creates an isolated environment on first run.

3. IDE Skills

Two Skills route your intent to the right tools:

Skill	Persona	When to use
/swarmia	Developer pair programmer	Troubleshooting, checking branch/commit hygiene, general Swarmia questions
/swarmia-admin	Infrastructure engineer	Setting up deployment pipelines, configuring DORA metrics, initial integration

The /swarmia and /swarmia-admin Skills are not installed automatically with the MCP server. Copy the .github/skills/swarmia/ and .github/skills/swarmia-admin/ directories from this repository into your project's .github/skills/ folder. Without these Skills, the MCP tools still work – but your LLM won't have the persona and routing instructions that make /swarmia invocations work.

4. Use /swarmia in the chat

Type /swarmia followed by your question or request. The LLM routes your intent to the right tool.

Manual testing (optional)

For debugging or testing outside VS Code, run the server directly:

uv run python -m swarmia_mcp

Or use MCP Inspector to call tools interactively:

npx @modelcontextprotocol/inspector uv run python -m swarmia_mcp

Example interactions

Check if your branch will be tracked by Swarmia:

/swarmia Is my current branch going to be tracked properly?

Agent checks your local git – notices fix-bug lacks an ENG- prefix – replies: "Your branch is missing a Linear ID. Shall I rename it to ENG-XXX-fix-bug?"

Audit recent commits for issue keys:

/swarmia Check my last 5 commits for Swarmia compliance

Agent calls check_swarmia_commit_hygiene – scans commit messages for ENG-\d+ patterns – flags any missing issue keys and offers to help fix them via interactive rebase.

Set up DORA metrics / deployment tracking:

/swarmia-admin Set up deployment tracking for this repository

Agent calls scaffold_swarmia_deployment – detects GitHub Actions (or GitLab CI, Jenkins) – generates the exact webhook YAML and explains which secrets to add.

Ask a Swarmia question without leaving the IDE:

/swarmia How does Swarmia calculate Cycle Time?

 Agent queries bundled documentation and returns a concise answer (max 3 sentences) grounded in official Swarmia help center content.

Check why work isn't showing up in Investment Balance:

/swarmia Why isn't my current work showing up in the Investment Balance view?

 Agent chains tools: checks your git history for missing issue keys, then explains that Swarmia requires PR–issue linking to categorize work into investment categories.

---

Video

include screencast

Details

Architecture

IDE (VS Code)
  ├── /swarmia          (Skill - developer persona)
  ├── /swarmia-admin    (Skill - infra persona)
  └── LLM routes intent
        ↓
  swarmia_mcp/server.py (FastMCP, stdio transport)
    ├── check_swarmia_commit_hygiene  →  local git + Linear API  →  ui://commit-hygiene.html
    ├── scaffold_swarmia_deployment   →  filesystem scan + YAML   →  ui://deployment-scaffold.html
    └── query_swarmia_docs            →  bundled docs + diagnostics → ui://docs-diagnostic.html

Transport: stdio (local). Server runs as a child process of the IDE.

MCP Apps: Each tool declares a ui:// resource via FastMCP's AppConfig. The host (VS Code) fetches HTML via resources/read and renders it inside the Chat window: widgetized HTML with inlined React bundles is served directly over the MCP protocol.

Distribution: Use uvx --from git+https://github.com/V-You/Swarmia_MCP swarmia-mcp to install from GitHub without cloning. Use uv run python -m swarmia_mcp for local development.

Tools

check_swarmia_commit_hygiene

Reads local git log and git branch, regex-scans for issue tracker IDs (e.g. ENG-123), and optionally validates each issue against the Linear GraphQL API. Returns structured JSON with both text and data for the interactive widget.

• With LINEAR_API_KEY: Full validation – issue title, status, assignment
• Without LINEAR_API_KEY: Fallback to regex-only matching with a note to add the key
• Widget: Interactive commit table with progress bar and Linear verification status

scaffold_swarmia_deployment

Detects the CI/CD framework (GitHub Actions, GitLab CI, Jenkins) by scanning the workspace, then generates the webhook configuration for Swarmia's Deployment API (POST https://hook.swarmia.com/deployments).

• Pure generation – returns YAML/config as text, does not write to the filesystem
• The IDE's native file-edit tools handle applying the diff
• Widget: Config preview with CI provider badge, YAML snippet, and setup steps

query_swarmia_docs

Reads the bundled docs_context.md (curated from the Swarmia help center) and returns it for the LLM to extract a concise answer. Also runs local integration diagnostics.

• Covers: getting started, deployment tracking, DORA metrics, cycle time, investment balance, PR-issue linking, working agreements
• Widget: Traffic-light dashboard: GitHub, Linear, Slack, Deployment Tracking integration status

Environment Variables

Variable	Required	Purpose
LINEAR_API_KEY	No	Linear issue validation in commit hygiene checks
SWARMIA_DEPLOYMENTS_AUTHORIZATION	No	Referenced in generated CI/CD config snippets

Project Structure

├── swarmia_mcp/                        # Installable Python package
│   ├── __init__.py
│   ├── __main__.py                     # python -m swarmia_mcp entry point
│   ├── server.py                       # MCP server (3 tools + 3 ui:// resources)
│   └── docs_context.md                 # Bundled Swarmia documentation
├── src/                                # Widget source (React + TypeScript)
│   ├── commit-hygiene/                 # Commit hygiene dashboard
│   ├── deployment-scaffold/            # CI config wizard
│   └── docs-diagnostic/                # Integration status dashboard
├── assets/                             # Built widgets (tracked for distribution)
│   ├── commit-hygiene/index.html       # Self-contained HTML + inlined JS
│   ├── deployment-scaffold/index.html
│   └── docs-diagnostic/index.html
├── package.json                        # Node.js build deps (Vite, React, TypeScript)
├── vite.config.mts                     # Per-widget build config (self-contained bundles)
├── tsconfig.json
├── pyproject.toml                      # Python build system, dependencies & entry points
├── .env                                # API keys (gitignored)
├── .vscode/
│   └── mcp.json                        # MCP server config (VS Code auto-starts)
├── .github/
│   ├── copilot_instructions.md         # Developer instructions for this repo
│   └── skills/
│       ├── swarmia/SKILL.md            # /swarmia skill definition (copy to your project)
│       └── swarmia-admin/SKILL.md      # /swarmia-admin skill definition (copy to your project)
└── README.md

---

Troubleshooting

uv not found

2026-02-23 12:18:17.011 [info] Connection state: Error spawn uv ENOENT

Cause 1: PATH mismatch.

• Solution 1: Adapt the command value in mcp.json (path to uv).
• Solution 2: Adapt or add env.PATH in mcp.json.

Duplicate output

A prompt like "Check my last 5 commits" may show some results twice: once in the MCP Apps widget (rich UI), and a second time rendered by the agent. This happens mostly because MCP Apps is a relatively new feature and strategies to avoid this duplication are not formalized. Mitigation implemented here: Tools return advise (widget shows X, focus on Y) and Skills contain note to avoid duplication. Better solution: Explicitly split concerns, widgets only show data and LLMs only do analysis/advise. Actually, Code Mode solves this elegantly, see md/code-mode_scoping.md, big refactor including adding a second remote MPC server and rewriting all tools, worth it.