aws-samples/sample-sop-mcp
GitHub: aws-samples/sample-sop-mcp
一个将可重复的多步骤流程转化为标准作业程序的 MCP Server，让 AI Agent 逐步门控执行并确保每一步输出可审计。
Stars: 3 | Forks: 0
# sample-sop-mcp
[](https://github.com/aws-samples/sample-sop-mcp/actions/workflows/ci.yml) [](LICENSE)
一个 MCP server，它会一次一步地将过程交接给你的 AI 助手，并要求其在继续下一步之前生成具体的输出。你可以使用自然语言与你的 agent 交流 —— Kiro, Cursor, Claude Desktop, Strands agent 或任何 MCP client —— 它会在底层为你调用 SOP 工具。
## ✨ 功能
- **🗣️ 自然语言驱动** — 要求你的 agent 运行或编写 SOP；你无需手动调用工具
- **👣 逐步执行** — 每一步都必须被执行并产生输出，然后 agent 才能继续下一步
- **✅ 门控与可审计** — RFC 2119 级别 (MUST, SHOULD, MAY) 逐步交付，每一步都以上一步为门控前提，且进度保持明确
- **📦 开箱即用** — 首次启动时即植入四个可直接运行的 SOP
- **✍️ 引导式编写** — 内置指南会对你进行访谈，起草、lint 并发布新的 SOP
- **🔌 处处可用** — 支持一键安装至 Kiro, Cursor 和 VS Code；也支持为任何 MCP client 进行手动配置
## 🤔 什么是 SOP？
Standard Operating Procedure（标准作业程序）是一个 markdown 文档，用于记录可重复的、多步骤的过程 —— 代码审查、新员工入职、发布版本。LLM 功能强大，但在多步骤工作中表现难以预测：它们会跳过步骤，只做总结而不执行，并且会忘记进行到哪一步。sop-mcp 使这种行为变得可预测 —— 过程逐步送达，执行受到门控，进度清晰明确。
每一步都要求 agent 去*执行* —— 而不仅仅是阅读。它必须在继续下一步之前产生该步骤预期的输出，这正是使运行过程可审计的原因。作为人在回路（human in the loop）中的一员，你可以看到每一步的结果，并随时进行干预。
## 🧩 Agent SOP 与 Skills 的对比
这里的 SOP 使用 [Agent SOP](https://github.com/strands-agents/agent-sop) 格式 —— 便携的 markdown 工作流（参数化，并带有 RFC 2119 `MUST`/`SHOULD`/`MAY` 约束），用于指导 agent 完成多步骤过程。[Agent Skill](https://agentskills.io) *同样*是指导 agent 的 markdown，因此两者看起来很相似 —— 真正的区别在于**指令是如何传达给 agent 的**：
- **作为 Skill** — 整个 playbook 会一次性加载到 context 中，由 agent 自主引导，因此它可以提前读取、跳过、批处理或总结。非常适合领域知识和灵活的任务。（Agent SOP 甚至可以导出为 Skills 格式。）
- **通过 sop-mcp** — 相同的 SOP 会*一次一步*地分配。agent 只能看到当前步骤，并且必须在下一步释放之前报告其输出。它无法提前查看或跳过 —— 这正是使多步骤运行保持一致性和可审计性的关键。
| | 作为 Skill | 通过 sop-mcp 运行 |
| ----------------- | -------------------------------- | -------------------------------------------------- |
| 交付 | 一次性交付整个 playbook | 一次一步 |
| 顺序 | agent 自律 | 门控 — 必须提供输出才能继续 |
| 进度状态 | 无 | 被追踪且明确 |
| 提前查看 / 跳过 | 可能 | 不可能 |
| 形式 | 静态 markdown 文件 | 运行中的 server + 工具 (lint / publish / feedback) |
| 最适用于 | 领域参考，灵活的任务 | 需要一致性和审计的多步骤流程 |
（另外，这个 repo 还提供了一个常规的 skill —— [`sop-mcp-usage`](skills/sop-mcp-usage/SKILL.md) —— 用于教导 agent *如何*驱动该 server。）
## 📦 内置 SOP
Server 附带四个 SOP —— 按名称要求你的 agent 运行任意一个：
| SOP | 功能 |
| --------------------------- | --------------------------------------------------------------------------- |
| `sop_creation_guide` | 包含 RFC 2119 要求的 7 步引导式新 SOP 编写指南 |
| `code_review_process` | 标准代码审查工作流 — 准备、审查、处理反馈、合并 |
| `employee_onboarding_setup` | 新员工 IT 设置 — 别名、电子邮件、硬件选择 |
| `user_onboarding_process` | 配置身份、应用访问权限和欢迎包 |
## 🛠️ 工具
agent 会代表你调用这些工具 —— 你无需直接调用它们。
| 工具 | 用途 |
| --------------------- | -------------------------------------------------------------------------------------- |
| `list_resources` | 发现可用的 SOP（内置于每个 MCP client） |
| `read_resource` | 在执行前读取 SOP 的完整内容 |
| `run_sop` | 逐步执行 SOP |
| `lint_sop` | 根据 `publish_sop` 执行的相同规则验证草稿 SOP，但不进行写入 |
| `publish_sop` | 创建或更新 SOP |
| `submit_sop_feedback` | 记录改进建议 |
完整参数参考：[docs/mcp-reference.md](docs/mcp-reference.md)
## 💾 存储
首次运行时，server 会将内置 SOP 植入你的存储目录 —— 默认为 `~/.sop_mcp`，或者设置 `SOP_STORAGE_DIR` 将其指向其他位置。内置 SOP 仅在该目录中还没有任何 SOP 时才会被复制，因此你编写的任何内容都不会被覆盖。
要使用自定义位置，请在 server 配置中添加 `SOP_STORAGE_DIR` 环境变量：
```
{
"mcpServers": {
"sop-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/aws-samples/sample-sop-mcp", "sop-mcp"],
"env": { "SOP_STORAGE_DIR": "/path/to/your/sops" }
}
}
}
```
## 📚 文档
| 受众 | 资源 |
| ---------- | --------------------------------------------------------------------- |
| AI 工具 | [`llms.txt`](llms.txt) — 自动发现的 server 描述 |
| 用户 | [`skills/sop-mcp-usage/`](skills/sop-mcp-usage/SKILL.md) — 如何使用 |
| 开发者 | [`CONTRIBUTING.md`](CONTRIBUTING.md) — 构建、测试、设计决策 |
| 参考 | [`docs/mcp-reference.md`](docs/mcp-reference.md) — 完整的工具 schema |
## 💻 开发
```
uv sync # install dependencies
uv run pytest # run tests
uv run ruff check src/ tests/ # lint
uv run sop-mcp # start server locally
uv run python scripts/generate_docs.py # regenerate docs
```
## 🔐 安全
有关安全策略、漏洞报告流程和安全模型文档，请参阅 [SECURITY.md](SECURITY.md)。
更多信息请参阅 [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications)。
## 许可证
本库采用 MIT-0 许可证授权。详见 LICENSE 文件。
以 Mermaid 序列图展示的相同流程
``` sequenceDiagram actor User participant Agent as AI Agent (MCP client) participant SOP as sop-mcp server participant Store as SOP storage (~/.sop_mcp) User->>Agent: "Run the code review SOP" Agent->>SOP: list_resources SOP->>Store: scan *.sop.md Store-->>SOP: SOP names SOP-->>Agent: available SOPs (sop://...) Agent->>SOP: run_sop(sop_name, current_step=0) SOP->>Store: read SOP markdown SOP-->>Agent: Step 1 of N + execution rules Agent->>Agent: execute step 1 (do the work) Agent->>SOP: run_sop(current_step=1, step_output="...") Note over Agent,SOP: required — step_output gates the next step opt human in the loop Agent-->>User: optionally show progress / ask input end SOP-->>Agent: Step 2 of N Note over Agent,SOP: repeat until the final step SOP-->>Agent: "SOP execution complete." Agent-->>User: done ```标签：AI代理, MCP, SOC Prime, 工作流引擎, 开发工具, 标准作业程序(SOP), 流程自动化, 逆向工具, 防御加固