ACE MCP Server

🌟 Overview

ACE MCP Server implements the Agentic Context Engineering framework as a Model Context Protocol (MCP) server for Cursor AI. Your AI assistant learns from its own execution feedback, building a self-improving knowledge base that gets better with every task.

Based on research from Stanford University & SambaNova Systems (October 2025).

🎯 Why ACE?

Traditional AI assistants forget everything between conversations. ACE remembers what works and what doesn't, creating a playbook of proven strategies that grows with your team's experience.

The Problem

💸 High token costs from sending full context every time
🔁 Same mistakes repeated across conversations
📝 No learning from past successes/failures
🤷 Generic responses that don't fit your codebase

The Solution

✅ Incremental delta updates (send only changes)
✅ Self-learning from execution feedback
✅ Semantic deduplication (no redundant knowledge)
✅ Context-aware strategies per domain

⚡ Quick Start

Prerequisites

Node.js 18+
Cursor AI or MCP-compatible client
OpenAI API key OR local LM Studio server

Installation

# Clone repository git clone https://github.com/Angry-Robot-Deals/ace-mcp.git cd ace-mcp # Install dependencies npm install # Configure environment cp .env.example .env # Edit .env with your LLM provider settings # Build npm run build # Start server npm start

Cursor AI Configuration

Add to ~/.cursor/mcp.json:

{ "mcpServers": { "ace-context-engine": { "command": "node", "args": ["/absolute/path/to/ace-mcp-server/dist/index.js"], "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-your-api-key-here", "ACE_CONTEXT_DIR": "./contexts", "ACE_LOG_LEVEL": "info" } } } }

Using Local LM Studio

{ "mcpServers": { "ace-context-engine": { "command": "node", "args": ["/absolute/path/to/ace-mcp-server/dist/index.js"], "env": { "LLM_PROVIDER": "lmstudio", "LMSTUDIO_BASE_URL": "http://localhost:1234/v1", "LMSTUDIO_MODEL": "your-model-name", "ACE_CONTEXT_DIR": "./contexts" } } } }

🚀 Features

Core ACE Framework

Generator: Creates code using learned strategies
Reflector: Analyzes what worked and what didn't
Curator: Synthesizes insights into playbook updates

Smart Context Management

Incremental Updates: Only send deltas, not full context
Semantic Deduplication: Automatically merge similar strategies
Multi-Context Support: Separate playbooks for frontend, backend, DevOps, etc.
Persistent Storage: JSON-based storage with configurable backends

LLM Flexibility

OpenAI Support: Use GPT-4, GPT-3.5-turbo
LM Studio Support: Run local models offline
Provider Abstraction: Easy to add new LLM providers
Configurable: Switch providers via environment variables

Deployment Options

Local Development: Run on your machine
Docker: Full containerization support
Ubuntu VM: Production deployment ready
Cloud: Deploy to any Node.js-compatible platform

📊 How It Works

graph LR A[Your Query] --> B[Generator] B --> C[Execute Code] C --> D[Reflector] D --> E[Extract Insights] E --> F[Curator] F --> G[Update Playbook] G --> H[Better Next Time] H --> B

Example: Building an Authentication System

First Query: "Create login endpoint"
- Generator uses generic strategies
- Creates basic endpoint
- Reflector notices: "Used bcrypt for passwords ✓", "Missing rate limiting ✗"
Curator Updates Playbook:
- ADD: "Always use bcrypt for password hashing"
- ADD: "Include rate limiting on auth endpoints"
Second Query: "Create registration endpoint"
- Generator automatically applies learned strategies
- Includes bcrypt AND rate limiting from the start
- Better code, fewer tokens, less iteration

🛠️ Available MCP Tools

Tool	Description	Use Case
`ace_generate`	Generate code using playbook	Primary code generation
`ace_reflect`	Analyze trajectory for insights	After code execution
`ace_curate`	Convert insights to updates	Process reflections
`ace_update_playbook`	Apply delta operations	Persist learned strategies
`ace_get_playbook`	Retrieve current strategies	Review learned knowledge
`ace_export_playbook`	Export as JSON	Backup or share playbooks

📖 Documentation

Document	Description	Location
Quick Start	Installation and first steps	`docs/intro/START_HERE.md`
Full Specification	Complete project details	`docs/intro/DESCRIPTION.md`
Installation Guide	Detailed setup instructions	`docs/intro/INSTALLATION.md`
Memory Bank	Project knowledge base	`memory-bank/`

🐳 Docker Deployment

Local Development

# Start all services docker-compose -f docker-compose.dev.yml up # Dashboard available at http://localhost:3000

Production (Ubuntu VM)

# Configure environment cp .env.example .env # Edit .env with production settings # Start services docker-compose up -d # View logs docker-compose logs -f ace-server

See docs/intro/INSTALLATION.md for detailed deployment guides.

⚙️ Configuration

Environment Variables

# LLM Provider Selection LLM_PROVIDER=openai # 'openai' or 'lmstudio' # OpenAI Configuration OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-4 OPENAI_EMBEDDING_MODEL=text-embedding-3-small # LM Studio Configuration LMSTUDIO_BASE_URL=http://localhost:1234/v1 LMSTUDIO_MODEL=your-model-name # ACE Settings ACE_CONTEXT_DIR=./contexts # Storage directory ACE_LOG_LEVEL=info # Logging level ACE_DEDUP_THRESHOLD=0.85 # Similarity threshold (0-1) ACE_MAX_PLAYBOOK_SIZE=1000 # Max bullets per context

🏗️ Project Structure

ace-mcp-server/ ├── src/ │ ├── core/ # ACE components (Generator, Reflector, Curator) │ ├── mcp/ # MCP server and tools │ ├── storage/ # Bullet storage and deduplication │ ├── llm/ # LLM provider abstraction │ ├── utils/ # Utilities (config, logger, errors) │ └── index.ts # Entry point ├── dashboard/ # Web dashboard (optional) ├── docs/ │ ├── intro/ # Documentation │ └── archive/ # Archived docs ├── memory-bank/ # Project knowledge base ├── docker-compose.yml # Production deployment ├── docker-compose.dev.yml # Development deployment └── package.json

🧪 Development

# Install dependencies npm install # Run in development mode (with hot reload) npm run dev # Build for production npm run build # Run tests npm test # Lint code npm run lint

📈 Performance Metrics

Based on Stanford/SambaNova research:

86.9% reduction in context adaptation latency
+10.6% improvement in code generation accuracy
30-50% reduction in storage via semantic deduplication
< 2s for delta operations on 1K bullet playbooks

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines.

Fork the repository
Create a feature branch
Make your changes
Write tests
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

Research Paper: Agentic Context Engineering
MCP Specification: modelcontextprotocol.io
Cursor AI: cursor.sh
GitHub: Angry-Robot-Deals/ace-mcp

💬 Support

📧 Email: support@example.com
💬 Discussions: GitHub Discussions
🐛 Issues: GitHub Issues
📖 Documentation: See docs/intro/ directory

🙏 Acknowledgments

Based on research by:

Stanford University
SambaNova Systems

Paper: "Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models" (October 2025)