ACE MCP Server

# Product Context: ACE MCP Server ## Product Vision ACE MCP Server is a production-ready implementation of the Agentic Context Engineering framework that enables AI agents to learn and improve from their own execution feedback, dramatically reducing token consumption while improving code quality. ## Target Users ### Primary Users 1. **AI/ML Engineers**: Integrating ACE into custom agent workflows 2. **Cursor AI Users**: Leveraging self-improving context for code generation 3. **DevOps Teams**: Deploying context-aware development environments ### Secondary Users 1. **Researchers**: Studying incremental learning in LLMs 2. **Product Teams**: Building AI-powered development tools 3. **Enterprise Developers**: Running local LLM infrastructure ## Key Features ### 1. ACE Framework Implementation - **Incremental Delta Updates**: 86.9% reduction in adaptation latency - **Grow-and-Refine Mechanism**: Self-improving playbooks - **Semantic Deduplication**: 30-50% storage reduction - **Feedback Learning**: Learn from helpful/harmful strategies ### 2. LLM Provider Flexibility (NEW REQUIREMENT) - **OpenAI Integration**: Cloud-based GPT models - **LM Studio Support**: Local model execution - **Provider Switching**: Configuration-based selection - **Offline Operation**: Work without internet (LM Studio) **Key Benefit**: Teams can start with OpenAI for prototyping, then switch to local models for production without code changes. ### 3. Dual Deployment Architecture (NEW REQUIREMENT) - **Local Development**: Docker Compose on macOS/Windows/Linux - **Remote Production**: Ubuntu VM deployment - **Unified Configuration**: Same setup for both environments - **Dashboard Access**: Web interface for monitoring **Key Benefit**: Develop locally with full control, deploy to production with same confidence. ### 4. MCP Protocol Compliance - **Standard Transport**: stdio for Cursor AI integration - **Six Core Tools**: Complete ACE workflow support - **Error Handling**: Graceful degradation - **Logging**: Structured logs for debugging ### 5. Interactive Dashboard - **Playbook Browser**: Search and filter strategies - **Statistics**: Real-time metrics and analytics - **Operations Log**: Track ACE workflow execution - **Settings**: Configure deduplication threshold ## User Workflows ### Workflow 1: Cursor AI Integration ```mermaid graph LR A[User writes query] --> B[Cursor AI calls ace_generate] B --> C[Generator uses playbook] C --> D[Code generated] D --> E[User reviews result] E --> F[Reflector analyzes] F --> G[Curator creates deltas] G --> H[Playbook updated] H --> I[Next query is better] ``` ### Workflow 2: Custom Agent Development ```mermaid graph LR A[Agent task] --> B[Generate trajectory] B --> C[Execute code] C --> D[Reflect on results] D --> E[Curate insights] E --> F[Update playbook] F --> G[Agent improves] ``` ### Workflow 3: Dashboard Exploration ```mermaid graph LR A[Open dashboard] --> B[Browse playbooks] B --> C[View statistics] C --> D[Test ACE workflow] D --> E[Export playbook] E --> F[Import to production] ``` ## Use Cases ### Use Case 1: Code Generation Assistant **Actor**: Developer using Cursor AI **Goal**: Generate authentication endpoint with best practices **Flow**: 1. Developer writes: "Create secure login endpoint" 2. ACE retrieves relevant bullets (e.g., "Use bcrypt for passwords") 3. Generator creates code with learned strategies 4. Reflector identifies what worked well 5. Playbook learns new patterns for future requests **Outcome**: Each authentication endpoint gets better as playbook grows. ### Use Case 2: Local LLM Development (NEW) **Actor**: Enterprise team with security requirements **Goal**: Use AI assistance without sending code to cloud **Flow**: 1. Team deploys LM Studio on internal network 2. Configure ACE with `LLM_PROVIDER=lmstudio` 3. Set `LMSTUDIO_BASE_URL=http://10.242.247.136:11888/v1` 4. All LLM calls stay on-premise 5. Same ACE workflow, zero cloud dependency **Outcome**: AI-powered development with full data sovereignty. ### Use Case 3: Remote Team Collaboration (NEW) **Actor**: Distributed development team **Goal**: Share learned strategies across team members **Flow**: 1. DevOps deploys ACE server on Ubuntu VM 2. Team members connect Cursor to VM endpoint 3. Each developer's work improves shared playbook 4. Best practices propagate automatically 5. Dashboard shows team-wide statistics **Outcome**: Collective intelligence without manual documentation. ### Use Case 4: Multi-Project Context Management **Actor**: Full-stack developer working on multiple projects **Goal**: Maintain separate contexts for frontend/backend/infrastructure **Flow**: 1. Create contexts: `frontend`, `backend`, `devops` 2. Each context accumulates project-specific strategies 3. Query with context_id: "Create React component" → `frontend` 4. Strategies don't leak between contexts 5. Export/import contexts between machines **Outcome**: Context isolation prevents strategy collision. ## Value Propositions ### For Individual Developers - **Faster Coding**: 86.9% reduction in context adaptation - **Better Quality**: +10.6% accuracy from learned patterns - **Privacy**: Local LLM option for sensitive code - **Learning**: System learns your coding style ### For Teams - **Shared Knowledge**: Collective playbook of best practices - **Consistency**: Same patterns across team members - **Onboarding**: New members benefit from team's experience - **Deployment Flexibility**: Local dev + remote production ### For Enterprises - **Cost Reduction**: Fewer API tokens, lower LLM costs - **Data Security**: On-premise LLM option - **Scalability**: Deploy on existing infrastructure - **Compliance**: No code sent to external APIs ## Competitive Advantages 1. **Token Efficiency**: 86.9% better than full context rewrites 2. **Self-Improvement**: Learns without labeled training data 3. **Provider Agnostic**: OpenAI or local models 4. **Deployment Flexibility**: Docker everywhere 5. **Open Architecture**: Inspect and modify playbooks 6. **Research-Backed**: Stanford/SambaNova paper validation ## Success Metrics ### Technical Metrics - Token reduction: >80% vs baseline - Accuracy improvement: >10% vs static context - Deduplication ratio: 30-50% storage savings - Latency: <2s for delta operations ### User Metrics - Setup time: <30 minutes from clone to running - Dashboard accessibility: 100% uptime - LLM provider switch: <5 minutes - Docker deployment: Single command ### Business Metrics - API cost reduction: >50% for OpenAI users - Local LLM adoption: >30% of enterprise users - Multi-environment deployments: >70% - User satisfaction: >4.5/5 stars ## Roadmap (Future Enhancements) ### Phase 1: Current Implementation - [x] Core ACE framework - [ ] LLM provider abstraction - [ ] Docker deployment configs - [ ] Dashboard containerization ### Phase 2: Production Hardening - [ ] Authentication/authorization - [ ] Rate limiting - [ ] Metrics export (Prometheus) - [ ] Backup/restore tools ### Phase 3: Advanced Features - [ ] Multi-tenant support - [ ] Distributed playbook storage - [ ] Real-time collaboration - [ ] Transformer-based embeddings ### Phase 4: Ecosystem Integration - [ ] VS Code extension - [ ] JetBrains plugin - [ ] GitHub Actions integration - [ ] Slack bot for team stats ## Documentation Structure 1. **User Guide** (15 pages): End-user focused - Quick start - Tool reference - Workflow examples - Best practices 2. **Administrator Guide** (23 pages): Ops-focused - Installation methods - Production deployment - Configuration - Monitoring & security 3. **Developer Guide** (NEW): Contributor-focused - Architecture overview - Adding LLM providers - Extending ACE components - Testing strategies ## Design Principles 1. **Simplicity First**: Easy setup, clear workflows 2. **Flexibility**: Support multiple LLM providers and deployment models 3. **Transparency**: Human-readable playbooks, inspectable operations 4. **Efficiency**: Minimize tokens, maximize value 5. **Reliability**: Graceful degradation, comprehensive logging 6. **Security**: No surprises, clear data handling ## User Pain Points Addressed ### Pain: High OpenAI API costs **Solution**: Semantic deduplication + incremental updates = 80%+ token reduction ### Pain: Can't use AI with proprietary code **Solution**: LM Studio integration = fully offline operation ### Pain: Complex setup for team environments **Solution**: Docker Compose = single command deployment ### Pain: Context doesn't improve over time **Solution**: ACE self-learning = automatic improvement from feedback ### Pain: Development/production parity issues **Solution**: Same Docker setup = dev and prod identical ### Pain: Dashboard only useful for demo **Solution**: Production-ready web interface = real monitoring tool