SkeletIQ

@skeletiq/mcp

在 SkeletIQ 中设计，使用你的编码 Agent 构建。

SkeletIQ 会将提示词转化为经过评审的系统架构——包括组件、数据存储、连接、决策和待解决问题——你可以在画布上完善它，然后发布。此 MCP 服务会将发布的架构交给任何兼容 MCP 的编码 Agent：它会根据写入仓库 AGENTS.md 的简报确定方向，按确定的顺序构建，并向你报告构建结果。

安装

无需安装——该服务通过 npx 运行。

你需要一个个人 API 令牌：在 SkeletIQ 中前往 Settings → Agent access，创建一个令牌并复制（令牌仅显示一次）。

Claude Code

claude mcp add skeletiq \
  --env SKELETIQ_API_KEY=skq_your_token_here \
  -- npx -y @skeletiq/mcp

opencode

{
  "mcp": {
    "skeletiq": {
      "type": "local",
      "command": ["npx", "-y", "@skeletiq/mcp"],
      "environment": { "SKELETIQ_API_KEY": "{env:SKELETIQ_API_KEY}" },
      "timeout": 600000
    }
  }
}

timeout 很重要。生成通常需要约 217 秒，最长可达 450 秒；opencode 的默认值远低于此值，会终止运行正常的任务。

其他主机

在环境变量中设置 SKELETIQ_API_KEY，通过 stdio 运行 npx -y @skeletiq/mcp。

配置

变量	必需	默认值	说明
SKELETIQ_API_KEY	是	—	以 skq_ 开头的个人 API 令牌。不是浏览器会话令牌。
SKELETIQ_API_URL	否	https://api.skeletiq.com	用于可自托管的安装。末尾的 /api/v1 可接受并会被移除。

权限范围

令牌仅授予你勾选的权限。该服务的工具需要：

权限范围	可执行的操作	工具
read	查看项目、设计、简报、构建顺序、就绪状态、缺漏和任务	list_projects、get_design、get_generation_status
generate	运行生成——这会消耗额度——以及评审数据（免费）	generate_architecture、critique_architecture
report	记录已构建的内容，以及请求他人更改决策。还需要 read	check_drift、request_decision_change

read 是很好的起点：Agent 可以确定方向并构建，但不能消耗任何额度。

上表无法在单元格中说明两件事：

• 单独授予 report 不起作用。 check_drift 和 request_decision_change 必须先查找项目和版本，才能提交报告；而这些查找需要 read。仅有 report 权限的令牌会被拒绝。
• 没有 read 的 generate 仍然可以生成，但返回的内容会更精简：工具会读取刚创建的设计来描述它，如果读取失败，会返回内容较精简的答案，而不是将生成标记为失败——如果告诉 Agent 生成失败，它可能会再次付费重做整个任务。

无论令牌拥有哪些权限，其他操作都无法执行——令牌不能创建其他令牌、读取或更改你的服务提供商密钥、查看账单或删除你的账户。

工具

工具	功能
list_projects	按名称查找项目。返回候选项目，而不是自行猜测。
get_design	以九种模式之一读取设计：overview、component、brief、todo、readiness、build_order、gaps、fitness、decisions。readiness 会以结论优先的标题开头（“满足 22 项，共 24 项 · 已就绪 · 得分 87”）。fitness 会列出需要在你自己的仓库中编写并通过 check_drift 报告的测试；decisions 会列出该版本的决策，包括选择了什么、原因以及否决了什么。如果某个版本记录了需求，overview 和 component 会将设计中的 R-id 解析为其对应的需求，并说明每项需求的结果。
generate_architecture	根据提示词设计系统。会消耗点数并需要几分钟。如果提示词未说明负载，会返回问题而不收费：请询问用户；如果用户不知道，就回答“暂时不确定”，而不是自行猜测。
get_generation_status	轮询通过 wait: false 启动的生成任务。
critique_architecture	根据 SkeletIQ 的规则检查设计。结果确定、免费，且不会存储任何内容。请告知它 domain 和 exposure。
check_drift	报告已构建的内容；了解缺失、只完成一半或未包含在设计中的内容。
request_decision_change	请求他人更改设计决策，或轮询已提交的请求。项目中的人员会在待办事项中审核；只有接受后才会发生更改。

会话流程

1. list_projects → 解析用户提到的项目。
2. get_design(mode: "brief") → 将围栏代码块写入 AGENTS.md。
3. get_design(mode: "readiness") → 查看仍未决定的事项并提出问题。
4. get_design(mode: "build_order") → 按该顺序构建。
5. get_design(mode: "component", component_id: …) → 开始处理每个部分时读取它。
6. check_drift(covers: [...]) → 报告进度。

需要了解的四件事

简报是受管理的代码块。 它位于 AGENTS.md 中的 skeletiq:brief HTML 注释围栏内。刷新时会替换整个代码块。切勿追加第二个代码块，也切勿编辑代码块内部：你的修改会在下次刷新时悄无声息地消失。

草稿不是发布版本。 未发布的版本会随着每次画布保存而更改，但不会通知你的代码仓库它已更新。这些工具会标记草稿，并告知你何时有更新的发布版本。

组件 ID 仅属于一个版本。 重新生成会创建新的 ID。当 check_drift 返回带有建议的未知 ID 时，这些只是建议——请交由他人处理，不要自行认定映射关系。

critique_architecture 的可选输入并非中性。 省略某项并不代表跳过相应问题，而是为该问题作答。未提供 domain 时，不会应用任何合规框架（secondary_domains 不会选择任何框架——它们只会作为建议，添加该领域的设计检查，因此必须应用某个框架时，请明确指定），所以不会产生合规检查结果，返回的得分也会高于 SkeletIQ 应用对同一设计显示的得分，最高相差 15 分。未提供 exposure 时，设计会按面向互联网的情况评估，因此气隙系统可能会被要求添加 CDN 和 WAF。响应会说明实际使用的设置——frameworks_checked 和 exposure_assessed；文本输出也会在应用默认值时发出警告。向他人报告得分之前，请先查看这些信息。

生成使用哪个模型

使用账户持有人在 Settings → Agent access 中选择的模型。工具有意不接受运行时参数：请求设计的模型不能决定你要为此付出多少成本。

开发

本仓库是已发布的 @skeletiq/mcp 包的源代码。该连接器在 SkeletIQ 的 monorepo 中开发，与它所连接的 API 同处一个仓库，并镜像到这里——因此，你看到的历史记录就是该包的真实历史，而不是压缩后的快照。在这里提交的拉取请求无法合并，因为下一次同步会覆盖它；CONTRIBUTING.md 说明了应该如何操作。

Node 20 或更高版本。

npm install
npm test          # vitest — hermetic: no network, no services, nothing to seed
npm run build     # tsup, to dist/index.js
npm run typecheck
npm run lint

测试会模拟 SkeletIQ API，而不是实际调用它，因此，干净克隆后无需令牌和账户即可运行测试。

**如果 npm install 因 Cannot read properties of null (reading 'edgesOut') 而失败，**说明你使用的是 npm 10.9.x——Node 22 附带的版本——它无法解析此依赖树；仅 vitest@4 就会触发此问题。运行 npm install -g npm@11 即可修复。此问题只影响克隆和构建：使用 npx 安装已发布的包不受影响。

许可证

MIT——详见 LICENSE。源代码： Sabhahith-Works/skeletiq-mcp——问题和疑问请前往 此处。

SkeletIQ 平台采用 AGPL-3.0-or-later 许可证；此连接器采用 MIT 许可证，因此可以自由嵌入、打包进其他项目并分叉。

“SkeletIQ”是 Sabhahith Works Private Limited 的商标——详见 NOTICE。安全问题请发送至 [email protected]，不要提交到问题跟踪器：SECURITY.md。