Agentic SDLC MCP

agentic-sdlc-mcp

为在真实 GitHub 仓库中工作的 AI 编码 Agent 提供治理与证据控制。

让 Claude Code、Cursor 和其他 Model Context Protocol (MCP) 客户端使用仓库上下文、审查关卡、安全证据和人工审批节点。

中文 · npm · MCP Registry · 路线图

agentic-sdlc-mcp 是一层软件开发生命周期（SDLC）治理层，面向已经允许 AI 编码 Agent 修改生产仓库的团队。它将 GitHub 上下文、策略、检查、审查、安全警报和发布信号转化为 13 个工作流级 MCP 工具。其中 12 个工具为只读。唯一可写入 GitHub 的工具默认会预览变更。

1.11.0 版本还提供了 agentic-sdlc，这是一个只读 CLI，可用于 PR 评估、可移植证据、快照对比和验收可追溯性。agentic-sdlc-mcp 仍是 MCP 服务入口。安装此版本时，请核实确切的软件包和发布元数据。

此 MCP 带来的变化

AI 编码 Agent 可以创建代码和拉取请求，却未必了解仓库的每一条规则。此服务为 Agent 提供范围明确的上下文，并向审查者明确指出证据缺口，而不是再生成一份不受约束的摘要。

此服务不会编写代码、合并拉取请求、强制推送、创建发布、部署软件，也不会取代人工安全审查。

它如何融入生产环境中的 Agent 工作流

MCP 位于 AI 编码 Agent 与 GitHub 证据之间。代码库变更仍通过 Agent 的常规开发环境完成，高影响决策仍由你的团队做出。

flowchart LR
    Policy["Engineering policy<br>and repository rules"] --> MCP["agentic-sdlc-mcp"]
    Agent["AI coding agent<br>Claude Code · Cursor · MCP client"] --> MCP
    MCP --> GitHub["GitHub API evidence"]
    GitHub --> MCP
    MCP --> Reports["Briefs · plans · gates<br>reviews · release reports"]
    Reports --> Agent
    Reports --> Human["Human review and approval"]
    Agent -. "Code · commits · pull requests" .-> GitHub
    Human -. "Merge · release · deploy" .-> GitHub

适用场景

在自主 Agent 原本会猜测或依赖过时文字说明的环节，使用这些工具辅助决策。

不使用 Agent 审查 PR

通过一条命令收集人类可读的决策和 JSON 快照。评估会结合现有门禁和基于规则的审查证据，并将其绑定到 PR 的 head/base 和策略摘要，同时保留阻塞项、缺失证据、请求次数和收集时长。

使用 Node.js 22 或更高版本，从已审查的检出版本构建：

npm ci
npm run build
node dist/cli.js doctor --repo acme/widget
node dist/cli.js assess-pr --repo acme/widget --pr 42 --output artifacts/pr-42-first.json --summary artifacts/pr-42-first.md

在线收集前，通过进程或密钥管理器注入 GITHUB_TOKEN。CLI 只读取环境变量；不会加载 home 配置或 .env。除非指定 --online，否则 doctor 会离线运行；缺少配置时返回退出代码 2。安装软件包后，agentic-sdlc 会运行与 node dist/cli.js 相同的 CLI。

assess-pr 和 evidence 也支持 --previous、--acceptance，以及可选的 --mappings，用于一次收集并进行本地分析。映射文件使用证据连续性中描述的严格数组架构。--json 会改变标准输出；--output 始终会创建 JSON 文件。绝不会覆盖现有文件。--summary 会创建新的 Markdown 文件；若其路径与 GitHub Actions 的确切 GITHUB_STEP_SUMMARY 路径相同，则会追加内容。

默认情况下，评估仅供参考：即使决策为阻塞或需要证据，报告完成后也会返回 0。assess-pr --enforce 在结果为 blocked 时返回 1，为 needs_evidence 时返回 2，为 ready_for_review 时返回 0。配置／输入／来源不可用错误返回 2；取消操作返回 130。diff 或 trace 命令成功表示分析已完成，并不表示证据或验收条件已通过。

在线收集的默认超时为 30 秒，请求预算为 120 次；支持的覆盖范围是 --timeout-ms 1 至 120000，以及 --max-requests 2 至 500。doctor 有自己的有界探测，并接受超时选项。文件输入和序列化输出的大小上限为 1 MiB。

未变化的快照绝不会继承先前的验证结果。head/base、策略、生成方版本、新鲜度和完整性的变化都可能需要重新收集。已勾选的方框、Agent 声明和普通的绿色 CI 均不能证明业务验收；默认情况下，CLI 未配置可信的验收生成方。报告显示就绪或使用 --enforce，都不会批准、合并或部署 PR。

对于 MCP 审查会话，设置 SDLC_CONFIG_MODE=envonly 以避免加载 home/.env 配置，并设置 SDLC_READ_ONLY=true 以拒绝实时创建 Issue，同时保留预览功能。使用仅限目标仓库且具有读取权限的令牌。客户端配置和可移植的审查技能见客户端配置示例；尚未执行的小样本验证计划见用户试点。

从 npm 安装

需要 Node.js 22 或更高版本。GitHub Actions 中已测试 Node 22 和 24。直接从 npm 运行已发布的包：

npx -y agentic-sdlc-mcp

全局安装 CLI：

npm install -g agentic-sdlc-mcp
agentic-sdlc-mcp

默认传输方式是 stdio。大多数 MCP 客户端应由自身启动该包，而不是在单独的终端中运行。

这些 npm 命令会解析已发布的版本。固定到 [email protected] 以复现此版本，验证其发布/包元数据，并在升级后重启任何现有的 MCP 连接。

让编码 Agent 完成设置

将此提示词粘贴到 Codex、Claude Code 或其他编码 Agent 中：

Use npm install -g agentic-sdlc-mcp to install and configure this MCP globally. Repository: https://github.com/SakuraCianna/agentic-sdlc-mcp
Configure GITHUB_TOKEN and optional repository defaults through the MCP client's secret or environment configuration. On a trusted single-user machine, you may instead run agentic-sdlc-mcp configure or write them to ~/.agentic-sdlc-mcp.json. Never expose the token in chat, logs, or repository files; ask me for missing non-secret details.
Then verify the connection with the read-only repo_context tool and summarize its capabilities, required GitHub permissions, and safety boundaries.

批准之前，请检查每条命令和每项配置更改。需要 Node.js 22 或更高版本。

连接 MCP 客户端

将此服务添加到 Claude Desktop、Cursor、Windsurf 或其他 MCP 客户端。通过客户端的密钥或环境配置注入 GitHub 令牌。

{
  "mcpServers": {
    "agentic-sdlc": {
      "command": "npx",
      "args": ["-y", "agentic-sdlc-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_OWNER": "your_organization",
        "GITHUB_REPO": "your_repository"
      }
    }
  }
}

某些 Windows MCP 客户端需要通过 cmd 调用 npx：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "agentic-sdlc-mcp"]
}

GITHUB_OWNER 和 GITHUB_REPO 是可选的默认值。工具调用可以显式提供仓库坐标。请参阅 GitHub 权限矩阵，仅授予你启用的功能所需的权限。

npx -y agentic-sdlc-mcp configure

验证连接

先进行只读调用，以便在授予写入权限前检查仓库边界：

Use agentic-sdlc-mcp to run repo_context for the configured repository. Include package scripts, workflows, governance, and repository policy. Do not create issues or modify GitHub.

然后验证写入边界，但不创建任何内容：

Generate a feature plan and pass its issue drafts to create_issue_set with dryRun: true. Show the target repository, titles, labels, body summaries, and warnings. Do not write to GitHub.

请参阅与客户端无关的冒烟测试，了解五分钟验证流程。

工具

该服务注册了 13 个工作流级工具。MCP 客户端会在运行时获取完整的输入和输出架构；本目录说明了各工具的适用场景以及如何解读其结果。

该服务还公开了五个只读的 sdlc:// 资源，分别用于 SDLC 标准，以及 Issue、PR 摘要、发布就绪情况和交接模板。

常见工作流

这些序列可减少工具选择的歧义。每个序列都以人工决策结束。

Start work
repo_context → plan_from_context → create_issue_set (dryRun: true)
→ human confirms the work items → create_issue_set (dryRun: false)
→ prepare_work_item

Review a pull request
create_pr_summary → quality_gate_status → review_pr_against_standard
→ human reviews findings and decides whether to merge

Review governance
branch_protection_status → workflow_permissions_audit → security_triage
→ repository owners decide which settings or workflows to change

Prepare a release
security_triage → release_readiness_check → sdlc_evidence_packet
→ human approves the tag, release, and deployment

Transfer work
relevant evidence tools → sdlc_evidence_packet → agent_handoff_packet
→ the next agent validates stale or caller-asserted state before continuing

GitHub 权限

默认情况下不要授予所有权限。请选择团队启用的工具所需的权限，并先在非生产仓库中进行测试。

GitHub 权限和端点要求可能会发生变化。请根据 GitHub REST API 权限文档确认失败原因。缺少可选权限可能导致证据降级或未经验证；这并非授予无关访问权限的理由。

安全与信任边界

服务会限制自身的工具，但无法控制周边 AI Agent 或 MCP 客户端可执行的所有操作。

• 仅有一个优先预览的写入工具：create_issue_set 是唯一的 GitHub 写入工具，默认设置为 dryRun: true
• 不提供特权仓库变更操作：不提供合并、批准、强制推送、删除分支、修改分支规则、创建发布或部署工具
• 人工把关仍由外部负责：服务会报告 CODEOWNERS、审查、策略、CI、安全和发布证据；最终决策由 GitHub 和你的团队执行
• 证据会保留限定说明：缺失、过时、截断、格式错误或权限受限的来源仍会作为差距显示
• 仓库策略绑定基准版本：如有可用的基准 SHA，PR 策略将从该版本读取，避免拉取请求暗中放宽自身的门槛
• 外部文本不可信：仓库和调用方文本会受到长度限制并进行转义；检测到指令覆盖、秘密/数据外泄、编码命令或工具胁迫模式时，这些内容会从面向 Agent 的 Markdown 中省略，但仍可检查原始结构化证据
• 秘密检测能力有限：可信的扫描器来源信息和补丁启发式规则可以降低风险，但跨文件或运行时数据流仍需借助 CodeQL 或其他静态应用安全测试（SAST）、秘密扫描器、测试和人工审查
• 凭据由你负责：优先通过客户端注入秘密或使用环境变量；切勿提交令牌，或将其粘贴到 Issue、PR 或日志内容中
• 仅限本地的传输边界：stdio 和环回 HTTP 适用于可信的本地工作站。远程 OAuth 和多租户托管目前不在产品路线图中

请参阅仓库策略，了解 .agentic-sdlc.yml 架构、来源信息、限制以及基准 SHA 自我修改行为。请参阅测试策略，了解对抗性测试矩阵和覆盖规则。

仓库策略与资源

当仓库专属检查需要影响计划、受保护路径、PR 门槛、审查者、阻塞标签、变更日志要求和回滚要求时，请添加 .agentic-sdlc.yml。策略输出包括其来源引用、Blob SHA、摘要、稳定的规则 ID 和警告。

静态资源可通过 sdlc:// 方案访问：

本地 HTTP 配置

Stdio 是默认且推荐的本地传输方式。本地的两个条目都使用官方 SDK v2 时代的路由器：2025 客户端通过 initialize 继续工作，而明确协商 2026-07-28 的客户端使用 server/discover。两个时代都提供相同的 13 个工具和 5 个资源。

需要 Streamable HTTP 的本地客户端可在从源代码构建后选择启用：

$env:TRANSPORT = "http"
$env:PORT = "3000"
node dist/index.js

端点为 http://127.0.0.1:3000/mcp。它仅绑定到 loopback，会在解析有大小限制的请求正文之前验证 Host 和提供的 Origin；为每个 POST 创建相互隔离的无状态服务和传输；拒绝不受支持的 GET/DELETE 会话操作；限制错误详情的大小；并在关闭时中止正在进行的交互。

2025 无状态 HTTP 配置没有会话或客户端身份，因此无法将单独发送的 notifications/cancelled POST 与较早的请求相关联。客户端仍会观察到本地取消，但原始服务端操作可能会自然运行至完成。两个 stdio 时代以及 2026 HTTP 都会将取消传递给服务端请求。需要服务端取消旧版调用时，优先使用 stdio。

请勿向其他机器公开或反向代理此端点。当前不计划支持远程 OAuth 和多租户托管。如果重新考虑此范围，项目必须先满足单独的远程部署重新评估标准；当前的本地服务并非安全的远程部署基础。

开发与项目链接

仅在想要贡献或检查实现时克隆仓库：

git clone https://github.com/SakuraCianna/agentic-sdlc-mcp.git
Set-Location agentic-sdlc-mcp
npm install
npm run build
npm run test

集成门禁会在两个时代通过真实 SDK Client.callTool 调用全部 13 个公开工具：旧版通过项目的 stdio 封装器调用，现代版则通过固定为 2026-07-28 的生产直接获取 HTTP 处理器调用。它会验证已注册的输出模式、关键 Markdown/结构化结果、信任边界、错误/降级语义、现代线路标头，以及 create_issue_set 的默认试运行行为。测试夹具会在发生任何实时问题写入时立即失败，并阻止外部获取/套接字访问。 独立的 Inspector stdio 门禁通过专属锁文件固定 Inspector 2.0.0，并从进程外调用实际的 dist/index.js。它会验证旧版 initialize、全部 13 项工具声明、全部 5 次资源读取、一次明确不写入的 create_issue_set 预览，以及无效输入和未知资源 URI 的稳定 JSON/退出约定。每次 tools/call 都以 dryRun:true 调用 create_issue_set。Inspector 使用官方 -e 选项向目标传递固定的环境变量允许列表，并要求实际服务写入临时的 harness 加载标记，否则运行失败。harness 保留用户的 HOME 值，但会阻止产品探测全局配置文件，以非机密测试占位符替换继承的 GitHub 凭据，隔离 Inspector 存储/OAuth 状态，并禁用此 stdio 专用检查中的所有 fetch/TCP 连接。这是黑盒兼容性证据，不是 MCP 认证，也不能证明支持现代版 server/discover。

HTTP 门禁会在 127.0.0.1:0 上启动生产适配器，使用 Inspector 的非交互式 --stored-auth-only 模式访问规范 /mcp URL，将完整的工具/资源 JSON 与独立的 Inspector stdio 发现结果进行比较，并在成功或失败后关闭所有子进程。另有一个独立的空存储 401 回环测试固件，它会触发自动打开的条件，但仍要求立即返回 3/auth_required；浏览器启动标记会使任何交互式 OAuth 尝试导致门禁失败。harness 仅允许访问完全匹配的 IPv4 回环 fetch/socket 目标；DNS 别名、具有欺骗性的主机名、外部网络访问和继承的凭据仍不可用。在 Windows 上，Inspector 2.0.0 可能会先输出正确的 JSON 错误，随后触发一个上游 libuv 关闭断言。运行器仅接受该平台上完全匹配的状态码和两行特征，并报告原始退出类别；Linux 上的任何失败及其他所有失败都会阻止通过。

Conformance 试点固定使用官方 0.1.16 和其旧版 2025-11-25 活动套件。目前记录了 30 个场景：5 个直接通过，25 个受控预期失败。失败主要是因为上游 everything-server 的提示词、固件 URI、固件工具、订阅、媒体/回调能力以及有状态 SSE 假设，并不属于本产品的公开约定。每个预期失败都有原因、负责人和移除条件；出现新失败或过时条目都会导致运行失败。上传的 checks.json 不包含原始响应详情和凭据。这是非阻断式兼容性试点，不是认证，也不构成添加仅供测试使用的生产能力的理由。

CI 会在 Node 22 和 Node 24 上运行完整的产品测试套件和当前约定对比。独立的 Node 24 作业会重放不可变基线，并运行必需的约定/评估门禁：Inspector stdio/HTTP、Conformance、12 个固定场景、全部 13 项响应预算，以及包含 11 个用例的 GitHub 故障矩阵。门禁要求场景总准确率至少达到 90%，6 个安全关键场景的准确率达到 100%，随后仅上传 5 个有界摘要文件。由于 Node 20 已结束生命周期，因此不属于受支持的运行时；本地贡献者只需使用一个受支持的 Node 版本，兼容性矩阵则由 GitHub Actions 强制执行。

评估结果会保留其来源信息。scripted 表示确定性固件，recorded-agent 表示针对固定输入重放的脱敏历史执行记录，live-model 表示可选的当前模型运行。必需的 CI 包含 6 个 scripted 场景和 6 个 recorded-agent 场景，不运行 live-model。重放通过只能证明已检入的工作流仍然具有确定性；这并不意味着对所有模型、提供商、未来提示词或 MCP 认证作出保证。请参阅评估指南。 常规测试、contracts:check 和 contracts:verify-baseline 均不会重写基线。重放命令和仅供维护者使用的 contracts:generate 命令会验证固定的标签／提交，安装历史锁文件（禁用生命周期脚本、审计和赞助输出），在系统临时目录中构建，并在有界子进程中调用真实的 tools/list 和 resources/list；该子进程的工作目录始终位于检出目录之外。子进程只会接收允许列表中的操作系统路径、临时目录、区域设置和动态库环境变量；不会继承凭据、业务配置、NODE_OPTIONS 和本地状态路径。释放历史句柄后，Windows 清理操作会进行有界重试。这些命令需要访问 npm 注册表，但不会调用 GitHub API 或模型服务。只有 contracts:generate 会写入纳入版本控制的 JSON 文件，其差异会保留以供审查。

通过 Issue 和拉取请求参与贡献

欢迎提交 Issue 和拉取请求。开始之前，请查看未解决的 Issue和路线图。如果更改会影响公开行为、安全边界、工具架构或整体架构，请先创建 Issue。

1. Fork 此仓库，并从最新的 main 创建一个专注于单一主题的分支。
2. 运行 npm ci，然后仅进行贡献所需的更改。
3. 如果行为有变化，请添加或更新测试和文档。
4. 运行与更改相关的检查。Node 22/24 矩阵会运行 npm run check:line-endings、npm run typecheck、npm run build、npm run contracts:check 的构建版本、npm run test、npm run smoke 和 npm run test:coverage；单独的 Node 24 任务会运行不可变基线重放，以及固定版本的 Inspector stdio/HTTP 和 Conformance 合约检查。
5. 向 main 提交拉取请求。请说明问题、解决方案、风险、验证结果以及关联的 Issue。

请勿在提交、Issue、拉取请求和日志中包含令牌、凭据、私有仓库内容或生成的本地配置。CI 通过有助于审查，但不能取代维护者的批准。

• 路线图
• 仓库政策指南
• 客户端使用示例和可移植的审查技能
• 证据连续性与验收可追溯性
• 用户试点计划
• 测试策略
• 远程部署重新准入标准
• v1.10.0 发行说明
• v1.9.0 发行说明
• AI 编码 Agent 冒烟测试
• 变更日志
• 发行版本
• 未解决的 Issue

npm 和 MCP Registry 工作流使用 GitHub OpenID Connect (OIDC) 可信发布。发布 GitHub Release 会触发这两个工作流。Registry 工作流会等待对应 npm 包版本发布后，再发布与之匹配的不可变 stdio 元数据。

许可证

MIT