Agile Planner MCP Server (v1.3.3) - AI-Powered Agile Backlog Generator

Agile Planner MCP 服务（v1.7.3）- AI 驱动的敏捷待办事项生成器

Agile Planner MCP 可根据简单描述自动生成完整的敏捷待办事项（史诗、用户故事、MVP、迭代）或特定功能，并可直接在 Windsurf、Cascade 或 Cursor 中使用，无需任何技术技能。

最新改进（v1.7.3）：

• 修复 generateFeature 的 MCP 模式：改进用户故事提取的稳健性
• 强化 RULE 3 结构：一致地创建 epics/features/user-stories 文件夹
• 解决 Windows 上的 Notepad 问题：在 MCP 模式下规范化 stderr/stdout 流
• 详细诊断日志：更轻松地识别问题
• 项目重组：清晰地整理测试文件和临时文件
• 更新使用指南：提供 Windsurf、Claude 和 Cursor 的完整说明
• 完整详情请参阅 CHANGELOG.md。

此前的改进（v1.7.1）：

• 全面重制 MCP 文档：通过 Mermaid 图表详细介绍 MCP 服务端架构。
• 降低认知复杂度：对关键模块（json-parser、mcp-router）进行重大重构。
• 增强稳健性：改进错误处理并优化 E2E 集成测试。
• 详情请参阅 CHANGELOG.md。

❌ 不使用 Agile Planner MCP

手动创建敏捷待办事项既耗时又容易出错：

• ❌ 花费数小时编写用户故事、验收标准和任务
• ❌ 不同项目之间的格式和结构不一致
• ❌ 没有为 AI 编码助手提供明确的实施指导
• ❌ 缺乏战略框架，需手动确定优先级并进行组织

✅ 使用 Agile Planner MCP

集中式错误处理

• generateBacklog 和 generateBacklogDirect 函数的所有错误返回现在都会通过 handleBacklogError 格式化，以确保 JSON 格式统一并提高审计的健壮性。
• 错误示例显示的格式为：{ success: false, error: { message: ... } }

Agile Planner MCP 可在数秒内生成完整、结构化的敏捷待办列表，并附带精准的 AI 引导注释：

• ✅ 完整的待办列表结构，包含史诗、功能、用户故事和独立故事
• ✅ AI 优化注释，逐步指导实施
• ✅ 进度跟踪，包含任务复选框和依赖项管理
• ✅ 集中组织在专用的 .agile-planner-backlog 文件夹中
• ✅ 智能功能组织，自动将功能关联到相关史诗

📑 文档

本文档已重新整理，以便更轻松地查阅：

用户指南

• MCP 集成指南 - Claude、Cursor 和 Windsurf IDE 集成指南
• 最佳使用指南 - 详细使用指南
• 迁移指南 - 从早期版本迁移的指南

开发者文档

• 开发 - 开发指南
• MCP 规范 - MCP 协议规范
• 已知问题 - 已知问题和技术债务清单
• 重构计划 - 详细的代码重构计划
• 测试重构计划 - 测试修复计划
• 路线图 - 未来版本路线图
• MCP 架构 - MCP 服务的完整架构
• Markdown 生成系统 - Markdown 生成器架构
• 待办列表格式 - 待办列表 JSON 格式规范

辅助函数

• createApiMessages(project) - 为 AI 生成一对系统/用户消息。参数 project 可以是 "名称: 描述" 形式的字符串，也可以是 { name, description } 对象。

TDD 注意事项：错误断言必须检查统一格式 { success: false, error: { message: ... } }。 任何错误格式变更都需要更新集成测试。

架构文档

• 设计 - 项目总体设计
• 待办列表格式 - 生成的待办列表格式
• 待办列表验证图 - 验证流程图
• 多 LLM 兼容性 - 与多个 LLM 的兼容性

🚦 在 Windsurf / Cascade / Cursor 中设置

请管理员或技术团队将此 MCP 服务添加到你的工作区配置中：

1. 将 .env.example 复制为 .env，并填写你的 OPENAI_API_KEY 或 GROQ_API_KEY。

选项 1：使用本地安装

{
  "mcpServers": {
    "agile-planner": {
      "command": "node",
      "args": ["D:/path/to/agile-planner/server/index.js"],
      "env": {
        "MCP_EXECUTION": "true",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

选项 2：使用 NPM 包

{
  "mcpServers": {
    "agile-planner": {
      "command": "npx",
      "args": ["agile-planner-mcp-server"],
      "env": {
        "MCP_EXECUTION": "true",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

🧠 工作原理

1. 用通俗的英语描述你的项目，尽可能提供详细信息。

   SaaS task management system for teams with Slack integration, 
   mobile support, and GDPR compliance.
   

2. Agile Planner MCP 会通过稳健的验证流程处理你的描述：

   • 🤖 利用 OpenAI 或 Groq 大模型生成待办事项结构
   • 🧪 根据全面的 JSON schema 验证结构
   • 🔍 为功能补充验收标准和任务
   • 📝 将用户故事整理到史诗和功能中
   • 🏗️ 创建包含 Markdown 文件的完整目录结构

3. 几秒钟内即可获得结构完整的敏捷待办事项清单：

生成的文件夹结构

.agile-planner-backlog/
├── epics/
│   └── [epic-slug]/
│       ├── epic.md
│       └── features/
│           └── [feature-slug]/
│               ├── feature.md
│               └── user-stories/
│                   ├── [story-1].md
│                   └── [story-2].md
├── orphan-stories/
│   ├── [story-orpheline-1].md
│   └── [story-orpheline-2].md
└── backlog.json

注意： planning/mvp 和 planning/iterations 文件夹已删除。所有用户故事都会生成在对应的史诗/功能目录中；如果没有关联到任何功能或史诗，则会生成在 orphan-stories 中。backlog.json 文件不再包含 mvp 或 iterations 部分。

所有文件都包含便于 AI 理解的说明，以指导实施。示例输出请参阅 示例 文件夹。

命令

Agile Planner MCP 支持以下命令：

生成完整的待办事项清单

// In Windsurf or Cascade
mcp0_generateBacklog({
  projectName: "My Project",
  projectDescription: "A detailed description of the project...",
  outputPath: "optional/custom/path"
})

// CLI
npx agile-planner-mcp-server backlog "My Project" "A detailed description of the project..."

生成特定功能

// In Windsurf or Cascade
mcp0_generateFeature({
  featureDescription: "A detailed description of the feature to generate",
  storyCount: 3,  // Optional: number of user stories to generate (min: 3)
  businessValue: "High", // Optional: business value of this feature
  iterationName: "iteration-2", // Optional: target iteration (default: 'next')
  epicName: "Optional Epic Name", // Optional: specify an epic or let the system find/create one
  outputPath: "optional/custom/path" // Optional: custom output directory
})

// CLI
npx agile-planner-mcp-server feature "A detailed description of the feature to generate"

🔄 环境变量

变量	描述	默认值
MCP_EXECUTION	必需 - 必须设为 "true" 才能使用 MCP 模式	-
OPENAI_API_KEY	用于生成待办事项清单的 OpenAI API 密钥	-
GROQ_API_KEY	备用 Groq API 密钥	-
DEBUG	启用调试模式以输出更多日志	false
TEST_MODE	启用测试模式（模拟生成）	false
AGILE_PLANNER_OUTPUT_ROOT	输出的基础目录	当前目录

📜 许可证

Agile Planner MCP Server 根据 MIT License with Commons Clause 授权。完整许可证文本请参阅 LICENSE 文件。

👥 支持

如需帮助，请在 GitHub 仓库中提交 issue，或联系你的 Windsurf/Cascade/Cursor 管理员。

---

☕️ 支持本项目

如果你觉得这个项目有用，可以通过在 BuyMeACoffee 上请我喝杯咖啡来支持项目开发！

🚀 获取 Windsurf

谢谢 🙏