Alice MCP - Agile Task Management

Alice MCP - 轻量级敏捷任务管理

Alice 是一款轻量级的本地任务管理系统，专为使用 Model Context Protocol（MCP）的 AI 编码环境设计。它提供全面的项目管理能力，包括批量操作、动态规划和架构决策跟踪；所有数据都在本地运行，并实现完整的项目隔离。

Alice 针对 Cline 和其他 AI 编码助手进行了优化，通过智能自动化和全面跟踪，改变开发工作流的管理方式。

如需详细指南，请参阅文档部分；如需立即开始设置，请参阅Cline 用户快速入门。

主要功能

🚀 高效的批量操作

• 批量任务管理： 同时创建和更新多个任务
• 批量决策记录： 批量处理架构决策，并支持丰富的 Markdown 格式
• 原子操作： 要么全部处理，要么全部不处理，并提供全面的错误报告

📊 智能项目管理

• 项目隔离： 所有数据均限定在特定项目范围内，安全分隔
• 动态项目规划： 可供 AI 查询的优先级待办事项列表，并会根据进度动态调整
• 任务与 Epic 跟踪： 采用层级组织方式，并跟踪状态历史
• 消息记录： 与特定任务关联的上下文备注和讨论

🏗️ 架构决策记录（ADR）

• 结构化决策跟踪： 记录背景、决策和后果
• 丰富的 Markdown 内容： 全面支持复杂技术文档的格式
• 任务集成： 将决策关联到促使其产生的任务
• 可查询的历史记录： 在各个开发周期中维护组织知识

🔧 开发者体验

• 针对 Cline 优化： 无缝集成，并自动管理服务
• 本地优先： 使用 SQLite 完全在本机运行，无外部依赖
• 原生支持 MCP： 专为 Model Context Protocol 环境构建
• 全面测试： 62 项测试，确保可靠性和稳定性

Cline 用户快速入门

让 Alice 与 Cline 一起运行的最快方式：

1. 克隆并设置：

   git clone https://github.com/your-organization/alice-mcp.git
   cd alice-mcp
   python -m venv alice-env
   source alice-env/bin/activate  # On Windows: alice-env\Scripts\activate
   pip install -r requirements.txt
   

2. 自动设置 MCP：

   ./scripts/setup-alice-mcp.sh
   

   这条命令即可完成所有操作：创建 MCP 服务、安装依赖项、构建 TypeScript，并更新 Cline 设置。

3. 重启 Cline，然后使用以下内容进行测试：

   Use alice to create a project named "test-project"
   

就是这样！Alice 现已集成到 Cline 中，可用于高效的项目管理。

高级设置

如需手动设置或自定义：

1. 克隆仓库：

   git clone https://github.com/your-organization/alice-mcp.git
   cd alice-mcp
   

2. 创建并激活 Python 虚拟环境：

   # 创建环境
   python -m venv alice-env
   
   # 激活环境（Linux/macOS）
   source alice-env/bin/activate
   
   # 激活环境（Windows）
   # alice-env\Scripts\activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

如需详细的手动设置说明，请参阅 LLM 安装指南。

运行服务

自动启动（MCP 集成）

在兼容 MCP 的环境中使用时，Alice 会自动启动——FastAPI 后端和 MCP 服务组件会一同启动。此过程由 scripts/start-alice-servers.sh 包装脚本处理，该脚本会：

• 激活 Python 环境
• 安装依赖项
• 启动 FastAPI 服务
• 启动 MCP 服务

手动启动（开发）

如果需要手动运行服务（用于开发或测试），可以：

1. 启动 FastAPI 服务：

   uvicorn app.main:app --reload
   

   服务将在 http://127.0.0.1:8000 上提供

2. 如需调试问题，可以直接运行包装脚本：

   /bin/zsh scripts/start-alice-servers.sh --debug
   

入门指南

1. 启动服务（见上文）。
2. 创建项目： 向 /projects/ 发送 POST 请求，并提供唯一的项目名称。

   { "name": "my-new-project" }
   

3. 标识项目： 通过 Alice MCP 服务工具与任务、史诗和消息交互时，请将项目的名称（例如，“my-new-project”）用作 project_id 参数。MCP 服务会将其转换为 API 所需的内部数字 ID。
4. API 端点（直接使用 API）： 如果直接与 FastAPI 后端交互（而非通过 MCP 服务），后续所有任务、史诗和消息操作都需要在 URL 路径中使用内部数字 project_id（例如，/{numeric_project_id}/tasks/）。你可以通过列出项目（GET /projects/）或按名称获取项目（GET /projects/by-name/my-new-project）来查找此数字 ID。

项目隔离 API 结构

Alice 的 FastAPI 后端在 URL 路径中使用数字项目 ID，以确保数据隔离。但是，使用 Alice MCP 服务工具时，应将项目的**名称（字符串）**作为 project_id 参数提供。MCP 服务会将其解析为 API 所需的正确数字 ID。

直接调用 API 的示例：

• 项目管理： /projects/（例如，POST /projects/、GET /projects/{project_id}）
• 任务： /{numeric_project_id}/tasks/（例如，POST /1/tasks/、GET /1/tasks/{task_id}）
• 史诗： /{numeric_project_id}/epics/（例如，POST /1/epics/、GET /1/epics/{epic_id}）
• 消息： /{numeric_project_id}/tasks/{task_id}/messages/（例如，POST /1/tasks/5/messages/）

直接使用 API 时，请将 1 替换为实际的内部数字 project_id。

强大的新功能

Alice 新增了强大的功能，可改进你的开发工作流，确保不同编码会话之间不会丢失上下文和优先级信息。

动态项目规划

厌倦了静态文档中的项目计划逐渐过时？Alice 推出了可动态查询的项目计划。

• 创建优先级待办列表： 使用 update_priority_plan 工具设置任务的确切处理顺序。你可以为每项任务的优先级提供理由，为未来的自己或其他 Agent 补充必要的上下文。
• 随时掌握下一步工作： get_next_task 工具会立即返回优先级最高且尚未标记为“Done”或“Canceled”的任务。这消除了模糊之处，并确保始终聚焦于最重要的工作。
• 实时状态更新： 项目计划始终保持最新。任务完成后，计划会自动更新其状态，实时展示进度。

架构决策记录（ADR）

通过结构化且可查询的架构决策日志，记录项目设计背后的“原因”。

• 记录关键决策： 使用 create_decision 工具记录重要架构选择的背景、决策和影响。
• 保留上下文： 新的开发线程可以通过回顾过往决策快速了解情况，避免反复讨论已确定的问题，并确保长期保持一致。
• 关联任务： 将决策与促使其产生的具体任务关联起来，为项目演进创建清晰的审计记录。

这些功能让 Alice 从简单的任务跟踪器转变为能够主动管理项目上下文和优先级的智能伙伴，让你的开发流程更高效、更透明、更强大。

批量操作——提升效率

Alice 的批量操作可提高开发项目管理效率：

批量任务操作：

• bulk_create_tasks： 通过单次操作创建多个任务，并进行全面验证
• bulk_update_tasks： 同时更新多个任务，并保证事务的原子性

批量决策操作：

• bulk_create_decisions： 批量处理架构决策，并支持丰富的 Markdown 格式
• bulk_update_decisions： 更新多条记录中的决策状态和内容

性能优势：

• 与单独操作相比，大幅减少 API 调用
• 原子事务和回滚保护确保数据一致性
• 详细报告会显示每项的成功或失败状态

使用示例：

// Create 5 tasks simultaneously
bulk_create_tasks("my-project", [
  { title: "Setup authentication", assignee: "Backend Team" },
  { title: "Design user interface", assignee: "Frontend Team" },
  { title: "Configure CI/CD pipeline", assignee: "DevOps Team" },
  { title: "Write API documentation", assignee: "Documentation Team" },
  { title: "Implement rate limiting", status: "In Progress" }
])

// Update multiple tasks with status changes
bulk_update_tasks("my-project", [
  { id: 1, update: { status: "Done" }},
  { id: 2, update: { status: "In Progress", assignee: "New Team" }},
  { id: 3, update: { description: "Updated requirements" }}
])

运行测试

确保已激活虚拟环境并安装依赖项。然后运行：

pytest

API 文档

服务运行期间，你可以在浏览器中访问交互式 API 文档（由 FastAPI 提供）：

• Swagger UI： http://127.0.0.1:8000/docs
• ReDoc： http://127.0.0.1:8000/redoc

文档

详细文档可在 docs/ 目录中找到：

• 应用概览： 介绍架构、功能和技术栈。
• 技术要求： 详细的系统、数据库和 API 规范。
• 大模型集成指南： 关于使用大模型自定义指令集成 Alice 的建议。

贡献

欢迎贡献！请遵循以下指南：

• 遵守代码风格（PEP 8、black、isort）。
• 使用类型提示。
• 为公开函数和 API 编写文档。
• 为新功能或 Bug 修复编写单元测试。
• 提交更改前，确保所有测试和代码检查均通过。
• 对于重大更改，可以先提交 Issue 讨论方案。

---

Alice 已通过 MCP Review 认证。请在此处查看其列表：https://mcpreview.com/mcp-servers/soapko/alice-mcp-server