Cycles MCP

循环MCP服务器

](https://www.npmjs.com/package/cycles-mcp)  

一个模型上下文协议（MCP）服务器，用于管理所有存储库中的开发周期、任务和git工作流。

特性

• 🔄 基于周期的开发 -将工作组织成有时间限制的周期
• 📝 任务管理 -使用自动进度更新创建和跟踪任务
• 🎯 灵活的尺寸 -在简单层或粒度控制之间进行选择
• 🔧 Git集成 -直接提交、推送和创建PR
• 📊 进度跟踪 -自动进度条和会话日志
• 🔀 依赖追踪 -自动对并行执行的任务进行分组
• 👥 团队协调 -查看哪些任务可以同时完成
• 📄 模板 -所有项目的一致文档
• 🤖 AI友好 -与Cursor和其他MCP客户端无缝协作

安装

添加到MCP客户端设置(~/.cursor/mcp.json 对于光标， ~/.config/claude/claude_desktop_config.json 克劳德桌面版）：

选项A:npx（推荐，零安装）

{
  "mcpServers": {
    "cycles": {
      "command": "npx",
      "args": ["cycles-mcp"]
    }
  }
}

选项B：全局安装

npm install -g cycles-mcp

{
  "mcpServers": {
    "cycles": {
      "command": "cycles-mcp"
    }
  }
}

方案C：地方发展

git clone https://github.com/btbishop93/cycles-mcp.git
cd cycles-mcp
bun install
bun run build

{
  "mcpServers": {
    "cycles": {
      "command": "node",
      "args": ["/path/to/cycles-mcp/dist/index.js"]
    }
  }
}

重新启动MCP客户端

重新启动Cursor/Claude Desktop以加载MCP服务器。

用法

初始化新回购中的工作流

初始化时，AI将提示您进行所有必需的配置：

User: Initialize the cycles workflow for this project
AI: I'll help you set up the workflow. First, let me ask a few questions:
    - What sizing mode do you prefer? (simple/granular)
    - [If simple] What skill tier? (junior/mid/senior)
    - [If granular] What difficulty/duration/detail level?
    - How long should each cycle be? (weeks/months/quarters)
    - How many hours do you have per cycle?
AI: *calls init-workflow with your configuration*

重要提示： AI将在创建工作流之前要求进行配置。您必须提供：

• 尺寸模式（简单或粒度）
• 技能等级/级别
• 周期持续时间和时间框架
• 每个周期可用小时数

简单模式 （推荐给大多数用户）：

User: Initialize workflow with simple mode, mid tier, 2 weeks, 16 hours
AI: *calls init-workflow with your settings*

粒度模式 （适用于高级用户）：

User: Initialize workflow with 8h tasks, senior difficulty, low detail level, 1 month, 40 hours
AI: *calls init-workflow with granular settings*

可用选项：

• 简单模式：选择一层

- junior -1小时任务，高细节（循序渐进） - mid -2小时任务，中等细节（平衡） - senior -4小时任务，低细节（高层次目标）

• 粒度模式：指定每个：

- 困难： junior, mid, senior - 持续时间： 0.5h, 1h, 2h, 4h, 8h - 详细信息： high, medium, low

• 循环周期:

- 1-3周 - 1-2个月 - 1个季度（3个月）

• 每个周期的小时数：你能为这个周期投入多少小时

创建循环

User: Create a new cycle called "Authentication System"
AI: *calls create-cycle*

详细信息：

User: Create cycle "API Development" with goal "Build REST API"
AI: *calls create-cycle with description and goal*

将任务添加到循环中

基本任务：

User: Add task "Setup database schema" to cycle 01
AI: *calls add-task with default settings from config*

有依赖关系（用于并行化）：

User: Add task "User authentication" to cycle 01, depends on Task 001
AI: *calls add-task with dependencies, automatically groups tasks*

使用完整元数据：

User: Add task "Implement OAuth" to cycle 01:
- Depends on: Task 001, Task 002
- Conflicts with: None
- Modifies: src/auth/, database users table
- Duration: 8h, senior difficulty
AI: *calls add-task with full metadata*

为什么要指定依赖关系？

• 任务会自动分组到并行执行组中
• 团队可以看到哪些任务可以同时完成
• LLM代理可以在不同的组中工作而不会发生冲突
• 循环README显示了清晰的视觉分组：🟢 第1组（现在开始），🟡 第2组（在第1组之后）等。

处理任务

1.承诺你的工作

User: Commit this with message "add user model"
AI: *calls commit-task*

详细正文：

User: Commit "add user model" with details about validation logic
AI: *calls commit-task with body*

2.推送你的分支

User: Push this branch
AI: *calls push-branch*

3.创建拉取请求

User: Create PR for task 001 "Setup database"
AI: *calls create-pr, automatically marks task complete*

跟踪进度

User: Update progress for cycle 01, mark task 002 complete
AI: *calls update-progress*

记录会话：

User: Log session for today, worked 2 hours on task 003
AI: *calls update-progress with session details*

可用工具

可用资源

工作流概述

1.初始化（每次重复一次）

重要： 这必须先做！所有其他工具都验证初始化是否完成。

init-workflow → creates:
  - .cycles-config.json (configuration)
  - WORKFLOW.md (workflow guide)
  - docs/cycles.md (cycles tracker)
  - docs/cycles/ (cycles directory)
  - .github/pull_request_template.md (PR template)

如果没有正确的初始化，其他工具将返回一个错误，列出丢失的文件。

2.创建循环

create-cycle → creates docs/cycles/01-cycle-name/README.md

3.添加任务

add-task → creates docs/cycles/01-cycle-name/001-task-name.md
add-task → creates docs/cycles/01-cycle-name/002-task-name.md
...
→ Automatically updates cycle README with task dependencies
→ Groups tasks for parallel execution

任务依赖性分组：

• 无依赖关系的任务→ 🟢 第1组（立即开始）
• 任务取决于第1组→ 🟡 第2组（平行于第1组）
• 任务取决于第2组→ 🟡 第3组（平行于第2组）
• 最终集成任务→ 🔴 最后一组

同一组内的任务可以同时处理！

4.按任务工作

# For each task:
1. Create branch: feat/cycle-01-task-001-description
2. Work and commit incrementally (commit-task)
3. Push branch (push-branch)
4. Create PR (create-pr) → auto-marks task complete
5. Repeat for next task

5.跟踪进度

创建PR时，进度会自动更新。您还可以手动更新：

update-progress → marks tasks complete, updates progress bars

配置

每个存储库都有一个 .cycles-config.json 文件：

{
  "sizing_mode": "simple",
  "simple_tier": "mid",
  "cycle_duration": {
    "unit": "weeks",
    "value": 2
  },
  "hours_per_cycle": 16
}

或颗粒状：

{
  "sizing_mode": "granular",
  "difficulty": "senior",
  "task_duration": "4h",
  "detail_level": "low",
  "cycle_duration": {
    "unit": "months",
    "value": 1
  },
  "hours_per_cycle": 40
}

例子

示例1：快速启动（简单模式）

User: Initialize cycles workflow with mid tier
AI: Creates structure, uses 2h tasks with medium detail

User: Create cycle "User Management"
AI: Creates cycle 01

User: Add tasks for signup, login, and profile
AI: Creates 3 tasks, each ~2h

User: (work on task 001, then...)
User: Commit "implement signup form"
AI: Commits with conventional format

User: Create PR for task 001
AI: Creates PR, marks task complete

示例2：高级开发人员（粒度模式）

User: Initialize workflow with 8h tasks, senior difficulty, low detail
AI: Creates structure for experienced devs

User: Create cycle "Microservices Architecture"
AI: Creates cycle 01

User: Add task "Design service boundaries"
AI: Creates high-level task with minimal hand-holding

User: (work on task, then...)
User: Create PR for task 001
AI: Creates PR with your changes

示例3：兼职贡献者

User: Initialize workflow with junior tier, 1 week cycles, 8 hours per cycle
AI: Creates structure with 8 1-hour tasks per cycle

User: Create cycle "Bug Fixes"
AI: Creates cycle with appropriate size

User: Add 8 small bug fix tasks
AI: Creates detailed, 1-hour tasks

示例4：并行工作的团队

User: Initialize workflow for team collaboration
AI: Sets up structure

User: Create cycle "E-commerce Platform"
AI: Creates cycle 01

User: Add tasks:
1. "Setup database" - no dependencies
2. "Create product API" - depends on Task 001
3. "Design UI components" - no dependencies
4. "Build shopping cart" - depends on Task 002, 003
5. "Payment integration" - depends on Task 004

AI: Creates tasks and groups them automatically in cycle README:

🟢 Group 1 (Start Immediately):
- [ ] 001 - Setup database
- [ ] 003 - Design UI components

🟡 Group 2 (After Group 1):
- [ ] 002 - Create product API (needs 001)

🟡 Group 3 (After Group 2):
- [ ] 004 - Build shopping cart (needs 002, 003)

🔴 Group 4 (Final Tasks):
- [ ] 005 - Payment integration (needs 004)

> Parallelization tip: Tasks within the same group can be worked on simultaneously

结果：

• 两个开发人员可以同时处理任务001和003
• 一旦完成，一个开发人员启动002，而另一个则处理文档
• 任务004在002和003完成后可用
• 整个团队清晰可见！

Git工作流集成

MCP服务器遵循以下约定：

分支命名

feat/cycle-XX-task-YYY-description

例子： feat/cycle-01-task-001-setup-database

提交消息

(cycle-XX): 

[optional body]

例子： feat(cycle-01): add user authentication

拉取请求

• 标题： feat(cycle-XX): Task description
• 正文：根据PR模板自动生成
• 创建时自动将任务标记为已完成

发展

在开发模式下运行

bun run dev

类型检查

bun run type-check

构建

bun run build

故障排除

服务器未显示在光标中

1. 检查MCP设置文件是否为有效的JSON
2. 确保路径 dist/index.js 是正确的
3. 完全重新启动游标
4. 检查游标日志是否有错误

工具不工作

1. 确保 init-workflow 先跑
2. 所有工具在运行之前都会验证工作流是否已正确初始化
3. 所需文件： .cycles-config.json, WORKFLOW.md, docs/cycles.md, docs/cycles/, .github/pull_request_template.md
4. 如果您看到“缺少文件”错误，请运行 init-workflow 建立完整的结构
5. 验证您是否在正确的目录中
6. 检查文件权限

公关创建失败

MCP服务器尝试使用GitHub CLI(gh)创建PR。如果未安装：

1. 安装GitHub命令行界面： brew install gh
2. 身份验证： gh auth login
3. 或者使用提供的模板手动创建PR

哲学

此MCP服务器基于 爱它或恨它 哲学：

• 无需定制 -模板是固定的，以保持一致性
• 意见化工作流程 -一种做事的方法，做得好
• 自动跟踪 -进度自动更新
• AI优先 -专为自然语言交互而设计

如果你需要定制，分叉和修改。否则，拥抱这种结构，享受生产力的提升！

许可证

麻省理工学院

贡献

问题和PR欢迎！这是一个爱好项目，但保持积极。

学分

创建用于管理跨多个存储库的开发周期。灵感来自敏捷冲刺，但针对单人开发人员和小团队进行了优化。