MCP Task Orchestrator

MCP任务编排器

一个模型上下文协议服务器，通过在构建过程中自动记录每个决策、实现和测试，改变您使用人工智能的方式。将其视为人工智能辅助开发的存储层，确保不会丢失任何上下文。

概述

MCP任务编排器为人工智能辅助开发提供智能任务编排、专门的人工智能角色和持久内存。它基于清洁架构原则构建，可以自动检测项目结构并适当保存工件。

文档类型：项目概述和用户指南\ 目标受众：使用MCP客户端的开发人员（Claude Desktop、Cursor、VS Code等）\ 先决条件：Python 3.8+，MCP兼容客户端\ 最后更新: 2025-01-13

主要特点

• 文档自动化：每个任务都会生成全面、可搜索的工件
• 专业AI角色：架构师、实施者、测试者、审阅者、文档编制者等
• 持久存储器：永远不要失去上下文-所有决策和实施都会被保留
• 工作空间意识：自动检测项目结构并适当保存工件
• 模板系统：13个用于创建可重用任务模板的工具
• 清洁建筑：采用现代软件设计原则构建
• 通用MCP兼容性：适用于Claude Desktop、Cursor、Windsurf、VS Code+扩展

快速开始

先决条件

• Python 3.8+
• 一个或多个MCP客户端（Claude Desktop、Cursor IDE、Windsurf或带扩展的VS Code）

安装

1. 安装: pip install mcp-task-orchestrator
2. 配置：添加到MCP客户端配置
3. 使用：“初始化任务编排器会话并帮助我构建REST API”

验证

在您的MCP客户端中尝试以下操作：

"Initialize a new orchestration session and plan a Python script for processing CSV files"

请参阅 快速入门指南 有关详细的设置说明。

运作原理

而不是单一的回应：

User: "Build a Python web scraper for news articles"
Claude: [Provides a single, basic response with minimal code]

您将获得结构化的专业工作流程：

User: "Build a Python web scraper for news articles"

Step 1: Architect Role
├── System design with rate limiting and error handling
├── Technology selection (requests vs scrapy)
├── Data structure planning  
└── Scalability considerations

Step 2: Implementer Role
├── Core scraping logic implementation
├── Error handling and retries
├── Data parsing and cleaning
└── Configuration management

Step 3: Tester Role
├── Unit tests for core functions
├── Integration tests with live sites
├── Error condition testing
└── Performance validation

Step 4: Documenter Role
├── Usage documentation
├── API reference
├── Configuration guide
└── Troubleshooting guide

Result: Complete implementation with:
✓ Error handling patterns ✓ Test coverage ✓ Documentation ✓ Best practices

每一步都提供了专业背景和专业知识，而不是通用的回应。

核心功能

• LLM驱动的任务分解：自动将复杂项目分解为逻辑子任务
• 专业AI角色：具有特定领域专业知识的架构师、实施者、调试器、文档编制者
• 自动维护：内置清理、优化和运行状况监控
• 任务持久性：具有自动恢复和归档功能的SQLite数据库
• 工件管理：通过智能文件存储防止上下文限制
• 工作空间智能：自动检测Git存储库、项目文件，并适当保存工件
• 可定制的角色：编辑 .task_orchestrator/roles/project_roles.yaml 为您的项目调整角色
• 单次会话完成：在一次对话中完成复杂的项目
• 智能工件放置：文件是相对于项目根目录保存的，而不是随机位置

安装

通用安装程序（推荐）

通用安装程序为所有主要的MCP客户端提供全面的支持，并提供灵活的安装选项。

快速安装-自动检测所有客户端：

# Download and run the universal installer
git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
python install.py

# Auto-detects and configures all compatible MCP clients
# Restart your MCP clients - the orchestrator tools will be available automatically

手动配置的PyPI安装：

# Install from PyPI
pip install mcp-task-orchestrator

# Then configure your MCP client manually (see configuration section below)

安装到特定客户端：

# Configure specific clients only
python install.py --clients claude,cursor

# Skip MCP configuration entirely (manual setup)
python install.py --no-clients

# Development installation with all tools
python install.py --dev

# Install in user directory
python install.py --user

高级安装选项：

# Force PyPI installation even in development
python install.py --source pypi

# Install specific version
python install.py --version 2.0.0

# Install from git repository
python install.py --git https://github.com/EchoingVesper/mcp-task-orchestrator.git

# Install in custom virtual environment
python install.py --venv /path/to/venv

# Force overwrite existing installation
python install.py --force

对于外部管理环境（WSL、Ubuntu 23.04+）：

# Create virtual environment first
python -m venv mcp-orchestrator-env
source mcp-orchestrator-env/bin/activate  # Linux/WSL/macOS
# OR: mcp-orchestrator-env\Scripts\activate  # Windows

# Clone and install
git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
python install.py --venv ../mcp-orchestrator-env

pipx的替代方案：

# Install via pipx for isolation
pipx install mcp-task-orchestrator

# Manual MCP configuration required (see configuration section)

安装特点

• ✅ 零漏洞所有38个安全问题均已解决
• ✅ 跨平台：Windows、macOS、Linux支持
• ✅ 多客户端：克劳德桌面，光标，风帆，VS代码，Zed，克劳德代码
• ✅ 自动备份：配置保护和回滚
• ✅ 演出：安装时间\24小时）
• 性能优化：防止数据库膨胀并保持响应能力
• 结构验证：确保任务层次结构保持一致
• 移交准备：简化上下文转换和项目移交
• 健康监测：提供系统状态和优化建议

快速维护: "Use the maintenance coordinator to scan and cleanup the current session"

有关详细指导，请参阅 维护协调员指南.

支持的环境

配置和定制

通用安装程序以零漏洞设计自动处理所有MCP客户端配置。有关高级配置选项，请参阅 安装指南 和 配置参考.

自定义专家角色

通过编辑创建特定于项目的专家 .task_orchestrator/roles/project_roles.yaml:

security_auditor:
  role_definition: "You are a Security Analysis Specialist"
  expertise:
    - "OWASP security standards"
    - "Penetration testing methodologies"
    - "Secure coding practices"
  approach:
    - "Focus on security implications"
    - "Identify potential vulnerabilities"
    - "Ensure compliance with security standards"

在任何目录中启动新的编排会话时，都会自动创建该文件。

常见用例

软件开发：完整的web应用程序，API开发和测试，数据库架构设计，DevOps管道设置

数据科学：机器学习管道、数据分析工作流程、研究项目规划、模型部署策略

文件和内容：技术文档、代码审查和重构、测试策略开发、内容创建工作流

故障排除

常见问题

“未检测到MCP客户端” -确保至少安装了一个受支持的客户端，并在安装前运行一次

“配置失败” -检查文件权限，尝试以管理员/sudo身份运行安装程序

“找不到模块错误” -尝试在新的虚拟环境中重新安装：

python -m venv fresh_env && source fresh_env/bin/activate && pip install mcp-task-orchestrator

诊断工具

# System health check
python scripts/diagnostics/check_status.py

# Database optimization
python scripts/diagnostics/diagnose_db.py

# Installation verification
python scripts/diagnostics/verify_tools.py

有关全面的故障排除，请参阅 故障排除指南 和 文档门户.

测试与开发

增强的测试基础设施

MCP任务编排器包括强大的测试改进，消除了常见问题：

• ✅ 无输出截断：基于文件的输出系统可防止测试输出截断
• ✅ 无资源警告：正确的数据库连接管理消除了资源警告
• ✅ 无测试挂起：全面的挂起检测和超时机制
• ✅ 备选试车手：使用专业跑步者绕过pytest限制

快速测试命令

# Activate your virtual environment (if using one)
source your_venv/bin/activate  # Linux/Mac
your_venv\Scripts\activate     # Windows

# Run enhanced testing suite
python tests/test_resource_cleanup.py     # Validate resource management
python tests/test_hang_detection.py       # Test hang prevention systems
python tests/enhanced_migration_test.py   # Run migration test with full output

# Demonstrate improved testing features
python tests/demo_file_output_system.py   # Show file-based output system
python tests/demo_alternative_runners.py  # Show alternative test runners

# Traditional pytest (still supported)
python -m pytest tests/ -v

测试最佳实践

为了可靠地执行测试，请使用新的测试基础架构：

# File-based output (prevents truncation)
from mcp_task_orchestrator.testing import TestOutputWriter
writer = TestOutputWriter(output_dir)
with writer.write_test_output("my_test", "text") as session:
    session.write_line("Test output here...")

# Alternative test runners (more reliable than pytest)
from mcp_task_orchestrator.testing import DirectFunctionRunner
runner = DirectFunctionRunner(output_dir=Path("outputs"))
result = runner.execute_test(my_test_function, "test_name")

# Database connections (prevents resource warnings)
from tests.utils.db_test_utils import managed_sqlite_connection
with managed_sqlite_connection("test.db") as conn:
    # Database operations with guaranteed cleanup
    pass

📖 文档:

• 测试最佳实践 -快速参考指南
• 测试改进 -全面的文件

看 CONTRIBUTING.md 供款指南和 docs/ 以获取完整的文档。

重要免责声明

本软件按“原样”提供，不提供任何形式的保修。 它旨在用于开发和实验目的。作者没有声称其适用于生产、关键系统或任何特定用例。

使用风险自负。 作者对使用本软件造成的任何损害或损失不承担任何责任，包括但不限于数据丢失、系统故障或业务中断。

开发工具通知。 这是一个开发工具，在任何生产使用之前都应该经过彻底的测试和验证。

许可证和资源

此项目根据MIT许可证获得许可-请参阅 LICENSE 文件以获取详细信息。

链接

• 仓库:
• 问题: 报告问题或请求功能
• 文档: 文档门户 | 安装指南 | api参考

版权所有（c）2025回声Vesper