MCP Agile Flow

一个综合系统，用于使用 FastMCP 管理 AI 辅助的敏捷开发工作流程，并提供现代的、基于资源的 API。

状态

✅ 迁移完成: 从旧服务器到 FastMCP 实现的迁移已完全完成。所有旧代码和测试都已删除。

概述

MCP Agile Flow 项目使用来自官方 MCP SDK 的基于资源的方法和 FastMCP，重点关注：

• RESTful API 设计 - 干净、直观的资源 URI 用于数据访问
• 资源优先架构 - 针对数据检索和状态表示进行优化
• 面向行动的工具 - 仅用于修改状态的操作的工具

主要特性

• 敏捷文档: 生成和维护全面的 AI 文档
• 项目结构: 使用 AI 生成的文件和目录组织您的项目
• IDE 集成: 与各种 AI IDE（Cursor、Windsurf、Cline）直接集成
• 工作流程管理: 跟踪敏捷故事和进度
• 直观的 API 结构: 以 RESTful 层次结构组织的资源
• 简化集成: 直接映射到资源 URI
• 改进的性能: 针对数据访问模式进行优化

开始使用

要使用 MCP Agile Flow：

1. 安装软件包：

   pip install mcp-agile-flow
   

2. 在您的代码中导入：

   from mcp_agile_flow import call_tool, call_tool_sync
   
   # 使用异步接口
   result = await call_tool("get-project-settings", {})
   
   # 或使用同步接口
   result = call_tool_sync("get-project-settings", {})
   

MCP 客户端配置

重要提示：需要更新配置

如果您之前配置过 MCP Agile Flow，则需要更新您的配置。fastmcp_server.py 模块已作为代码清理的一部分被删除，并且功能已合并到主包中。

将您的 MCP 客户端配置从：

{
    "name": "mcp-agile-flow",
    "server": {
        "type": "module",
        "module": "mcp_agile_flow.fastmcp_server",
        "entry_point": "run"
    }
}

更新为：

{
    "name": "mcp-agile-flow",
    "server": {
        "type": "module",
        "module": "mcp_agile_flow",
        "entry_point": "main"
    }
}

对于 Cursor 用户，还要更新 mcp.json 文件（通常位于 ~/.cursor/mcp.json）：

"mcp-agile-flow": {
  "command": "/path/to/python",
  "args": [
    "-m",
    "mcp_agile_flow"  // 从 "mcp_agile_flow.fastmcp_server" 更新
  ],
  "autoApprove": [
    // ...
  ]
}

命令行用法

您也可以直接从命令行运行服务器：

# 使用 Python（默认禁用日志记录）
python -m mcp_agile_flow

# 启用普通日志记录
python -m mcp_agile_flow --verbose

# 调试模式（最详细的日志记录）
python -m mcp_agile_flow --debug

可用工具

MCP Agile Flow 提供了几个工具：

• get-project-settings: 获取项目设置，包括路径和环境变量
• initialize-ide: 初始化特定 IDE 的项目目录结构
• initialize-ide-rules: 初始化特定 IDE 的 AI 规则文件
• prime-context: 分析项目文档并构建上下文理解
• migrate-mcp-config: 在不同的 IDE 之间迁移 MCP 配置
• think: 记录一个想法，用于复杂的推理和逐步分析
• get-thoughts: 检索当前会话中记录的所有想法
• clear-thoughts: 清除当前会话中记录的所有想法
• get-thought-stats: 获取有关当前会话中记录的想法的统计信息
• process-natural-language: 处理自然语言命令并路由到适当的工具

自然语言命令

MCP Agile Flow 支持自然语言命令，使您可以更轻松地与工具交互，而无需记住确切的命令名称。只需使用会话短语，系统就会自动检测您的意图，并将它们映射到具有正确参数的适当工具。

支持的命令类型

迁移命令

要在不同的 IDE 之间迁移 MCP 配置：

• "migrate mcp config to claude-desktop"
• "migrate config from cursor to claude-desktop"
• "copy mcp settings to windsurf"
• "transfer config to cline"
• "move mcp settings from cursor to roo"

如果未指定源 IDE，则默认为 "cursor"。

注意: 有效的 IDE 名称为："cursor"、"windsurf-next"、"windsurf"、"cline"、"roo" 和 "claude-desktop"。

初始化命令

要使用特定 IDE 的规则初始化项目：

• "initialize ide for claude"
• "setup rules for windsurf"
• "create ide for cline"
• "initialize rules for copilot"

项目设置命令

要获取全面的项目设置：

• "get project settings"
• "show settings"
• "project settings"

上下文分析命令

要分析项目文档：

• "prime context"
• "analyze project context"
• "build context"

思考命令

要记录一个想法：

• "think about [your thought here]"

用法示例

以下是一些如何使用这些命令的示例：

from mcp_agile_flow import process_natural_language

# 将配置从 Cursor 迁移到 Claude
result = process_natural_language("migrate mcp config to claude-desktop")

# 初始化 Windsurf 的规则
result = process_natural_language("initialize ide for windsurf")

# 获取项目设置
result = process_natural_language("get project settings")

# 启动上下文
result = process_natural_language("prime context")

# 记录一个想法
result = process_natural_language("think about how to improve code quality")

从命令行使用

您还可以将自然语言命令与 MCP Agile Flow CLI 一起使用：

python -m mcp_agile_flow process-natural-language "migrate mcp config to claude-desktop"

错误处理

如果系统无法识别命令，它将返回一条错误消息，解释说未检测到任何命令，并建议使用更具体的措辞。

扩展命令

自然语言命令检测在 utils.py 中使用正则表达式实现。要添加对新命令模式的支持，请将适当的正则表达式模式添加到 detect_mcp_command 函数。

开发

要设置开发环境：

1. 克隆存储库：

   git clone https://github.com/yourusername/mcp-agile-flow.git
   cd mcp-agile-flow
   

2. 创建一个虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   

3. 安装开发依赖项：

   pip install -e ".[dev]"
   

4. 运行测试：

   pytest
   

5. 常用 Makefile 命令：

   make test             # 运行所有测试
   make test-nl-commands # 测试自然语言命令功能
   make test-core        # 仅运行核心测试
   make coverage         # 生成覆盖率报告
   make clean            # 清理构建工件
   make clean-all        # 清理所有内容，包括 venv
   make clean-archived   # 删除已存档的旧文件
   

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参见 LICENSE 文件。