Metadata-Version: 2.4
Name: aceflow-mcp-server
Version: 2.0.0
Summary: AceFlow MCP Server - AI-协作增强版，支持双向AI-MCP数据交换的智能开发工作流服务器
Author-email: AceFlow Team <team@aceflow.dev>
Maintainer-email: AceFlow Team <team@aceflow.dev>
License: MIT
Project-URL: Homepage, https://github.com/aceflow/mcp-server
Project-URL: Documentation, https://docs.aceflow.dev
Project-URL: Repository, https://github.com/aceflow/mcp-server.git
Project-URL: Bug Tracker, https://github.com/aceflow/mcp-server/issues
Project-URL: Changelog, https://github.com/aceflow/mcp-server/blob/main/CHANGELOG.md
Keywords: mcp,model-context-protocol,workflow,ai-collaboration,ai-tools,dual-direction,intelligent-workflow,claude-code,cursor
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: performance
Requires-Dist: psutil>=5.9.0; extra == "performance"
Requires-Dist: memory-profiler>=0.60.0; extra == "performance"
Requires-Dist: py-spy>=0.3.14; extra == "performance"
Provides-Extra: monitoring
Requires-Dist: prometheus-client>=0.16.0; extra == "monitoring"
Requires-Dist: grafana-api>=1.0.3; extra == "monitoring"
Provides-Extra: all
Requires-Dist: aceflow-mcp-server[dev,monitoring,performance]; extra == "all"
Dynamic: license-file

# AceFlow MCP Server - AI-协作增强版

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

[![PyPI version](https://badge.fury.io/py/aceflow-mcp-server.svg)](https://badge.fury.io/py/aceflow-mcp-server)
[![Python Support](https://img.shields.io/pypi/pyversions/aceflow-mcp-server.svg)](https://pypi.org/project/aceflow-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📋 概述

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** - 项目初始化
```python
# 初始化标准项目
aceflow_init(mode="standard", project_name="my-project")
```

### 2. **aceflow_stage** - 阶段管理 (双向协作增强版)
```python
# 传统操作
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** - 项目验证
```python
# 基础验证
aceflow_validate(mode="basic", report=True)
```

### 4. **aceflow_template** - 模板管理
```python
# 列出可用模板
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保证多线程数据一致性
- **📊 性能监控**: 实时缓存命中率和队列状态

## 🚀 快速开始

### 安装

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

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

### 基础使用

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

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

### MCP 配置

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

```json
{
  "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 项目

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

#### `aceflow_stage`
管理项目阶段

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

#### `aceflow_validate`
验证项目状态

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

### 协作工具 (增强模式)

#### `aceflow_respond`
响应协作请求

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

### 智能工具 (增强模式)

#### `aceflow_intent_analyze`
分析用户意图

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

## 🔧 高级配置

### 环境变量

```bash
# 设置运行模式
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`:

```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 迁移

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

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

### 从 aceflow-enhanced-server 迁移

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

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

## 🧪 开发

### 安装开发依赖

```bash
# 克隆仓库
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
```

### 运行测试

```bash
# 运行所有测试
aceflow-unified test

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

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

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

## 🐛 故障排除

### 常见问题

#### 服务器启动失败

```bash
# 检查系统状态
aceflow-unified doctor

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

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

#### 功能模块未加载

```bash
# 检查模式设置
echo $ACEFLOW_MODE

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

更多故障排除信息，请查看 [故障排除指南](https://docs.aceflow.dev/troubleshooting)。

## 📄 许可证

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

## 🔗 相关链接

- [文档](https://docs.aceflow.dev)
- [问题反馈](https://github.com/aceflow/mcp-server/issues)
- [讨论区](https://github.com/aceflow/mcp-server/discussions)
- [更新日志](https://github.com/aceflow/mcp-server/blob/main/CHANGELOG.md)

## 🤝 贡献

我们欢迎社区贡献！请查看 [贡献指南](CONTRIBUTING.md) 了解详情。

## 📈 版本历史

### 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 统一服务器，体验更强大、更灵活的工作流管理！**
