项目介绍
【技术文档摘要】
MCP任务编排器
一个模型上下文协议服务器，通过自动记录每个决策、实现和测试来改变您与AI的工作方式。可以将其视为AI辅助开发的记忆层，确保不会丢失任何上下文。
概述
MCP任务编排器提供智能任务编排、专门的AI角色以及持久记忆功能，适用于AI辅助开发。基于清洁架构原则构建，能够自动检测项目结构并适当保存工件。
文档类型：项目概述及用户指南
目标受众：使用MCP客户端（如Claude桌面版、Cursor、VS Code等）的开发者
前提条件：Python 3.8+，兼容MCP的客户端
最后更新日期：2025-01-13
主要特性
- 文档自动化：每个任务都会生成全面且可搜索的工件
- 专业AI角色：架构师、实施者、测试员、审查员、文档编写员等
- 持久记忆：永不丢失上下文——所有决策和实现都被保留
- 工作区感知：自动检测项目结构并适当保存工件
- 模板系统：13种工具用于创建可重用的任务模板
- 清洁架构：采用现代软件设计原则构建
- 通用MCP兼容性：支持Claude桌面版、Cursor、Windsurf、VS Code及其扩展
快速开始
前提条件
- Python 3.8+
- 一个或多个MCP客户端（如Claude桌面版、Cursor IDE、Windsurf或带有扩展的VS Code）
安装
- 安装：
pip install mcp-task-orchestrator - 配置：添加到您的MCP客户端配置中
- 使用："初始化任务编排会话并帮助我构建REST API"
验证
在您的MCP客户端中尝试以下命令：
"初始化新的编排会话并计划处理CSV文件的Python脚本"
查看详细的设置说明，请参阅快速开始指南。
工作原理
替代单体响应：
用户："构建一个用于新闻文章的Python网络爬虫"
Claude：[提供一个包含少量代码的基本响应]
您得到的是结构化的专业工作流程：
用户："构建一个用于新闻文章的Python网络爬虫"
步骤1：架构师角色
├── 包含速率限制和错误处理的系统设计
├── 技术选择（requests vs scrapy）
├── 数据结构规划
└── 可扩展性考虑
步骤2：实施者角色
├── 核心爬取逻辑实现
├── 错误处理和重试
├── 数据解析和清理
└── 配置管理
步骤3：测试员角色
├── 核心函数单元测试
├── 与实时站点集成测试
├── 错误条件测试
└── 性能验证
步骤4：文档编写员角色
├── 使用文档
├── API参考
├── 配置指南
└── 故障排除指南
结果：完整的实现包括：
✓ 错误处理模式 ✓ 测试覆盖率 ✓ 文档 ✓ 最佳实践
每个步骤都提供了专业上下文和专业知识，而不是通用响应。
核心功能
- 基于LLM的任务分解：自动将复杂项目分解成逻辑子任务
- 专业AI角色：具有领域特定专业知识的架构师、实施者、调试员、文档编写员
- 自动化维护：内置清理、优化和健康监控
- 任务持久化：SQLite数据库，自动恢复和归档
- 工件管理：通过智能文件存储防止上下文限制
- 工作区智能：自动检测Git仓库、项目文件，并适当保存工件
- 可定制角色：编辑
.task_orchestrator/roles/project_roles.yaml以适应项目的角色 - 单会话完成：在一个对话中完成复杂项目
- 智能工件放置：文件保存在项目根目录下，而非随机位置
安装
通用安装程序（推荐）
通用安装程序为所有主要MCP客户端提供全面支持，并具有灵活的安装选项。
快速安装 - 自动检测所有客户端：
# 下载并运行通用安装程序
git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
python install.py
# 自动检测并配置所有兼容的MCP客户端
# 重启您的MCP客户端 - 编排器工具将自动可用
从PyPI安装并手动配置：
# 从PyPI安装
pip install mcp-task-orchestrator
# 然后手动配置您的MCP客户端（见下文配置部分）
安装到特定客户端：
# 配置特定客户端
python install.py --clients claude,cursor
# 跳过MCP配置（手动设置）
python install.py --no-clients
# 开发安装，包含所有工具
python install.py --dev
# 在用户目录中安装
python install.py --user
高级安装选项：
# 即使在开发环境中也强制使用PyPI安装
python install.py --source pypi
# 安装特定版本
python install.py --version 2.0.0
# 从git仓库安装
python install.py --git https://github.com/EchoingVesper/mcp-task-orchestrator.git
# 在自定义虚拟环境中安装
python install.py --venv /path/to/venv
# 强制覆盖现有安装
python install.py --force
针对外部管理环境（WSL，Ubuntu 23.04+）：
# 先创建虚拟环境
python -m venv mcp-orchestrator-env
source mcp-orchestrator-env/bin/activate # Linux/WSL/macOS
# 或：mcp-orchestrator-env\Scripts\activate # Windows
# 克隆并安装
git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
python install.py --venv ../mcp-orchestrator-env
使用pipx的替代方法：
# 通过pipx进行隔离安装
pipx install mcp-task-orchestrator
# 手动MCP配置需要（见配置部分）
安装功能
- ✅ 零漏洞：解决了所有38个安全问题
- ✅ 跨平台：支持Windows、macOS、Linux
- ✅ 多客户端：Claude桌面版、Cursor、Windsurf、VS Code、Zed、Claude Code
- ✅ 自动备份：配置保护和回滚
- ✅ 性能：<5秒安装时间，<50MB内存使用
- ✅ 验证：全面的安装后验证
支持的MCP客户端
| 客户端 | 自动检测 | 安装方法 | 多项目支持 | 状态 |
|---|---|---|---|---|
| Claude桌面版 | ✅ | JSON配置 | ✅ 动态检测 | 完全支持 |
| Claude Code | ✅ | CLI集成 | ✅ 按项目安装 | 完全支持 |
| Windsurf | ✅ | JSON配置 | ✅ 内置项目上下文 | 完全支持 |
| Cursor | ✅ | JSON配置 | ✅ 内置项目上下文 | 完全支持 |
| VS Code | ⚠️ | 扩展+配置 | ⚠️ | 进行中 |
| Continue.dev | ⚠️ | JSON配置 | ⚠️ | 进行中 |
| Cline | ⚠️ | JSON配置 | ⚠️ | 进行中 |
安装故障排查
快速诊断：
# 查看安装帮助和选项
python install.py --help
# 检查安装状态
python install.py --status
# 如果已安装，强制重新配置
python install.py --force
# 测试干运行模式，查看将执行的操作
python install.py --dry-run --verbose
常见问题：
- Claude Code未被检测到：确保已安装Claude Code CLI，并且
claude --version可以正常工作 - 配置文件未找到：确保已安装MCP客户端并且至少运行了一次
- 权限错误：检查配置目录的文件权限
- 已经配置：使用
--force标志覆盖现有配置
客户端特定说明：
- Claude桌面版：使用动态检测在全球范围内跨多个项目工作
- Claude Code：自动按项目检测，以获得最佳体验
- Windsurf/Cursor：在打开项目文件夹时自动检测项目上下文
对于全面的故障排查，请参阅安装故障排查指南。
验证
在您的MCP客户端中尝试以下命令：
"初始化新的编排会话并计划处理CSV文件的Python脚本"
工作流过程
编排器遵循一个五步系统过程：
- 工作区检测 - 自动识别您的项目类型和根目录
- 任务分析 - LLM分析您的请求并创建结构化的子任务
- 任务规划 - 组织子任务，评估依赖关系和复杂度
- 专业执行 - 每个子任务都在角色特定的上下文中运行
- 结果综合 - 将输出组合成一个全面的解决方案，并根据工作区意识放置工件
可用工具
核心编排工具，用于任务管理和执行：
| 工具 | 目的 | 参数 |
|---|---|---|
orchestrator_initialize_session | 启动新工作流 | working_directory（可选） |
orchestrator_plan_task | 创建任务分解 | 必需 |
orchestrator_execute_task | 使用专业上下文执行 | 必需 |
orchestrator_complete_task | 使用工件标记任务完成 | 必需 |
orchestrator_synthesize_results | 结合结果 | 必需 |
orchestrator_get_status | 检查进度 | 可选 |
orchestrator_maintenance_coordinator | 自动清理和优化 | 必需 |
维护与自动化功能
编排器包括智能维护能力：
- 自动清理：检测并归档过期任务（>24小时）
- 性能优化：防止数据库膨胀并保持响应性
- 结构验证：确保任务层次结构的一致性
- 交接准备：简化上下文转换和项目交接
- 健康监控：提供系统状态和优化建议
快速维护："使用维护协调器扫描并清理当前会话"
详细指导，请参阅Maintenance Coordinator Guide。
支持的环境
| 客户端 | 描述 | 状态 |
|---|---|---|
| Claude桌面版 | Anthropic的桌面应用程序 | ✅ 支持 |
| Cursor IDE | AI驱动的代码编辑器 | ✅ 支持 |
| Windsurf | Codeium的开发环境 | ✅ 支持 |
| VS Code | 带有Cline扩展 | ✅ 支持 |
配置与定制
通用安装程序自动处理所有MCP客户端配置，采用零漏洞设计。对于高级配置选项，请参阅安装指南和配置参考。
自定义专业角色
通过编辑.task_orchestrator/roles/project_roles.yaml创建项目特定的专业人员：
security_auditor:
role_definition: "您是安全分析专家"
expertise:
- "OWASP安全标准"
- "渗透测试方法"
- "安全编码实践"
approach:
- "专注于安全影响"
- "识别潜在漏洞"
- "确保符合安全标准"
当您在任何目录中启动新的编排会话时，该文件将自动创建。
常见用例
软件开发：全栈Web应用、API开发带测试、数据库模式设计、DevOps流水线设置
数据科学：机器学习流水线、数据分析工作流、研究项目规划、模型部署策略
文档与内容：技术文档、代码审查与重构、测试策略开发、内容创作工作流
故障排查
常见问题
“未检测到MCP客户端” - 确保已安装至少一个受支持的客户端，并在安装前至少运行一次
“配置失败” - 检查文件权限，尝试以管理员/sudo身份运行安装程序
“模块未找到错误” - 尝试在新鲜的虚拟环境中重新安装：
python -m venv fresh_env && source fresh_env/bin/activate && pip install mcp-task-orchestrator
诊断工具
# 系统健康检查
python scripts/diagnostics/check_status.py
# 数据库优化
python scripts/diagnostics/diagnose_db.py
# 安装验证
python scripts/diagnostics/verify_tools.py
测试与开发
增强的测试基础设施
MCP任务编排器包括强大的测试改进，消除了常见问题：
- ✅ 无输出截断：基于文件的输出系统防止测试输出截断
- ✅ 无资源警告：适当的数据库连接管理消除资源警告
- ✅ 无测试挂起：全面的挂起检测和超时机制
- ✅ 替代测试运行器：绕过pytest限制的专用运行器
快速测试命令
# 激活您的虚拟环境（如果使用的话）
source your_venv/bin/activate # Linux/Mac
your_venv\Scripts\activate # Windows
# 运行增强的测试套件
python tests/test_resource_cleanup.py # 验证资源管理
python tests/test_hang_detection.py # 测试挂起预防系统
python tests/enhanced_migration_test.py # 运行带有完整输出的迁移测试
# 展示改进的测试功能
python tests/demo_file_output_system.py # 展示基于文件的输出系统
python tests/demo_alternative_runners.py # 展示替代测试运行器
# 传统的pytest（仍然支持）
python -m pytest tests/ -v
测试最佳实践
为了可靠地执行测试，请使用新的测试基础设施：
# 基于文件的输出（防止截断）
from mcp_task_orchestrator.testing import TestOutputWriter
writer = TestOutputWriter(output_dir)
with writer.write_test_output("my_test", "text") as session:
session.write_line("测试输出在这里...")
# 替代测试运行器（比pytest更可靠）
from mcp_task_orchestrator.testing import DirectFunctionRunner
runner = DirectFunctionRunner(output_dir=Path("outputs"))
result = runner.execute_test(my_test_function, "test_name")
# 数据库连接（防止资源警告）
from tests.utils.db_test_utils import managed_sqlite_connection
with managed_sqlite_connection("test.db") as conn:
# 具有保证清理的数据库操作
pass
📖 文档：
请参阅CONTRIBUTING.md了解贡献指南，以及docs/获取完整文档。
重要免责声明
本软件“按原样”提供，不附带任何形式的担保。 它旨在用于开发和实验目的。作者不对其适合生产、关键系统或任何特定用途做出声明。
自行承担风险使用。 作者对使用此软件造成的任何损害或损失概不负责，包括但不限于数据丢失、系统故障或业务中断。
开发工具通知。 这是一个开发工具，在任何生产使用之前应彻底测试和验证。
许可证与资源
本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。
链接
版权所有 © 22025 Echoing Vesper