内容
# 循环工程 MCP 服务器
> **停止输入提示信息。开始设计自动提示信息的系统。**
使用 AI 代理自动完成重复的编码任务。只需设置一次，即可永久运行。
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
---
## 什么是该项目？
一个 MCP 服务器，为您的 AI 编码工作流程带来**循环工程**。不再手动为每个任务提示 AI 代理，而是设计循环为代理提示。每个循环都实现了规范的循环工程控制系统：
- 🔄 **自动运行**，按计划（心跳）
- 🔁 **迭代直到目标可验证满足** - 执行 → 验证 → 决策 → 重复
- 🧑🔧 **制作者/检查者分离** - 代理进行更改；**独立**的检查门决定目标是否满足（代理永远不会评估自己的作业）
- 🛑 **停止规则** - 在 N 次尝试后或重复失败时升级到人工（不会出现失控循环）
- 🌳 **工作树隔离** - 每个运行都有自己的 git 工作树，因此并行循环永远不会冲突
- 💸 **预算上限** - 每日运行限制和累计成本上限
- 🧠 **持久内存** - 状态文件，包含运行历史和经验教训，重启后仍可访问
- 🧪 **适用性测试** - 飞行前 4 条件检查，确保您只自动化循环形状的工作
**可以将其视为：** GitHub Actions + AI 代理 + 智能、自验证控制循环
---
## 为什么该项目如此强大？
### 循环工程之前
```
您：“检查 CI 失败” [5 分钟]
AI：[报告失败]
您：“是什么导致身份验证测试失败？” [3 分钟]
AI：[调查]
您：“修复它” [10 分钟]
AI：[编写修复程序]
您：“打开 PR” [2 分钟]
AI：[创建 PR]
总计：20 分钟 × 4 次/天 = 80 分钟/天
```
### 循环工程之后
```
[您只需设置一次：“创建 CI 分类循环，每 6 小时运行一次”]
循环自动：
✅ 检测失败
✅ 分类（故障 vs. 错误 vs. 环境问题）
✅ 为确定性错误草拟修复
✅ 运行测试
✅ 打开 PR
✅ 升级复杂问题
✅ 记录经验教训
总计：0 分钟/天（在您睡觉时运行）
```
**实际影响：**
- ⚡ **快 80%** - 循环并行运行，不需要您的关注
- 🎯 **更高质量** - 一致的检查，从过去的错误中学习
- 💰 **成本效益** - 仅在需要时运行，跟踪投资回报率
- 😴 **24/7 工作** - 在您睡觉时运行，在周末运行
---
## 您可以使用循环工程自动化什么？
### ✅ 适用于循环工程
- **CI 分类** - 分类失败，草拟修复，升级阻止程序
- **依赖项更新** - 检查更新，测试兼容性，创建 PR
- **Lint 和格式化** - 在每个 PR 上应用自动修复
- **文档同步** - 保持文档与代码更改的同步
- **Flaky 测试检测** - 确定和跟踪间歇性失败
- **安全补丁** - 自动应用安全更新
### ❌ 不适用于循环工程
- 架构决策（需要判断）
- 身份验证/支付代码（风险太大）
- 生产部署（需要人工监督）
- 模糊产品工作（不明确的成功标准）
---
## 安装
选择以下方法之一。两者都适用于 [设置](#设置-2-分钟) 中的 MCP 配置模板。
### 选项 1：uv（推荐）
[安装 uv](https://docs.astral.sh/uv/getting-started/installation/)，然后从 PyPI 运行服务器 - 不需要单独的 `pip install`：
```bash
uvx loop-mcp
```
在步骤 1 中使用 **uv** MCP 模板（`command`：`uvx`）。
### 选项 2：pip
```bash
pip install loop-mcp
```
验证它是否在您的 PATH 上：
```bash
loop-mcp
```
在步骤 1 中使用 **pip** MCP 模板（`command`：`loop-mcp`）。
### 选项 3：从源代码（本地开发）
**克隆并安装：**
```bash
# 克隆仓库
git clone https://github.com/yourusername/loop-engineering
cd loop-engineering
# 安装 Python 包
cd python
pip install -e ".[dev]"
```
---
## 设置（2 分钟）
### 步骤 1：添加到 AI 代理配置
#### 对于 Cursor
创建或编辑项目中的 `.cursor/mcp.json`。
**uv** ([选项 1](#选项-1-uv-推荐) - `uvx` 自动从 PyPI 获取 `loop-mcp`）：
```json
{
"mcpServers": {
"loop-engineering": {
"command": "uvx",
"args": ["loop-mcp"]
}
}
}
```
**pip** ([选项 2](#选项-2-pip) - 在 `pip install loop-mcp` 之后）：
```json
{
"mcpServers": {
"loop-engineering": {
"command": "loop-mcp"
}
}
}
```
#### 对于 Kiro
创建或编辑 `.kiro/settings/mcp.json` - 与上述 **uv** 或 **pip** 模板相同。
#### 对于 Claude Desktop
**Mac：** 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows：** 编辑 `%APPDATA%\Claude\claude_desktop_config.json`
使用与 Cursor 相同的 **uv** 或 **pip** 模板。
**本地开发？** 使用：
```json
{
"command": "python",
"args": ["-m", "loop_engineering_mcp"]
}
```
### 步骤 2：重启 AI 代理
- **Cursor**：重新加载窗口（Cmd/Ctrl + R）
- **Kiro**：自动重新连接
- **Claude Desktop**：重启应用程序
### 步骤 3：创建您的第一个循环
打开您的 AI 代理并说：
```
创建每 6 小时运行一次的 CI 分类循环
```
AI 将自动设置所有内容。
---
## 快速示例
### 创建循环
```
您：“创建 CI 分类循环”
AI：✅ 循环 'ci-triage' 已创建！
调度：每 6 小时
验证：npm test
目标：所有 CI 失败都被分类
已创建文件：
- .loop/loops.json（配置）
- .loop/skills/ci-triage.md（说明）
- .loop/state/ci-triage.json（状态跟踪）
您：“启动它”
AI：✅ 循环已启动，将自动运行
```
### 检查状态
```
您：“正在运行哪些循环？”
AI：📊 活动循环：
ci-triage
- 上次运行：2 小时前
- 今日 PR：3（2 个已合并）
- 接受率：67%
- 今日 Token 成本：$4.20
```
### 查看历史记录
```
您：“显示 ci-triage 状态”
AI：📊 ci-triage 状态：
最近 5 次运行：
- 2 小时前：分类 3 次失败，开启 2 个 PR
- 8 小时前：所有测试通过，无需采取行动
- 14 小时前：修复了易失性身份验证测试，升级了数据库问题
经验教训：
- 身份验证测试需要 AUTH_SECRET 环境变量
- 端到端测试需要 Stripe webhook 配置
```
---
## 可用工具
安装后，您的 AI 代理将获得这些工具：
| 工具 | 用途 |
|------|---------|
| `check_loop_suitability` | 在构建循环之前运行 4 条件测试 |
| `create_loop` | 设置新循环（检查门，停止规则，预算，隔离） |
| `start_loop` | 启动/恢复循环（激活调度器） |
| `stop_loop` | 暂停循环 |
| `run_loop_now` | 开始运行 - 返回主机代理执行的简报 |
| `complete_loop_run` | 提交尝试（循环体）：运行检查门，开启 PR，迭代或升级 |
| `list_pending_runs` | 显示调度器为下一个代理会话排队的运行 |
| `run_verification` | 按需运行循环的验证命令 |
| `set_goal_check` | 设置/更新独立检查门 |
| `configure_verification` | 设置/更新制造商自检命令 |
| `list_loops` | 查看所有循环及其状态 |
| `delete_loop` | 永久删除循环 |
| `add_skill` / `list_skills` | 管理可重用的技能模板 |
| `view_state` | 检查循环历史记录、尝试和指标 |
| `add_lesson` | 记录经验教训以供未来运行使用 |
| `get_metrics` | 查看整体性能 |
您的 AI 代理在您请求循环相关任务时自动使用这些工具。
### 运行实际循环
```
run_loop_now ──► 简报（目标，工作目录，停止规则）
│
▼
代理进行最小更改
│
▼
complete_loop_run ──► 制造商自检 ──► 独立检查门
│ │
│ ┌───────────┴───────────┐
│ 目标满足？ 否
│ │ │
▼ ▼ ▼
开启 PR 并停止 开启 PR 并停止 剩余尝试次数？ ── 是 ─► 迭代（相同 run_id）
│
否 / 重复失败
▼
升级到人工
```
---
## 本地开发设置
### Python
```bash
# 导航到 python 包
cd python
# 以开发模式安装
pip install -e ".[dev]"
# 运行 MCP 服务器
loop
# 运行后台工作线程（可选 - 用于计划执行）
loop-worker
# 运行测试
pytest
# 运行测试并生成覆盖率报告
pytest --cov
```
### 测试 MCP 服务器
1. **本地安装**（上述命令）
2. **在您的 AI 代理中配置**（请参阅设置部分）
3. **使用您的 AI 代理测试：**
```
"您有循环工程工具吗？"
"创建一个测试循环"
"列出所有循环"
```
---
## 项目结构
```
loop-engineering/
├── python/ # Python MCP 服务器
│ ├── src/
│ │ └── loop_engineering_mcp/
│ │ ├── server.py # MCP 服务器
│ │ ├── loop_manager.py # 循环 CRUD
│ │ ├── skill_manager.py # 技能模板
│ │ ├── state_manager.py # 状态跟踪
│ │ ├── loop_executor.py # 控制循环：隔离，检查门，停止规则
│ │ ├── scheduler.py # Cron 调度器（心跳）
│ │ ├── suitability.py # 4 条件循环适用性测试
│ │ ├── verification_runner.py # 制造商/检查门运行器
│ │ ├── github_client.py # GitHub 集成
│ │ └── worker.py # 后台工作线程
│ └── tests/
│
├── shared/ # 共享技能模板
│ └── skills/
│ ├── ci-triage.md
│ ├── dependency-updates.md
│ └── lint-fixes.md
│
└── references/ # 文档
├── README.md # 完整的循环工程指南
├── FRAMEWORK.md # 完整的实现指南，包含示例
└── QUICKSTART.md # 5 分钟设置
```
---
## 这是真正的循环工程吗？
循环工程（Addy Osmani / Codez / O'Reilly, 2026）将循环定义为具有六个部分的控制系统。该服务器映射到所有六个部分：
| 构建块 | 含义 | 服务器如何实现 |
|----------------|---------------|--------------------------|
| **自动化** | 触发运行的心跳 | Cron 调度器（`scheduler.py`）在计划上排队运行 |
| **工作树** | 独立目录，以便并行代理不会冲突 | 每个运行都有自己的 `git worktree`（`isolation: "worktree"`） |
| **技能** | 每运行一次读取的重用项目知识 | `.loop/skills/*.md`，注入每个运行简报 |
| **连接器** | 达到真实系统的工具 | MCP 本身 + GitHub PR 客户端 |
| **子代理（制造商/检查者）** | 单独的验证者评估工作 | 独立的 `goal_check_command` 门，与制造商的自检区分开 |
| **内存/状态** | 跨运行的持久状态 | `.loop/state/*.json`，包含运行记录、尝试记录、经验教训、预算 |
以及防止真实循环与 cron 作业分离的安全规则：**迭代直到目标** 循环、**停止规则**（最大尝试次数 + 无进展检测）、**预算上限** 和 **4 条件适用性测试**。
## 预构建的技能模板
### CI 分类
自动对 CI 失败进行分类并草拟修复：
- **Flakes** - 重试一次，如果持续存在，则提交问题
- **Bugs** - 立即草拟修复 PR
- **环境问题** - 升级并提供清晰的说明
- **依赖问题** - 草拟回滚 PR
### 依赖项更新
安全地保持包更新：
- 检查过时的包
- 测试兼容性
- 创建 PR 以进行安全更新
- 标记破坏性更改以供审查
### Lint & Format 修复
自动维护代码质量：
- 应用自动格式化
- 验证无逻辑更改
- 在提交前运行测试
- 开启清理 PR
---
## 配置选项
### 循环计划（Cron 格式）
```
"0 */6 * * *" # 每 6 小时
"0 9 * * 1" # 星期一 9 点
"0 0 * * *" # 每天午夜
"/30 * * * *" # 每 30 分钟
```
### 验证 & 制造商/检查门
循环有两个门户。**制造商自检** (`verification_command`) 是代理更改后运行的快速检查。**独立检查者** (`goal_check_command`) 是一个单独的客观命令，决定目标是否实际满足 - 因此编写代码的代理不是评估代码的代理。
```json
{
"verification_command": "npm test",
"goal_check_command": "npm run test:integration && npm run lint"
}
```
### 停止规则和预算
```json
{
"max_attempts": 3, // 失败 3 次后升级到人工
"max_runs_per_day": 24, // 每日运行上限（心跳预算）
"cost_budget": 5.00, // 累计 USD 代币成本上限（0 = 无限制）
"isolation": "worktree" // "worktree"（隔离，并行安全）或 "branch"
}
```
循环还执行**无进展检测**：如果连续两次出现相同的失败，它会立即升级，而不是烧掉代币进行死胡同。
### 环境变量
```bash
# 可选：GitHub 集成
export GITHUB_TOKEN="ghp_..."
# 可选：自定义工作区
export LOOP_WORKSPACE="/path/to/project"
```
---
## 文档
- **[QUICKSTART.md](./QUICKSTART.md)** - 5 分钟设置指南
- **[FRAMEWORK.md](./FRAMEWORK.md)** - 完整的实现指南，包含示例
- **[references/README.md](./references/README.md)** - 循环工程概念和理论
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - 如何贡献
- **[PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)** - 架构细节
---
## 故障排除
### MCP 服务器未找到
```bash
# 检查是否安装
loop-mcp --version
```
### AI 代理中工具不可用
1. 验证 MCP 配置文件是否为有效 JSON
2. 检查命令路径是否正确
3. 重启您的 AI 代理
4. 检查 AI 代理日志中的错误
### 权限错误
```bash
# Unix/Mac
chmod -R u+w .loop/
# Windows
icacls .loop /grant Users:F /T
```
---
## 常见问题
**问：我需要 API 密钥吗？**
A：否！您的 AI 代理（Cursor/Kiro/Claude）已经拥有自己的 API 密钥。此 MCP 服务器仅提供工具。
**问：它支持离线模式吗？**
A：MCP 服务器支持离线模式，但循环执行需要互联网（调用 AI API、创建 PR 等）
**问：安全性如何？**
A：循环永远不会自动合并到 main。 人工审查是必需的。 验证门户防止错误代码。
**问：我可以使用自己的 AI 模型吗？**
A：是的！适用于任何支持 MCP 的 AI 代理（Cursor、Kiro、Claude Desktop 等）
**问：费用是多少？**
A：MCP 服务器免费。您只需支付 AI API 使用费（与手动提示相同，但更高效）
---
## 致谢和许可证
### 循环工程概念
- **作者：** Codez（[@0xCodez](https://x.com/0xCodez））
- **文章：** [14 步路线图](https://x.com/0xCodez/status/2064374643729773029）
- **基于：** Anthropic 工程文档，Addy Osmani的文档
### 服务器实现
- **许可证：** [MIT](https://opensource.org/licenses/MIT)
- **仓库：** [GitHub](https://github.com/yourusername/loop-engineering)
### 模型上下文协议
- **开发：** [Anthropic](https://www.anthropic.com/)
- **文档：** [modelcontextprotocol.io](https://modelcontextprotocol.io)
---
## 支持
- 📖 **文档：** [FRAMEWORK.md](./FRAMEWORK.md)
- 🐛 **报告问题：** [GitHub 问题](https://github.com/yourusername/loop-engineering/issues)
- 💬 **讨论：** [GitHub 讨论](https://github.com/yourusername/loop-engineering/discussions)
- 🚀 **快速入门：** [QUICKSTART.md](./QUICKSTART.md)
---
## 下一步？
1. **安装** 服务器（1 个命令）
2. **配置** 您的 AI 代理（添加 JSON 配置）
3. **创建** 您的第一个循环（“创建 CI 分类循环”）
4. **监控** 性能（验收率、节省的时间）
5. **迭代** 基于学习成果
**构建循环。保持工程师身份。** 🚀
---
## 星级历史
⭐ 如果这为您节省了时间，请在 GitHub 上给我们一个星级！
---
**由 Loop Engineering 社区 ❤️ 制作**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器