# AceFlow MCP Server

AI-driven workflow management through Model Context Protocol.

## 📁 Project Structure

```
aceflow-mcp-server/
├── aceflow_mcp_server/          # Core package directory
│   ├── core/                    # Core functionality modules
│   ├── main.py                  # Main entry point
│   ├── tools.py                 # Tool implementations
│   └── ...
├── tests/                       # Formal test suite
├── examples/                    # Examples and demo code
├── scripts/                     # Build and deployment scripts
│   ├── build/                   # Build-related scripts
│   ├── deploy/                  # Deployment scripts
│   └── dev/                     # Development tools
├── docs/                        # Documentation
│   ├── user-guide/              # User guides
│   ├── developer-guide/         # Developer guides
│   └── project/                 # Project documentation
├── dev-tests/                   # Development tests and experiments
└── pyproject.toml               # Project configuration
```

## Overview

AceFlow MCP Server provides structured software development workflows through the Model Context Protocol (MCP), enabling AI clients like Kiro, Cursor, and Claude to manage projects with standardized processes.

## Features

### 🛠️ MCP Tools
- **aceflow_init**: Initialize projects with different workflow modes
- **aceflow_stage**: Manage project stages and workflow progression  
- **aceflow_validate**: Validate project compliance and quality
- **aceflow_template**: Manage workflow templates

### 📊 MCP Resources
- **aceflow://project/state**: Current project state and progress
- **aceflow://workflow/config**: Workflow configuration and settings
- **aceflow://stage/guide/{stage}**: Stage-specific guidance and instructions

### 🤖 MCP Prompts
- **workflow_assistant**: Context-aware workflow guidance
- **stage_guide**: Stage-specific assistance and best practices

## Quick Start

### Installation

```bash
# Method 1: Install via uvx (recommended for end users)
uvx aceflow-mcp-server

# Method 2: Install via pip (traditional method)
pip install aceflow-mcp-server

# Method 3: Install with optional features
pip install aceflow-mcp-server[performance,monitoring]
```

### MCP Client Configuration

#### For uvx installation:
```json
{
  "mcpServers": {
    "aceflow": {
      "command": "uvx",
      "args": ["aceflow-mcp-server@latest"],
      "env": {
        "ACEFLOW_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

#### For pip installation:
```json
{
  "mcpServers": {
    "aceflow": {
      "command": "aceflow-mcp-server",
      "args": [],
      "env": {
        "ACEFLOW_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### Usage Example

```
User: "I want to start a new AI project with standard workflow"

AI: I'll help you initialize a new project using AceFlow.

[Uses aceflow_init tool]
✅ Project initialized successfully in standard mode!

Current status:
- Project: ai-project
- Mode: STANDARD
- Stage: user_stories (0% complete)

Ready to begin with user story analysis. Would you like guidance for this stage?
```

## Workflow Modes

### Minimal Mode
Fast prototyping and concept validation
- 3 stages: Implementation → Test → Demo
- Ideal for MVPs and quick experiments

### Standard Mode  
Traditional software development workflow
- 8 stages: User Stories → Task Breakdown → Test Design → Implementation → Unit Test → Integration Test → Code Review → Demo
- Balanced approach for most projects

### Complete Mode
Enterprise-grade development process
- 12 stages: Full requirements analysis through security review
- Comprehensive quality gates and documentation

### Smart Mode
AI-enhanced adaptive workflow
- 10 stages with intelligent adaptation
- Dynamic complexity assessment and optimization

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Client     │    │  MCP Server     │    │  AceFlow Core   │
│  (Kiro/Cursor)  │◄──►│   (FastMCP)     │◄──►│    Engine       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │  File System    │
                       │ (.aceflow/...)  │
                       └─────────────────┘
```

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/aceflow/aceflow-mcp-server
cd aceflow-mcp-server

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=aceflow_mcp_server
```

### Project Structure

```
aceflow-mcp-server/
├── aceflow_mcp_server/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── tools.py           # MCP tools implementation
│   ├── resources.py       # MCP resources
│   ├── prompts.py         # MCP prompts
│   └── core/              # Core functionality
├── tests/                 # Test suite
├── docs/                  # Documentation
└── pyproject.toml         # Project configuration
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- **Documentation**: https://docs.aceflow.dev/mcp
- **Issues**: https://github.com/aceflow/aceflow-mcp-server/issues
- **Discussions**: https://github.com/aceflow/aceflow-mcp-server/discussions

---

*Generated by AceFlow v3.0 MCP Server*