内容
<p align="center">
<img src="assets/logo.svg" alt="MCP Logo" width="120"/>
</p>
<h1 align="center">Agentic SDLC 控制平面（agentic-sdlc-mcp）</h1>
<p align="center">
<b>将专业的、结构化的 SDLC 工作流作为 MCP 工具暴露给 AI 编码代理（Claude、Cursor 等），引导其通过安全、可审计的开发生命周期。</b>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/agentic-sdlc-mcp"><img src="https://img.shields.io/npm/v/agentic-sdlc-mcp.svg?style=flat-square&color=blue" alt="npm 版本"></a>
<a href="https://github.com/SakuraCianna/agentic-sdlc-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/SakuraCianna/agentic-sdlc-mcp/ci.yml?branch=main&style=flat-square" alt="CI 状态"></a>
<a href="https://www.npmjs.com/package/agentic-sdlc-mcp"><img src="https://img.shields.io/npm/dm/agentic-sdlc-mcp.svg?style=flat-square&color=green" alt="下载量"></a>
<a href="https://github.com/SakuraCianna/agentic-sdlc-mcp/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/agentic-sdlc-mcp.svg?style=flat-square&color=orange" alt="许可证"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square" alt="MCP 兼容"></a>
</p>
---
## 💡 什么是 Agentic SDLC 控制平面？
传统的 AI 代理可以编写代码，但通常缺乏软件工程学科的背景。它们可能会强制推送、绕过审查、不运行 CI、泄露密钥或跳过编写测试用例。
`agentic-sdlc-mcp` 是建立在 **模型上下文协议（MCP）** 之上的 **SDLC 协调层和控制平面**。它将 GitHub API 封装成高级、有偏见的工具，强制执行可追溯性、人工干预门控、质量阈值和安全检查，供 AI 编码代理使用。
### Agentic SDLC 环路
```mermaid
graph TD
A[阶段 1：计划] -->|暴露上下文和简报| B[阶段 2：创建]
B -->|增量提交| C[阶段 3：测试]
C -->|本地测试报告| D[阶段 4：审查]
D -->|人工审查门控| E[阶段 5：优化]
E -->|精炼| F[阶段 6：安全]
F -->|安全检查| G[人工发布批准]
G -->|发布标签和部署| A
```
---
## 🛠️ 工具分类
该服务器不是暴露原始 API 端点，而是提供围绕 SDLC 管道的 **12 种专门工具**：
| 类别 | 工具 | 描述 |
|---|---|---|
| **💡 规划和上下文** | [`repo_context`](#repo_context)<br>[`plan_from_context`](#plan_from_context)<br>[`prepare_work_item`](#prepare_work_item) | 了解代码库、构建阶段性计划并生成代理简报。 |
| **🚀 执行** | [`create_issue_set`](#create_issue_set) | 批量创建 GitHub 问题，直接映射到 SDLC 计划。 |
| **🔍 审查和验证** | [`quality_gate_status`](#quality_gate_status)<br>[`create_pr_summary`](#create_pr_summary)<br>[`review_pr_against_standard`](#review_pr_against_standard) | 审计 CI 检查、生成结构化 PR 摘要并审查代码是否符合 SDLC 标准级别。 |
| **🛡️ 治理和安全** | [`branch_protection_status`](#branch_protection_status)<br>[`workflow_permissions_audit`](#workflow_permissions_audit)<br>[`security_triage`](#security_triage)<br>[`release_readiness_check`](#release_readiness_check) | 查询分支规则强制执行、审计 Actions 工作流权限、排查漏洞并执行发布前检查。 |
| **🤝 交接和连续性** | [`agent_handoff_packet`](#agent_handoff_packet) | 编制一个数据包，以便其他代理可以无缝接管工作。 |
---
## 🗺️ 系统架构
```mermaid
sequenceDiagram
autonumber
actor Developer as 人工所有者
participant Agent as AI 编码代理（Cursor/Claude）
participant MCP as agentic-sdlc-mcp（控制平面）
participant GitHub as GitHub API
participant npm as npm 注册表
Developer->>Agent: "为仓库 X 创建一个功能"
Agent->>MCP: 调用 repo_context / plan_from_context
MCP->>GitHub: 获取仓库状态和文件树
GitHub-->>MCP: 仓库元数据和文件
MCP-->>Agent: SDLC 计划和上下文简报
Note over Agent: 代理开发代码...
Agent->>MCP: 调用 review_pr_against_standard / quality_gate_status
MCP->>GitHub: 审计拉取请求、CODEOWNERS 和检查状态
GitHub-->>MCP: 拉取请求批准、CI 检查状态
MCP-->>Agent: 验证报告和发现
Note over Developer,Agent: 人工审查门控：合并 PR
Developer->>MCP: 触发 gh release create v1.3.0
MCP->>GitHub: 创建发布标签
GitHub->>GitHub: 触发 publish.yml 工作流（OIDC）
GitHub->>npm: 发布软件包（签名证明）
```
---
## 📋 先决条件
在运行服务器之前，请确保您已：
1. **Node.js >= 24** 已安装在您的系统上。
2. **GitHub 个人访问令牌（PAT）**：
* **所需范围**：
* `repo`（私有/公共仓库、问题、PR 和检查的完全控制权）。
* `security_events`（查询 Code Scanning 和 Dependabot 警报）。
* 注意：如果安全端点失败，请确保根据 [GitHub REST API 文档](https://docs.github.com/en/rest) 验证令牌权限。
---
## ⚡ 快速入门
### 1. 通过 npx 即时运行（推荐）
您无需下载或克隆仓库。直接在 MCP 客户端环境中运行服务器：
```bash
npx -y agentic-sdlc-mcp
```
### 2. 全局安装
或全局安装软件包：
```bash
npm install -g agentic-sdlc-mcp
# 使用全局命令启动
agentic-sdlc-mcp
```
### 3. 本地开发（从源代码）
如果您想从源代码运行或扩展服务器：
```bash
git clone https://github.com/SakuraCianna/agentic-sdlc-mcp.git
cd agentic-sdlc-mcp
npm install
npm run build
node dist/index.js
```
---
## ✅ 通用 AI 编码代理烟雾测试
如果您需要在任何支持 MCP 的 AI 编码代理中验证此 MCP 服务器，请遵循 [`docs/ai-coding-agent-smoke-test.md`](docs/ai-coding-agent-smoke-test.md) 中的客户端中立指南。它涵盖了最小配置、仓库备用行为、`repo_context` 只读验证和 `create_issue_set` 干燥运行预览，而无需创建 GitHub 问题。
---
## ⚙️ MCP 客户端配置
将此服务器配置添加到您的 MCP 客户端设置文件（例如 `claude_desktop_config.json`、Cursor 或 Windsurf 设置）：
### Claude Desktop / Cursor / Windsurf（使用 npm 软件包）
```json
{
"mcpServers": {
"agentic-sdlc": {
"command": "npx",
"args": ["-y", "agentic-sdlc-mcp"],
"env": {
"GITHUB_TOKEN": "替换为 GitHub 令牌",
"GITHUB_OWNER": "您的 GitHub 用户名或组织",
"GITHUB_REPO": "您的目标仓库"
}
}
}
}
```
### 🔑 全局配置和交互式设置（持久性）
除了在 MCP 客户端配置中指定环境变量外，您还可以使用交互式终端问卷全局配置您的 GitHub 凭证。设置将保存到 `~/.agentic-sdlc-mcp.json` 下您的主目录，并在后续运行中自动加载。
#### 1. 通过 CLI 配置
运行配置命令：
```bash
npx agentic-sdlc-mcp configure
```
这将指导您配置：
* `GITHUB_TOKEN`（主要令牌；[在此处生成经典令牌](https://github.com/settings/tokens)并具有 `repo` 和 `read:org` 范围）
* `GITHUB_OWNER`（默认仓库所有者名称，可选）
* `GITHUB_REPO`（默认仓库名称，可选）
#### 2. 自动设置提示（TTY）
如果您直接运行 `npx -y agentic-sdlc-mcp` 而没有配置的 `GITHUB_TOKEN`，该工具会检测它是否在交互式环境（TTY）中，并自动启动提示流程。如果它在非交互式环境中运行（例如 Claude Desktop 在后台启动），它会正常退出并提供清晰的设置说明。
#### 3. 全局环境变量（备用）
您仍然可以在终端 shell 中直接定义环境变量（`PowerShell` for Windows 或 `bash` for macOS/Linux）：
```powershell
# Windows PowerShell
$env:GITHUB_TOKEN = "替换为 GitHub 令牌"
$env:GITHUB_OWNER = "您的组织"
$env:GITHUB_REPO = "您的仓库"
```
---
## 🎯 典型场景和最佳实践
AI 代理不应盲目运行命令或在没有结构的情况下编写代码。此控制平面强制执行软件工程学科。以下是推荐的代理协作模式：
### 场景 1：启动功能/修复
当代理启动任务时，它必须遵循此清单以防止“盲编码”：
1. **收集上下文**：调用 [`repo_context`](#repo_context) 以检查当前问题、PR 和分支状态。
2. **设计计划**：调用 [`plan_from_context`](#plan_from_context) 并提供任务目标。这将概述与 SDLC 阶段（计划、创建、测试、审查、优化、安全）对应的结构化问题。
3. **编写问题**：调用 [`create_issue_set`](#create_issue_set) 并设置 `dryRun: false` 以直接将检查清单发布到 GitHub。
4. **获取工作简报**：调用 [`prepare_work_item`](#prepare_work_item) 获取精确的指南、范围定义和相关文件。
### 场景 2：保护拉取请求门控
在提交 PR 进行人工审查之前，代理必须验证其自身质量：
1. **生成 PR 摘要**：调用 [`create_pr_summary`](#create_pr_summary) 自动生成结构化、专业的发布说明和文件差异更改。
2. **审计 CI 状态**：调用 [`quality_gate_status`](#quality_gate_status) 以确保所有 GitHub Actions 测试和 linting 检查运行均通过绿色。
3. **执行静态审计**：调用 [`review_pr_against_standard`](#review_pr_against_standard) 并设置 `standard: "strict"` 或 `"security-focused"` 以扫描差异的关键泄漏、验证 `.env` 安全性和确保 `.github/CODEOWNERS` 审查者正确分配。
### 场景 3：发布准备检查
当准备完成且请求发布时：
1. **漏洞检查**：调用 [`security_triage`](#security_triage) 以审计 Code Scanning（SAST）、Dependabot 和 Secret Scanning。确保没有关键警报阻止发布。
2. **发布准备就绪**：调用 [`release_readiness_check`](#release_readiness_check) 以生成回滚指令模板、验证没有未解决的发布阻塞问题，并确保 CHANGELOG.md 已更新。
3. **交接**：如果将部署职责转移给另一个代理，请调用 [`agent_handoff_packet`](#agent_handoff_packet) 以传递完整的审计日志。
---
## 📖 工具参考
暴露的 MCP 工具的详细规范。
### `repo_context`
读取仓库元数据、README、package.json、开放问题和开放 PR。可选地作为完整的“仓库简报包” - 检测到的包管理器、技术栈、常见验证脚本、工作流文件名、轻量级治理信号和代理指令文件摘要（例如 `AGENTS.md`、`CLAUDE.md`）。使用此功能开始任何工作流以定位代理。
请求时，`readmeSummary` 和 `packageJsonSummary` 值也包含在 `structuredContent` 中，因此代理无需从 Markdown 响应中恢复它们。
* **参数：**
* `owner`（字符串，可选）：GitHub 所有者。
* `repo`（字符串，可选）：GitHub 仓库。
* `includeReadme`（布尔值，默认为 `true`）：包括截断的 README 摘要。
* `includePackageJson`（布尔值，默认为 `false`）：包括 package.json 摘要、检测到的包管理器（npm/pnpm/yarn/bun）、技术栈和常见脚本（build/test/typecheck/lint/smoke/...）。
* `includeWorkflows`（布尔值，默认为 `false`）：包括 `.github/workflows/*.yml` 文件名（仅限文件名 - 使用 `workflow_permissions_audit` 获取权限内容）。
* `includeAgentInstructions`（布尔值，默认为 `false`）：包括在仓库根目录找到的代理指令文件摘要（`AGENTS.md`、`CLAUDE.md`）。
* `includeGovernance`（布尔值，默认为 `false`）：包括是否存在 CODEOWNERS 文件（对于完整的分支保护详细信息，请使用 `branch_protection_status`）。
* `includeOpenIssues` / `includeOpenPRs`（布尔值，默认为 `false`）：包括最近的开放问题/PR。
* `issueLimit` / `prLimit`（数字，默认为 `20`，最大 `100`）：限制获取的问题/PR 数量。
* `maxReadmeChars`（数字，默认为 `3000`）：最大 README 字符数（截断前）。
* `maxInstructionChars`（数字，默认为 `1000`）：每个代理指令文件摘要的最大字符数（截断前）。
### `plan_from_context`
生成一个结构化、分阶段的 SDLC 计划，与标准里程碑相匹配，针对 `workType` 量身定制。每个工作类型都有实质上不同的计划 - 例如 `docs` 默认不要求代码单元测试，`bugfix` 始终包括重现和回归测试，`security` 始终包括威胁模型和最小特权审查，而 `release`/`infra` 始终分别包括 changelog/回滚和工作流权限检查。
响应包含 3-5 个结构化的 `issueDrafts`，其标题、Markdown 正文、确认的仓库标签、SDLC 阶段、验收标准、风险级别和源目标可以直接传递给 `create_issue_set`。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `goal`（字符串，必填）：目标功能或修复描述。
* `workType`（字符串，可选）：`docs` / `feature` / `bugfix` / `refactor` / `security` / `release` / `infra`之一。如果省略，则根据`goal` + `acceptanceCriteria`通过保守的关键字启发式推断 - 响应中的`confidence`（`high`/`medium`/`low`）和`needsClarification`字段告诉您是否信任猜测或显式传递`workType`。
* `constraints`（字符串数组，可选）：技术或业务约束。
* `acceptanceCriteria`（字符串数组，可选）：明确的验收标准（也用于工作类型推断）。
### `create_issue_set`
预览或批量创建映射到生成计划的 GitHub 问题。干预响应包括目标仓库、最终标题、标签、正文摘要和人工审查警告，而无需调用 GitHub 写入 API。实时批次保留成功的项目编号和 URL，同时报告每个项目的安全失败原因，以便一个被拒绝的问题不会隐藏早期成功或停止后续尝试。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `issues`（对象数组，必填）：结构化的问题列表（标题、正文、标签和可选的指定人员）。直接接受 `plan_from_context.issueDrafts`。
* `dryRun`（布尔值，默认为 `true`）：如果为 `true`，则在不写入 GitHub 的情况下预览列表。
### `prepare_work_item`
为特定问题生成一个包含目标、非目标和技术风险的代理就绪简报。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `issueNumber`（数字，必填）：目标问题 ID。
* `includeRelatedFiles`（布尔值，默认为 `false`）：启发式提取提到的文件路径。
* `includeRecentPRs`（布尔值，默认为 `false`）：扫描最多 5 个合并的 PR，这些 PR 涉及这些路径。
### `quality_gate_status`
审计给定 PR 或 git 引用（CI 状态、构建状态、linting 状态）的检查运行。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `pullNumber`（数字，可选）：按 PR 编号查询检查。
* `ref`（字符串，可选）：按分支、标签或 SHA 查询检查。
### `create_pr_summary`
生成结构化的拉取请求描述和更改日志草稿。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `pullNumber`（数字，必填）：拉取请求 ID。
### `review_pr_against_standard`
根据 SDLC 治理级别审查拉取请求代码更改（`basic` / `strict` / `security-focused`）。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `pullNumber`（数字，必填）：拉取请求 ID。
* `standard`（字符串，默认为 `"basic"`）：标准级别。
* `checkOwnership`（布尔值，默认为 `true`）：验证文件所有权更改是否与 `.github/CODEOWNERS` 一致，并标记未分配的审查者。
### `security_triage`
检索并对 Code Scanning、Dependabot 和 Secret Scanning 警报进行分类。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
### `release_readiness_check`
评估发布前健康状况（测试、开放问题、更改日志）并生成回滚说明。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `headRef`（字符串，可选）：目标发布分支/标签。
### `branch_protection_status`
查询经典分支保护和仓库规则集，以获取所需的审查、状态检查和推送限制。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `branch`（字符串，可选）：目标分支。默认为默认分支。
### `workflow_permissions_audit`
扫描 `.github/workflows/*.yml` 文件的 `permissions` 块并标记过度授权的令牌。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `ref`（字符串，可选）：Git 引用。默认为默认分支。
### `agent_handoff_packet`
将当前问题上下文、已完成的工作和剩余任务编译成一个紧凑的提示数据包，供下一个代理使用。
* **参数：**
* `owner` / `repo`（字符串，可选）：仓库坐标。
* `issueNumber`（数字，必填）：活动问题 ID。
---
## 📚 资源参考
服务器通过 `sdlc://` 方案公开只读静态资源以供代理快速指导：
| 资源 URI | 描述 |
|---|---|
| `sdlc://standards/agentic-sdlc` | Agentic SDLC 标准完整 Markdown 规范。 |
| `sdlc://templates/issue` | 创建结构化 GitHub 问题的 Markdown 模板。 |
| `sdlc://templates/pr-summary` | PR 描述和更改日志的 Markdown 模板。 |
| `sdlc://templates/release-readiness` | 发布前审计的检查清单。 |
| `sdlc://templates/handoff` | 代理交接的提示数据包模板。 |
---
## 🔒 安全默认值和 `dryRun` 模型
为了防止 AI 编码代理对生产仓库执行破坏性或意外操作，此控制平面强制执行：
* **默认预览（`dryRun: true`）**：所有编写数据的工具（例如 `create_issue_set`）默认运行在预览模式下。写入需要显式传递 `dryRun: false`。
* **可审查的批量结果**：问题预览公开目标仓库和写入前的警告。实时批次保留成功的实际结果和安全失败详细信息，而不是隐藏部分完成。
* **零自我合并策略**：不存在自动合并拉取请求的工具。所有合并门控都需要人工批准。
* **访问限制**：服务器不支持强制推送或删除分支规则。
* **CODEOWNERS 强制审查**：特殊路径（例如 `.github/` 下的工作流和 `src/` 下的核心文件）需要所有者批准。
---
## 📦 开发者指南和 npm 发布
### 开发脚本
* `npm run typecheck`: 运行 TypeScript 编译器类型检查。
* `npm run build`: 将 TS 文件编译到 `dist/` 目录。
* `npm run test`: 执行完整的单元测试套件。
* `npm run smoke`: 在不使用外部凭证的情况下验证注册和加载。
### OIDC 信任发布（适用于维护人员）
此软件包使用 **受信任发布（OIDC）** 安全发布到 npm，从而消除了在仓库中存储静态 `NPM_TOKEN` 机密的需求。发布由创建 GitHub 发布或手动运行操作触发。
---
## 📄 许可证
在 [MIT 许可证](LICENSE) 下公开。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器