specshield-mcp-server

Name: specshield-mcp-server
Author: specshield26

本地服务

github.com/specshield26开发工具011 周前更新

代码仓库

关于 specshield-mcp-server

specshield-mcp-server 让 AI 编码 Agent 在部署前评估 API 规范变更，提供只读分析工具，涵盖发布安全判断、变更说明和迁移材料。

主要功能

01评估 API 变更是否适合发布
02比较 API 规范并评估风险
03说明破坏性变更及其影响
04生成迁移指南和发布说明
05检查 API 治理规则

适用场景

01合并或部署前检查 OpenAPI 变更
02说明规范变更对使用方的影响
03准备迁移步骤和发布说明
04检查规范中的治理问题

MCP 相关

向 MCP 客户端提供 SpecShield 分析工具，可接收内联规范或明确指定路径的文件。工具只做分析，不修改代码；治理审查需 Team+ 付费计划。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "specshield26-specshield": {
      "command": "npx",
      "args": [
        "-y",
        "specshield-mcp-server"
      ],
      "env": {
        "SPECSHIELD_API_KEY": "<SPECSHIELD_API_KEY>",
        "SPECSHIELD_API_URL": "<SPECSHIELD_API_URL>",
        "SPECSHIELD_TIMEOUT_MS": "<SPECSHIELD_TIMEOUT_MS>",
        "SPECSHIELD_LOG_LEVEL": "<SPECSHIELD_LOG_LEVEL>"
      }
    }
  }
}

启动命令npx -y specshield-mcp-server

需要配置的环境变量

SPECSHIELD_API_KEY密钥SpecShield API key

SPECSHIELD_API_URLBackend base URL

SPECSHIELD_TIMEOUT_MSPer-request timeout (ms)

SPECSHIELD_LOG_LEVELdebug|info|warn|error

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmspecshield-mcp-server1.0.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

SpecShield MCP 服务

面向 AI 编码 Agent 的 API 变更部署门禁。 直接在 Claude、Cursor 和其他 MCP 客户端中询问 “将此 API 变更发布给我的使用者安全吗？”，并在破坏性变更影响使用者之前将其发现。

这是对 SpecShield 后端的轻量封装。所有工具都仅支持只读／分析，不会修改你的代码。

为什么不直接对比规格？许多工具（包括免费的工具）都会列出破坏性变更。SpecShield 的职责是做出判断：我可以部署吗？——部署门禁才是这里的核心工具。

⚙️ 在 CI/CD 中使用，而不是在 Agent 中使用？ specshield CLI 可在你的流水线中运行相同的破坏性变更和 can-i-deploy 检查（GitHub Action、退出代码）。功能相同，入口各异：此服务供 AI Agent 使用，CLI 供 CI/CD 使用。

工具

#	工具	可回答的问题
1	`is_change_safe` ⭐	此变更适合合并／部署吗？会影响使用者吗？（`safeToMerge` + 风险 + 阻止原因）
2	`explain_breaking_changes`	哪些内容会受影响、对开发者和使用者的影响，以及建议的迁移方案
3	`generate_migration_guide`	迁移指南（markdown）+ 安全的逐步发布步骤
4	`generate_release_notes`	面向开发者／客户／内部人员的发行说明
5	`compare_specs`	原始差异（破坏性变更／新增／修改／警告）+ 风险评分
6	`run_governance_review` 🔒	超出破坏性变更范围的 API 治理规则集检查（缺少 operationId、错误响应、安全方案、分页、版本控制……）→ 定位问题并建议修复。付费（Team+）

工具 1–5 支持内联传入规格（baseSpecContent / targetSpecContent），或通过路径传入（baseSpecPath / targetSpecPath）。run_governance_review 会检查单个规格（specContent / specPath）。

🔒 run_governance_review 是付费功能——使用 FREE API 密钥会返回 payment_required 错误。请前往 specshield.io/pricing 升级。

完整的设置、验证和故障排查说明：docs/mcp-server-setup.md。

安装

需要 Node.js ≥ 20 和 SpecShield API 密钥（可从 specshield.io/account 获取）。

npx -y specshield-mcp-server

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "specshield": {
      "command": "npx",
      "args": ["-y", "specshield-mcp-server"],
      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
    }
  }
}

Claude Code

claude mcp add specshield --env SPECSHIELD_API_KEY=ss_your_key_here -- npx -y specshield-mcp-server

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "specshield": {
      "command": "npx",
      "args": ["-y", "specshield-mcp-server"],
      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
    }
  }
}

配置

环境变量	必需	默认值	用途
`SPECSHIELD_API_KEY`	是	—	你的 SpecShield API 密钥。请将其存储为机密；切勿提交。
`SPECSHIELD_API_URL`	否	`https://api.specshield.io`	后端基础 URL（可覆盖为可自托管／暂存环境）。
`SPECSHIELD_TIMEOUT_MS`	否	`30000`	单次请求的超时时间。
`SPECSHIELD_LOG_LEVEL`	否	`info`	`debug` \| `info` \| `warn` \| `error`（日志输出到 stderr）。

示例提示词（以部署门禁为先）

“这是我的旧版和新版 openapi.yaml——将此 API 变更发布给我的使用者安全吗？”
“比较 v1.yaml 和 v2.yaml，告诉我能否部署，以及原因。”
“说明这两个规格之间的破坏性变更，以及使用者应如何迁移。”
“为此 API 变更生成面向客户的发行说明。”

安全与隐私

需要 API 密钥。 密钥仅通过 X-Api-Key 标头发送到你配置的后端。
仅支持只读／分析。 没有修改类工具、没有 Shell 执行，也不会任意访问文件（只有在你明确传入路径时才会读取规格文件）。
不记录机密或规格内容。 服务绝不会记录规格内容、API 密钥或请求正文；错误消息经过脱敏处理且可供机器读取。
规格会发送到你配置的 SpecShield 后端进行分析。

本地开发

npm install
npm run build      # tsc → dist/
npm test           # vitest (no network)
npm run lint
npm run smoke      # boots the server against a stubbed backend and lists tools
npm start          # run the built server over stdio