Swarmia MCP

Swarmia Docs MCP

Swarmia的活动文档–直接在IDE中

静态知识库已死开发人员工具变得越来越复杂，传统的知识库无法解决这个问题。 今天， 当开发人员面临与Swarmia等平台的集成或故障排除问题时，他们被迫中断工作流程，切换到web浏览器，点击文档。这种传统的“拉式”支持模式完全依赖于开发人员找到指令并将其转换为特定的本地环境。它是 缓慢、低效，并强调了对与工具相融合的文档的需求。

这个项目 引入了一种由自定义MCP服务器支持的独特技能。您可以转换档位：从静态文档到交互式工作流。 调用 /swarmia 直接在IDE中。MCP服务器主动评估您的本地环境——git历史记录、分支名称、CI/CD配置——并提供可操作的解决方案：

• 检查承诺卫生 –验证分支和提交是否包含问题跟踪器ID，根据线性API进行验证
• 脚手架部署跟踪 –检测您的CI/CD框架并生成Swarmia webhook配置
• 回答Swarmia的问题 –根据上下文查询捆绑文档，无需浏览器

场景1：

|我不确定该怎么办。 /swarmia 向我展示了要修复的内容：|它有效。 （常规UI）|它有效。 （丰富的UI）|我的Linear API键可以吗？

场景2：

|我刚加入这个团队。 我的本地设置准备好了吗？ （标准UI）|我刚刚加入团队。 我的本地设置准备好了吗？ （丰富的用户界面）| /swarmia 查看我最近的5次提交 合规

用法

待办事项：按IDE排序，目前仅VS代码。

1.先决条件

# 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.将MCP服务器添加到您的项目中

添加 .vscode/mcp.json 到你的项目。它告诉VS Code如何启动MCP服务器。

选项A：从GitHub安装（推荐用于您的项目）：

{
  "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 直接从GitHub获取包，在隔离的环境中构建它，并运行 swarmia-mcp 入口点。无需克隆，只需提交即可 mcp.json 到您的仓库，每个开发人员都会自动获得服务器。

选项B：本地开发（本回购）：

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

当你调用 /swarmia 在聊天中，VS Code将服务器作为子进程生成，并通过stdio连接到它。无需手动启动服务器—— uv 解析依赖关系，并在首次运行时创建一个隔离的环境。

3.IDE技能

两种技能将你的意图引导到正确的工具上：

这 /swarmia 和 /swarmia-admin 技能不会自动安装 使用MCP服务器。复制 .github/skills/swarmia/ 和 .github/skills/swarmia-admin/ 从该存储库到项目的目录 .github/skills/ 文件夹。如果没有这些技能，MCP工具仍然可以工作，但你的LLM将没有使 /swarmia 调用工作。

4.使用 /swarmia 在聊天

类型 /swarmia 然后是您的问题或请求。LLM将您的意图引导到正确的工具。

手动测试（可选）

要在VS Code之外进行调试或测试，请直接运行服务器：

uv run python -m swarmia_mcp

或者使用MCP Inspector以交互方式调用工具：

npx @modelcontextprotocol/inspector uv run python -m swarmia_mcp

交互示例

检查您的分行是否会被Swarmia跟踪：

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

代理检查您的本地git–通知 fix-bug 缺少a ENG- 前缀–回复： *“您的分支缺少线性ID。我可以将其重命名为吗 ENG-XXX-fix-bug?"*

审核最近提交的问题密钥：

/swarmia Check my last 5 commits for Swarmia compliance

客服电话 check_swarmia_commit_hygiene –扫描提交消息 ENG-\d+ 模式——标记任何缺失的问题密钥，并通过交互式重基帮助修复它们。

设置DORA指标/部署跟踪：

/swarmia-admin Set up deployment tracking for this repository

客服电话 scaffold_swarmia_deployment –检测GitHub操作（或GitLab CI、Jenkins）–生成确切的webhook YAML并解释要添加哪些秘密。

在不离开IDE的情况下提出Swarmia问题：

/swarmia How does Swarmia calculate Cycle Time?

代理查询捆绑的文档，并返回基于Swarmia官方帮助中心内容的简洁答案（最多3句话）。

检查为什么工作没有显示在投资余额中：

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

代理链工具：检查您的git历史记录中是否缺少问题密钥，然后解释Swarmia需要PR问题链接将工作分类到投资类别中。

______________________________________________________________________

视频

包括屏幕截图

详情

建筑

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

运输： stdio（本地）。服务器作为IDE的子进程运行。

MCP应用程序： 每个工具都声明一个 ui:// 通过FastMCP的资源 AppConfig主机（VS Code）通过以下方式获取HTML resources/read 并在聊天窗口内呈现：带有内联React包的widgetized HTML直接通过MCP协议提供。

分布： 使用 uvx --from git+https://github.com/V-You/Swarmia_MCP swarmia-mcp 从GitHub安装而无需克隆。使用 uv run python -m swarmia_mcp 为了地方发展。

工具

check_swarmia_commit_hygiene

阅读本地 git log 和 git branch，正则表达式扫描问题跟踪器ID（例如。 ENG-123)，并可选择根据Linear GraphQL API验证每个问题。为交互式小部件返回包含文本和数据的结构化JSON。

• 随着 LINEAR_API_KEY：完全验证-问题标题、状态、分配
• 没有 LINEAR_API_KEY：回退到仅匹配注释以添加密钥的正则表达式
• 小装置： 带有进度条和线性验证状态的交互式提交表

scaffold_swarmia_deployment

通过扫描工作区检测CI/CD框架（GitHub Actions、GitLab CI、Jenkins），然后为Swarmia的部署API生成webhook配置(POST https://hook.swarmia.com/deployments).

• 纯生成-以文本形式返回YAML/config，不写入文件系统
• IDE的本机文件编辑工具处理应用diff
• 小装置： 使用CI提供者徽章、YAML代码段和设置步骤进行配置预览

query_swarmia_docs

读取捆绑的 docs_context.md （由Swarmia帮助中心策划）并将其返回给法学硕士，以提取简洁的答案。还运行本地集成诊断。

• 涵盖：入门、部署跟踪、DORA指标、周期时间、投资平衡、公关问题链接、工作协议
• 小装置： 交通灯仪表板：GitHub、Linear、Slack、部署跟踪集成状态

环境变量

项目结构

├── 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

______________________________________________________________________

故障排除

未找到紫外线

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

原因1:路径不匹配。

• 解决方案1：调整 command mcp.json中的值（到uv的路径）。
• 解决方案2：调整或添加 env.PATH 在mcp.json中。

重复输出

像“Check my last 5 commits”这样的提示可能会显示一些结果两次：一次在MCP Apps小部件（富UI）中，另一次由代理呈现。这主要是因为MCP Apps是一个相对较新的功能，避免这种重复的策略尚未正式确定。此处实施的缓解措施：工具返回建议（小部件显示X，关注Y）和技能包含注释以避免重复。更好的解决方案：明确划分关注点，小部件只显示数据，LLM只做分析/建议。事实上， *代码模式* 优雅地解决了这个问题，请参见 md/code-mode_scoping.md，大重构，包括添加第二个远程MPC服务器和重写所有工具，值得一试。