ACE MCP Server

Agentic Context Engineering - Self-improving AI context framework

Version: 1.0.0 | License: MIT

🎯 Overview

ACE MCP Server is an intelligent development assistant that learns from your coding patterns and automatically enhances your development workflow. It integrates seamlessly with Cursor AI through the Model Context Protocol (MCP), providing contextual code generation, intelligent analysis, and self-improving recommendations.

✨ Key Features

🤖 Smart Code Generation - Context-aware code generation with automatic prompt enhancement
🧠 Intelligent Code Analysis - Deep code analysis with actionable improvement suggestions
📚 Self-Improving Playbook - Accumulates knowledge and patterns from your development work
🔧 Multiple LLM Support - Works with OpenAI, Anthropic Claude, DeepSeek, Google Gemini, Mistral, and LM Studio
🐳 Docker Ready - Complete containerized solution for local and production deployment
🔒 Secure by Default - Bearer token authentication and comprehensive security measures

🚀 What Makes ACE Special

ACE doesn't just generate code - it learns from your development patterns and improves over time:

Generates contextual development trajectories
Reflects on code to extract insights and patterns
Curates knowledge into a self-improving playbook
Enhances future interactions with accumulated wisdom

📚 Documentation

🚀 Getting Started

Installation Guide - Complete setup instructions
Project Overview - Detailed project introduction
Quick Start - Fast track to running ACE

⚙️ Setup & Configuration

Cursor AI Setup - Basic MCP integration
Enhanced Auto Setup - Smart auto-enhancement features
LLM Providers - Configure different AI providers

🚀 Deployment

Production Deployment - Deploy to production servers
Full Deployment Guide - Complete Docker deployment guide

📖 Project Documentation

Project Status - Current development status
Architecture - Technical architecture details
GitHub Setup - Repository initialization

⚡ Quick Start

1. Clone and Setup

git clone https://github.com/Angry-Robot-Deals/ace-mcp.git
cd ace-mcp
cp .env.example .env
# Edit .env with your configuration

2. Docker Development

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop environment  
docker-compose -f docker-compose.dev.yml down

3. Configure MCP Client

Choose your environment for installation:

Cursor AI - Recommended for AI-powered code editing
Claude Desktop - For Anthropic's Claude Desktop app
Windsurf - For Windsurf IDE
Standalone/CLI - Run as standalone server

4. Use ACE Commands

# Smart code generation
@ace_smart_generate create a REST API endpoint

# Intelligent code analysis  
@ace_smart_reflect [your code here]

# Context-aware assistance
@ace_context_aware optimize database queries domain:database

# Automatic prompt enhancement
@ace_enhance_prompt create secure authentication focus_area:security

# View current playbook
@ace_playbook

5. View Playbook

The ACE playbook stores accumulated knowledge and patterns from your development work. View it using:

Option 1: Via API endpoint (JSON)

curl -H 'Authorization: Bearer YOUR_TOKEN' \
  http://localhost:34301/api/playbook | python3 -m json.tool

Option 2: Using provided script

./view-playbook.sh

Option 3: Via MCP tool in Cursor AI

@ace_playbook

Option 4: Via dashboard

http://localhost:34300

The playbook contains:

Patterns - Code patterns and conventions learned from your work
Best Practices - Development best practices accumulated over time
Insights - Key insights extracted from code reflections

🛠️ Development

Prerequisites

Node.js 18+
Docker & Docker Compose
TypeScript

Local Development

# Install dependencies
npm install

# Run tests
npm test

# Build project
npm run build

# Start development server
npm run dev

Testing MCP Methods

The test suite validates all 4 MCP methods through the MCP protocol:

ace_smart_generate - Code generation with auto-enhancement
ace_smart_reflect - Code analysis with suggestions
ace_context_aware - Contextual assistance
ace_enhance_prompt - Prompt enhancement

All tests verify:

✅ Correct response structure
✅ Required fields presence
✅ Error handling
✅ Tool availability

Local Testing

# Using npm script (recommended)
npm run test:mcp

# Or directly
node test-server.mjs

Docker Testing

# Build and start the container
docker-compose up -d ace-server

# Run tests inside the container using npm script
npm run test:mcp:docker

# Or directly
docker exec ace-mcp-server node test-server.mjs

# Or using direct Docker build
docker run --rm -it \
  -v $(pwd)/test-server.mjs:/app/test-server.mjs:ro \
  ace-mcp-server:latest \
  node test-server.mjs

Note: The test suite automatically detects whether it's running in Docker or locally and adjusts the server path accordingly.

Docker Management

Using Docker Compose (Recommended)

# Development environment
docker-compose -f docker-compose.dev.yml up -d

# Production environment  
docker-compose up -d

# View service logs
docker-compose logs ace-server
docker-compose logs ace-dashboard

# Rebuild services
docker-compose build --no-cache

Direct Docker Build (Alternative)

If you prefer to build and run the Docker image directly without docker-compose:

# Build the Docker image
docker build -t ace-mcp-server:latest .

# Run the container
docker run -d \
  --name ace-mcp-server \
  -p 34301:34301 \
  -e LLM_PROVIDER=deepseek \
  -e DEEPSEEK_API_KEY=your-api-key \
  -e ACE_SERVER_PORT=34301 \
  -e API_BEARER_TOKEN=your-secure-token \
  -v ace_contexts:/app/contexts \
  -v ace_logs:/app/logs \
  ace-mcp-server:latest

# View logs
docker logs -f ace-mcp-server

# Stop the container
docker stop ace-mcp-server

# Remove the container
docker rm ace-mcp-server

Note: When using direct Docker build, you'll need to:

Create named volumes manually: docker volume create ace_contexts and docker volume create ace_logs
Set all required environment variables via -e flags or use --env-file .env
Configure networking if you need to connect to other services

🔧 Configuration

LLM Providers & Models

ACE supports 6 LLM providers with various models:

Supported Providers

DeepSeek (Recommended) ⭐
- Provider: deepseek
- Default Model: deepseek-chat (V3.2-Exp)
- Embedding Model: deepseek-embedding
- Best for: ACE framework performance, cost-effective
- Pricing: $0.28/1M input, $0.42/1M output tokens
- Context: 128K tokens, Max output: 32K (reasoner mode)
- Environment Variables:
```
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-your-deepseek-api-key
DEEPSEEK_MODEL=deepseek-chat
DEEPSEEK_EMBEDDING_MODEL=deepseek-embedding
```
OpenAI
- Provider: openai
- Models: gpt-4o, gpt-4, gpt-3.5-turbo
- Embedding Models: text-embedding-3-small, text-embedding-3-large
- Environment Variables:
```
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4o
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
```
Anthropic Claude
- Provider: anthropic
- Models: claude-3-5-sonnet-20241022, claude-3-opus, claude-3-sonnet, claude-3-haiku
- Environment Variables:
```
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-api-key
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
```
Google Gemini
- Provider: gemini
- Models: gemini-1.5-pro, gemini-1.5-flash, gemini-pro
- Environment Variables:
```
LLM_PROVIDER=gemini
GOOGLE_API_KEY=your-google-api-key
GOOGLE_MODEL=gemini-1.5-pro
```
Mistral
- Provider: mistral
- Models: mistral-large-latest, mistral-medium-latest, mistral-small-latest
- Environment Variables:
```
LLM_PROVIDER=mistral
MISTRAL_API_KEY=your-mistral-api-key
MISTRAL_MODEL=mistral-large-latest
```
LM Studio (Local/Self-hosted)
- Provider: lmstudio
- Models: Any local model compatible with OpenAI API format
- Environment Variables:
```
LLM_PROVIDER=lmstudio
LMSTUDIO_BASE_URL=http://localhost:1234/v1
LMSTUDIO_MODEL=local-model
```

Environment Variables

Copy .env.example to .env and configure:

# LLM Provider Selection (required)
# Options: 'deepseek', 'openai', 'anthropic', 'gemini', 'mistral', 'lmstudio'
LLM_PROVIDER=deepseek

# Provider-specific API keys and models (see above for details)
DEEPSEEK_API_KEY=sk-your-deepseek-api-key
DEEPSEEK_MODEL=deepseek-chat

# Server Configuration
ACE_SERVER_PORT=34301
DASHBOARD_PORT=34300
API_BEARER_TOKEN=your-secure-token

# Docker Configuration
COMPOSE_PROJECT_NAME=ace-mcp
DOCKER_BUILDKIT=1

For complete configuration options, see .env.example file.

Installation & Configuration

Cursor AI

Global Configuration (All Users and Projects) - Recommended

macOS/Linux:

Create or edit the global MCP configuration file:

mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage
nano ~/Library/Application\ Support/Cursor/User/globalStorage/mcp.json

Add the following configuration:

{
  "mcpServers": {
    "ace-context-engineering": {
      "command": "node",
      "args": ["/absolute/path/to/ace-mcp-server/dist/index.js"],
      "env": {
        "LLM_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "your-deepseek-api-key-here",
        "API_BEARER_TOKEN": "your-secure-bearer-token-here",
        "ACE_LOG_LEVEL": "info",
        "ACE_CONTEXT_DIR": "./contexts"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "ace-context-engineering": {
      "command": "node",
      "args": ["C:\\path\\to\\ace-mcp-server\\dist\\index.js"],
      "env": {
        "LLM_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "your-deepseek-api-key-here",
        "API_BEARER_TOKEN": "your-secure-bearer-token-here"
      }
    }
  }
}

Linux:

mkdir -p ~/.config/Cursor/User/globalStorage
nano ~/.config/Cursor/User/globalStorage/mcp.json

Project-Specific Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ace-context-engineering": {
      "command": "node",
      "args": ["./ace-mcp-server/dist/index.js"],
      "env": {
        "LLM_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "your-api-key",
        "API_BEARER_TOKEN": "your-token"
      }
    }
  }
}

Restart Cursor AI to apply changes.

Claude Desktop

Installation

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Configuration

Create or edit the configuration file:

macOS/Linux:

mkdir -p ~/Library/Application\ Support/Claude  # macOS
# or
mkdir -p ~/.config/Claude  # Linux

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json  # macOS
# or
nano ~/.config/Claude/claude_desktop_config.json  # Linux

Windows:

New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add ACE configuration:

{
  "mcpServers": {
    "ace-context-engineering": {
      "command": "node",
      "args": ["/absolute/path/to/ace-mcp-server/dist/index.js"],
      "env": {
        "LLM_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "your-deepseek-api-key-here",
        "API_BEARER_TOKEN": "your-secure-bearer-token-here",
        "ACE_LOG_LEVEL": "info"
      }
    }
  }
}

Restart Claude Desktop to apply changes.

Windsurf

Installation

macOS:

~/Library/Application Support/Windsurf/User/globalStorage/mcp.json

Windows:

%APPDATA%\Windsurf\User\globalStorage\mcp.json

Linux:

~/.config/Windsurf/User/globalStorage/mcp.json

Configuration

Open Windsurf Settings → MCP Servers
Add ACE configuration:

{
  "mcpServers": {
    "ace-context-engineering": {
      "command": "node",
      "args": ["/absolute/path/to/ace-mcp-server/dist/index.js"],
      "env": {
        "LLM_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "your-api-key",
        "API_BEARER_TOKEN": "your-token"
      }
    }
  }
}

Restart Windsurf to apply changes.

Standalone/CLI

Running as Standalone Server

You can run ACE MCP Server as a standalone server:

# Using compiled JavaScript
node /path/to/ace-mcp-server/dist/index.js

# Using tsx (development)
npx tsx /path/to/ace-mcp-server/src/index.ts

Using with Docker

# Build and run
docker build -t ace-mcp-server:latest .
docker run -d \
  --name ace-mcp-server \
  -p 34301:34301 \
  -e LLM_PROVIDER=deepseek \
  -e DEEPSEEK_API_KEY=your-api-key \
  -e API_BEARER_TOKEN=your-token \
  ace-mcp-server:latest

Programmatic Usage

import { spawn } from 'child_process';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Start ACE server
const transport = new StdioClientTransport({
  command: 'node',
  args: ['/path/to/ace-mcp-server/dist/index.js'],
  env: {
    LLM_PROVIDER: 'deepseek',
    DEEPSEEK_API_KEY: 'your-api-key',
    API_BEARER_TOKEN: 'your-token'
  }
});

const client = new Client({
  name: 'my-app',
  version: '1.0.0'
}, {
  capabilities: {}
});

// Connect to server
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));

// Call a tool
const result = await client.callTool({
  name: 'ace_smart_generate',
  arguments: {
    prompt: 'Create a REST API endpoint for user authentication'
  }
});

console.log('Generated code:', result.content);

Available MCP Tools

ACE MCP Server provides 4 comprehensive tools:

ace_smart_generate - Automatically generate enhanced code with ACE insights
- Parameters: prompt (required), context (optional), auto_enhance (optional, default: true)
- Uses accumulated playbook knowledge to enhance code generation
ace_smart_reflect - Automatically analyze code and suggest improvements
- Parameters: code (required), auto_suggest (optional, default: true)
- Provides actionable improvement suggestions based on best practices
ace_context_aware - Get contextually relevant suggestions
- Parameters: query (required), domain (optional)
- Provides domain-specific assistance (web, api, database, frontend, backend, etc.)
ace_enhance_prompt - Enhance prompts with playbook knowledge
- Parameters: prompt (required), focus_area (optional)
- Automatically improves prompts using accumulated knowledge

🤝 Contributing

Read the Documentation - Start with Project Overview
Follow Best Practices - Review Development Guide
Submit PRs - Follow our contribution guidelines

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

ACE MCP Server - Making AI development smarter, one interaction at a time. 🚀

ace-mcp

ACE MCP Server

🎯 Overview

✨ Key Features

🚀 What Makes ACE Special

📚 Documentation

🚀 Getting Started

⚙️ Setup & Configuration

🚀 Deployment

📖 Project Documentation

⚡ Quick Start

1. Clone and Setup

2. Docker Development

3. Configure MCP Client

4. Use ACE Commands

5. View Playbook

🛠️ Development

Prerequisites

Local Development

Testing MCP Methods

Local Testing

Docker Testing

Docker Management

Using Docker Compose (Recommended)

Direct Docker Build (Alternative)

🔧 Configuration

LLM Providers & Models

Supported Providers

Environment Variables

Installation & Configuration

Cursor AI

Global Configuration (All Users and Projects) - Recommended

Project-Specific Configuration

Claude Desktop

Installation

Configuration

Windsurf

Installation

Configuration

Standalone/CLI

Running as Standalone Server

Using with Docker

Programmatic Usage

Available MCP Tools

🤝 Contributing

📄 License

🔗 Links

Reviews