AceFlow MCP Server - AI-协作增强版

🚀 双向AI协作 - 支持AI Agent与MCP工具双向数据交换的智能开发工作流服务器

📋 概述

AceFlow MCP Server v2.0 引入了突破性的双向AI-MCP协作架构，不仅支持传统的MCP工具调用，更实现了AI Agent向MCP工具提供数据的反向流程。这种设计充分发挥了AI Agent的内容生成能力和MCP工具的数据管理能力。

🎯 核心创新 - 双向协作

传统单向模式 (v1.x)

AI Agent → MCP Tools → 执行结果

双向协作模式 (v2.0)

AI Agent ↔ MCP Tools ↔ 数据持久化

AI Agent → MCP 方向：

• set_analysis: AI提供项目分析数据
• save_output: AI保存阶段产出内容

MCP → AI Agent 方向：

• prepare_data: MCP准备结构化数据包
• validate: 验证数据完整性

✨ 主要特性

• 🤝 双向协作: 革命性的AI-MCP双向数据交换
• ⚡ 性能优化: 内存缓存、并发处理、批量操作
• 📊 智能工作流: 支持4种复杂度项目模式
• 🔧 核心工具: 4个精心设计的MCP工具
• 💾 数据持久化: 智能数据管理和状态保持
• 🧪 稳定可靠: 完整测试覆盖和错误处理

🛠️ 核心工具

1. aceflow_init - 项目初始化

# 初始化标准项目
aceflow_init(mode="standard", project_name="my-project")

2. aceflow_stage - 阶段管理 (双向协作增强版)

# 传统操作
aceflow_stage(action="status")      # 查看状态
aceflow_stage(action="next")        # 推进阶段

# AI → MCP 协作
aceflow_stage(action="set_analysis", stage="analysis", data={
    "project_info": {"name": "web-app", "version": "1.0.0"},
    "code_metrics": {"complexity": "medium", "coverage": 85}
})

aceflow_stage(action="save_output", stage="design", data={
    "content": {"architecture": "microservices"},
    "metadata": {"author": "AI Agent"}
})

# MCP → AI 协作  
aceflow_stage(action="prepare_data", stage="implementation")
aceflow_stage(action="validate", stage="design")

3. aceflow_validate - 项目验证

# 基础验证
aceflow_validate(mode="basic", report=True)

4. aceflow_template - 模板管理

# 列出可用模板
aceflow_template(action="list")

🏗️ 双向协作架构

架构图

┌─────────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude Code/Cursor)               │
│  ┌─────────────────┐                    ┌──────────────────────┐ │
│  │   内容生成      │                    │    数据分析         │ │
│  │   代码编写      │                    │    质量评估         │ │
│  │   文档创建      │                    │    决策建议         │ │
│  └─────────────────┘                    └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
           │ set_analysis               │ prepare_data
           │ save_output               │ validate
           ↓                          ↑
┌─────────────────────────────────────────────────────────────────┐
│                    AceFlow MCP Server                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ SimplifiedUnified│  │   DataManager   │  │  MCPStdioServer │ │
│  │     Tools       │  │   (缓存+持久化)  │  │   (协议适配)    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│                    本地文件系统                                │
│  .aceflow/                                                     │
│  ├── analysis_data.json    (AI分析数据)                       │
│  ├── stage_outputs/        (阶段产出)                         │
│  ├── cache/                (性能缓存)                         │
│  └── current_state.json    (项目状态)                         │
└─────────────────────────────────────────────────────────────────┘

工作流程

1. AI分析阶段: AI Agent分析项目，调用set_analysis提供数据
2. MCP处理阶段: MCP工具处理数据，更新项目状态
3. 数据准备阶段: MCP调用prepare_data为下阶段准备数据包
4. AI生成阶段: AI Agent基于数据包生成内容
5. 输出保存阶段: AI Agent调用save_output保存产出
6. 验证阶段: MCP调用validate确保数据完整性

性能特性

• 📦 内存缓存: 5分钟TTL，减少重复数据读取
• 🔄 并发处理: 4线程池，支持异步批量操作
• 🔒 线程安全: RLock保证多线程数据一致性
• 📊 性能监控: 实时缓存命中率和队列状态

🚀 快速开始

安装

# 使用 pip 安装
pip install aceflow-mcp-server

# 使用 uvx 安装（推荐）  
uvx aceflow-mcp-server

基础使用

# 启动MCP服务器
python -m aceflow_mcp_server.mcp_stdio_server

# 或使用便捷命令
aceflow-mcp-server

MCP 配置

在你的 MCP 客户端配置中添加：

{
  "mcpServers": {
    "aceflow-unified": {
      "command": "aceflow-unified",
      "args": ["serve", "--mode", "enhanced"],
      "env": {
        "ACEFLOW_LOG_LEVEL": "INFO"
      }
    }
  }
}

🔧 配置模式

基础模式 (Basic)

• ✅ 核心工具: aceflow_init, aceflow_stage, aceflow_validate
• ✅ 基础资源: project_state, workflow_config, stage_guide
• 🎯 适用于: 简单项目，快速原型

标准模式 (Standard)

• ✅ 包含基础模式所有功能
• ✅ 可选启用协作和智能功能
• 🎯 适用于: 大多数项目，平衡功能和性能

增强模式 (Enhanced)

• ✅ 包含标准模式所有功能
• ✅ 协作工具: aceflow_respond, aceflow_collaboration_status, aceflow_task_execute
• ✅ 智能工具: aceflow_intent_analyze, aceflow_recommend
• ✅ 增强资源: collaboration_insights, usage_stats
• 🎯 适用于: 复杂项目，团队协作

📚 API 参考

核心工具

aceflow_init

初始化 AceFlow 项目

result = await aceflow_init(
    mode="standard",
    project_name="my-project",
    directory="./my-project"
)

aceflow_stage

管理项目阶段

result = await aceflow_stage(
    action="next",
    current_stage="planning"
)

aceflow_validate

验证项目状态

result = await aceflow_validate(
    mode="basic",
    target="project"
)

协作工具 (增强模式)

aceflow_respond

响应协作请求

result = await aceflow_respond(
    request_id="req-123",
    response="Approved",
    user_id="user-456"
)

智能工具 (增强模式)

aceflow_intent_analyze

分析用户意图

result = await aceflow_intent_analyze(
    user_input="Create a new web project",
    context={"type": "project_creation"}
)

🔧 高级配置

环境变量

# 设置运行模式
export ACEFLOW_MODE=enhanced

# 启用/禁用特定功能
export ACEFLOW_COLLABORATION_ENABLED=true
export ACEFLOW_INTELLIGENCE_ENABLED=true

# 性能配置
export ACEFLOW_CACHE_TTL=300
export ACEFLOW_MAX_CONCURRENT_REQUESTS=100

配置文件

创建 aceflow-config.json:

{
  "version": "2.0",
  "mode": "enhanced",
  "core": {
    "enabled": true,
    "default_mode": "standard",
    "auto_advance": false,
    "quality_threshold": 0.8
  },
  "collaboration": {
    "enabled": true,
    "confirmation_timeout": 30,
    "auto_confirm": false,
    "interaction_level": "standard"
  },
  "intelligence": {
    "enabled": true,
    "intent_recognition": true,
    "adaptive_guidance": true,
    "learning_enabled": false
  }
}

🔄 迁移指南

从 aceflow-server 迁移

# 自动迁移配置
aceflow-unified config --migrate

# 验证迁移结果
aceflow-unified config --validate

从 aceflow-enhanced-server 迁移

// 旧配置
{
  "mcpServers": {
    "aceflow-enhanced-server": {
      "command": "uvx",
      "args": ["aceflow-enhanced-server@latest"]
    }
  }
}

// 新配置
{
  "mcpServers": {
    "aceflow-unified": {
      "command": "aceflow-unified",
      "args": ["serve", "--mode", "enhanced"]
    }
  }
}

🧪 开发

安装开发依赖

# 克隆仓库
git clone https://github.com/aceflow/mcp-server.git
cd mcp-server

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行类型检查
mypy aceflow_mcp_server

# 格式化代码
black aceflow_mcp_server
isort aceflow_mcp_server

运行测试

# 运行所有测试
aceflow-unified test

# 运行单元测试
aceflow-unified test --mode unit

# 运行集成测试
aceflow-unified test --mode integration

# 运行兼容性测试
aceflow-unified test --mode compatibility

🐛 故障排除

常见问题

服务器启动失败

# 检查系统状态
aceflow-unified doctor

# 验证配置
aceflow-unified config --validate

# 查看详细日志
aceflow-unified serve --mode enhanced --log-level DEBUG

功能模块未加载

# 检查模式设置
echo $ACEFLOW_MODE

# 强制启用功能
export ACEFLOW_COLLABORATION_ENABLED=true
export ACEFLOW_INTELLIGENCE_ENABLED=true

更多故障排除信息，请查看 故障排除指南。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• 文档
• 问题反馈
• 讨论区
• 更新日志

🤝 贡献

我们欢迎社区贡献！请查看 贡献指南 了解详情。

📈 版本历史

v2.0.0 (双向AI协作架构) - 2025-08-26

• 🎉 突破性更新: 双向AI-MCP协作架构
• ✨ 新增功能:
  • AI Agent → MCP 数据输入 (set_analysis, save_output)
  • MCP → AI Agent 数据准备 (prepare_data, validate)
• ⚡ 性能优化:
  • 内存缓存系统 (5分钟TTL)
  • 4线程池并发处理
  • 批量操作支持
  • 线程安全保证
• 📊 数据管理:
  • 完整数据持久化层 (DataManager)
  • 智能缓存和过期处理
  • 项目状态一致性保证
• 🔧 接口增强:
  • aceflow_stage 支持 data 参数
  • 8种操作类型支持
  • 完善的错误处理和验证
• 🧪 测试覆盖:
  • 完整系统集成测试
  • 性能基准测试
  • 协作工作流验证

v1.x.x (简化架构)

• 🚀 基础MCP服务器功能
• 📋 项目初始化和阶段管理
• ✅ 基础验证和模板系统
• 🔧 4个核心工具

🚀 开始使用 AceFlow MCP 统一服务器，体验更强大、更灵活的工作流管理！