ACE MCP Server

# Active Context: ACE MCP Server Initialization ## Current Task **Task ID**: ACE-INIT-001 **Task Name**: Project Initialization with LLM Provider Abstraction and Docker Support **Status**: In Progress **Created**: 2025-10-28 **Priority**: High ## Task Objectives 1. ✅ Initialize Memory Bank structure 2. ⏳ Analyze existing project files 3. ⏳ Implement LLM provider abstraction layer 4. ⏳ Add Docker and Docker Compose configuration 5. ⏳ Update environment configuration 6. ⏳ Create deployment documentation 7. ⏳ Test local Docker deployment 8. ⏳ Document LM Studio integration ## Current Focus **Phase**: VAN Mode - Project Initialization **Step**: Creating Memory Bank files and analyzing project structure ## Key Decisions ### Decision 1: LLM Provider Architecture **Decision**: Use Strategy pattern with factory method **Rationale**: - Allows easy switching between OpenAI and LM Studio - No code changes needed to swap providers - Easy to add new providers in future (Anthropic, local Ollama, etc.) **Implementation**: ```typescript interface LLMProvider { chat(messages: Message[]): Promise<string>; embed(text: string): Promise<number[]>; } ``` ### Decision 2: Docker Deployment Strategy **Decision**: Multi-container with Docker Compose **Rationale**: - Separate server and dashboard containers - Same configuration for local and remote - Easy volume management for persistent data - Network isolation **Structure**: - `ace-server`: Main MCP server - `ace-dashboard`: Web interface - Shared volume for contexts - Named network for service communication ### Decision 3: Configuration Management **Decision**: Environment variables with validation **Rationale**: - 12-factor app methodology - Easy to switch between environments - Secure (no secrets in code) - Docker-friendly **Key Variables**: - `LLM_PROVIDER`: 'openai' | 'lmstudio' - `OPENAI_API_KEY`: For OpenAI provider - `LMSTUDIO_BASE_URL`: For LM Studio provider - `ACE_CONTEXT_DIR`: Playbook storage path - `ACE_DEDUP_THRESHOLD`: Similarity threshold ## Work Completed ### Memory Bank Files Created - ✅ `projectbrief.md` - Project overview and objectives - ✅ `techContext.md` - Technical architecture and stack - ✅ `productContext.md` - Product vision and use cases - ✅ `systemPatterns.md` - Design patterns and best practices - ✅ `activeContext.md` - Current task tracking (this file) ### Project Analysis - ✅ Verified existing structure (package.json, tsconfig.json, dashboard) - ✅ Identified missing components (TypeScript source files) - ✅ Analyzed LM Studio API endpoints - ✅ Documented Docker requirements ## Next Steps ### Immediate (Next 30 mins) 1. Create `tasks.md` with detailed implementation checklist 2. Create `progress.md` for tracking 3. Create `style-guide.md` for coding standards 4. Analyze existing package.json dependencies ### Short-term (Next 2-4 hours) 1. Implement LLM provider abstraction layer - Create `src/llm/provider.ts` interface - Create `src/llm/openai.ts` implementation - Create `src/llm/lmstudio.ts` implementation - Update `src/utils/config.ts` for provider selection 2. Create Docker configurations - Write `Dockerfile` for MCP server - Write `Dockerfile` for dashboard - Write `docker-compose.yml` for orchestration - Write `docker-compose.dev.yml` for development - Write `docker-compose.prod.yml` for production 3. Update environment configuration - Enhance `.env.example` with LLM provider settings - Create `.env.development` template - Create `.env.production` template ### Medium-term (Next day) 1. Test implementations - Unit tests for LLM providers - Integration tests with mock LLM - Docker build tests - End-to-end workflow test 2. Documentation - Update installation guide for Docker - Create LM Studio setup guide - Document provider switching process - Create deployment guide for Ubuntu VM ## Open Questions 1. **LM Studio Authentication**: Does LM Studio require API keys? - Answer: No, local server typically doesn't require auth - Action: Make authentication optional for lmstudio provider 2. **Dashboard Docker Port**: What port should dashboard expose? - Proposed: 3000 for development, configurable for production - Action: Use environment variable `DASHBOARD_PORT` 3. **Context Volume Permissions**: How to handle file permissions in Docker? - Action: Use named volume with appropriate user mapping - Document permission setup for Ubuntu VM 4. **MCP Server Transport in Docker**: How does stdio work with Docker? - Answer: MCP server runs on host, accesses Docker via IPC - Alternative: HTTP transport for remote server access - Action: Document both approaches ## Known Issues 1. **TypeScript Source Files Missing**: Need to be implemented based on DESCRIPTION.md - Status: Documented in techContext.md - Priority: High - Next: Will be addressed in implementation phase 2. **No Tests Yet**: Test infrastructure needs to be set up - Status: Will add Jest + ts-jest - Priority: Medium - Next: After core implementation ## Context References ### Files to Review - `/Users/ug/code/perplexity/ace-mcp-server/package.json` - Current dependencies - `/Users/ug/code/perplexity/ace-mcp-server/tsconfig.json` - TypeScript config - `/Users/ug/code/perplexity/ace-mcp-server/.env.example` - Current env template - `/Users/ug/code/perplexity/ace-mcp-server/docs/DESCRIPTION.md` - Full project spec ### External References - LM Studio API: http://10.242.247.136:11888/v1 - MCP Specification: https://modelcontextprotocol.io/specification/2025-06-18 - ACE Paper: Stanford/SambaNova October 2025 ## Communication Notes - User prefers Russian language for communication - Code, comments, and documentation in English - User has LM Studio running at http://10.242.247.136:11888 - User needs both local Docker and Ubuntu VM deployment ## Risk Assessment ### Technical Risks - **Low**: LLM provider abstraction is straightforward - **Low**: Docker setup is standard practice - **Medium**: MCP stdio transport in containerized environment - **Low**: Dashboard containerization ### Mitigation Strategies - Use established patterns (Strategy, Factory) - Test both LLM providers early - Document MCP server connection methods clearly - Provide troubleshooting guides ## Success Criteria This initialization phase is complete when: - ✅ Memory Bank fully populated - [ ] All TypeScript source files implemented - [ ] Docker configurations working locally - [ ] Both LLM providers functional - [ ] Dashboard accessible in Docker - [ ] Documentation updated - [ ] Basic tests passing ## Timeline Estimate - **Initialization Phase**: 1 hour (current) - **Implementation Phase**: 4-6 hours - **Testing Phase**: 2-3 hours - **Documentation Phase**: 1-2 hours - **Total**: ~10 hours for complete implementation ## Last Updated 2025-10-28 - Initial creation during VAN mode initialization