# Context Engine MCP Server - Comprehensive Project Summary
## 🎯 Project Overview
**Context Engine** is a local-first, agent-agnostic Model Context Protocol (MCP) server that provides semantic code search and AI-powered planning capabilities to coding agents like Claude, Cursor, and Codex.
### Key Characteristics
- **Local-First**: All processing happens on your machine - no cloud dependencies
- **Agent-Agnostic**: Works with any MCP-compatible coding agent
- **Production-Ready**: 222 passing tests, comprehensive error handling, full TypeScript support
- **Extensible**: Clean 5-layer architecture with well-defined interfaces
## 📊 Project Statistics
- **Total Tools**: 29 MCP tools across 6 categories
- **Test Coverage**: 222 tests passing (100% pass rate)
- **Lines of Code**: ~15,000+ lines of TypeScript
- **Dependencies**: Built on Auggie SDK (@augmentcode/auggie)
- **Version**: 1.5.0 (latest)
## 🏗️ Architecture
### 5-Layer Architecture
```
┌─────────────────────────────┐
│ Layer 4: Coding Agents │ Claude, Cursor, Codex
│ (MCP Clients) │
└──────────────┬──────────────┘
│ MCP Protocol
┌──────────────┴──────────────┐
│ Layer 3: MCP Interface │ server.ts, tools/*
│ (Tool Definitions) │
└──────────────┬──────────────┘
│ Internal API
┌──────────────┴──────────────┐
│ Layer 2: Service Layer │ serviceClient.ts, services/*
│ (Business Logic) │
└──────────────┬──────────────┘
│ SDK Calls
┌──────────────┴──────────────┐
│ Layer 1: Auggie SDK │ @augmentcode/auggie
│ (Core Engine) │
└──────────────┬──────────────┘
│ File System
┌──────────────┴──────────────┐
│ Layer 5: Storage │ .augment-context-state.json
│ (Persistence) │
└─────────────────────────────┘
```
### Key Components
#### Layer 1: Core Engine (Auggie SDK)
- File ingestion and chunking
- Embedding generation
- Vector search
- Metadata management
#### Layer 2: Service Layer
**Main Services:**
1. `ContextServiceClient` - Core context operations
2. `PlanningService` - AI-powered plan generation
3. `PlanPersistenceService` - Plan storage and retrieval
4. `ExecutionTrackingService` - Step-by-step execution tracking
5. `ApprovalWorkflowService` - Built-in approval system
6. `PlanHistoryService` - Version control for plans
#### Layer 3: MCP Interface
**Tool Categories:**
1. Core Context Tools (6 tools)
2. Index Management Tools (4 tools)
3. Planning Tools (4 tools)
4. Plan Persistence Tools (4 tools)
5. Approval Workflow Tools (2 tools)
6. Execution Tracking Tools (4 tools)
7. History & Versioning Tools (3 tools)
8. Memory Tools (2 tools)
#### Layer 4: Transport Layers
1. **stdio Transport** - For MCP clients (Claude Desktop, Codex)
2. **HTTP Transport** - For VS Code extension and web clients
## 🛠️ Available Tools (29 Total)
### Core Context Tools
1. `index_workspace` - Index workspace files
2. `codebase_retrieval` - Semantic search (JSON output)
3. `semantic_search` - Semantic search (Markdown output)
4. `get_file` - Retrieve file contents
5. `get_context_for_prompt` - Get context bundle
6. `enhance_prompt` - AI-powered prompt enhancement
### Index Management Tools
7. `index_status` - View index health
8. `reindex_workspace` - Rebuild index
9. `clear_index` - Clear index state
10. `tool_manifest` - List all capabilities
### Planning Tools (v1.4.0+)
11. `create_plan` - Generate implementation plans
12. `refine_plan` - Refine existing plans
13. `visualize_plan` - Generate Mermaid diagrams
14. `execute_plan` - Execute plan steps with AI code generation
### Plan Persistence Tools (v1.4.0+)
15. `save_plan` - Save plans to storage
16. `load_plan` - Load saved plans
17. `list_plans` - List all saved plans
18. `delete_plan` - Delete saved plans
### Approval Workflow Tools (v1.4.0+)
19. `request_approval` - Request approval for plans/steps
20. `respond_approval` - Approve/reject/request changes
### Execution Tracking Tools (v1.4.0+)
21. `start_step` - Mark step as in-progress
22. `complete_step` - Mark step as complete
23. `fail_step` - Mark step as failed
24. `view_progress` - View execution progress
### History & Versioning Tools (v1.4.0+)
25. `view_history` - View plan version history
26. `compare_plan_versions` - Compare plan versions
27. `rollback_plan` - Rollback to previous version
### Memory Tools (v1.4.1+)
28. `add_memory` - Store persistent memories
29. `list_memories` - List stored memories
## 📁 Project Structure
```
context-engine/
├── src/
│ ├── index.ts # Entry point
│ ├── mcp/
│ │ ├── server.ts # MCP server (Layer 3)
│ │ ├── serviceClient.ts # Context service (Layer 2)
│ │ ├── services/ # Business logic services
│ │ │ ├── planningService.ts
│ │ │ ├── planPersistenceService.ts
│ │ │ ├── executionTrackingService.ts
│ │ │ ├── approvalWorkflowService.ts
│ │ │ └── planHistoryService.ts
│ │ ├── tools/ # MCP tool definitions
│ │ │ ├── search.ts
│ │ │ ├── file.ts
│ │ │ ├── context.ts
│ │ │ ├── plan.ts
│ │ │ ├── planManagement.ts
│ │ │ └── memory.ts
│ │ └── types/ # TypeScript types
│ ├── http/ # HTTP transport layer
│ │ ├── httpServer.ts
│ │ ├── middleware/
│ │ └── routes/
│ ├── watcher/ # File watching
│ └── worker/ # Background workers
├── tests/ # 222 passing tests
├── vscode-extension/ # VS Code extension
└── docs/ # Documentation
```
## 🚀 Key Features
### 1. Semantic Code Search
- Natural language queries
- Context-aware results
- Relevance scoring
- Deduplication
### 2. AI-Powered Planning
- Generate implementation plans from tasks
- DAG-based dependency analysis
- Mermaid diagram generation
- Step-by-step execution
### 3. Plan Management
- Persistent storage
- Version control
- Approval workflows
- Execution tracking
### 4. Memory System
- Store coding preferences
- Track architectural decisions
- Remember project facts
### 5. VS Code Extension
- Chat panel with context
- CodeLens integration
- Status monitoring
- Health checks
## 📈 Version History
- **v1.0.0** - Initial release with core context tools
- **v1.1.0** - Added index management tools
- **v1.2.0** - Added codebase_retrieval tool
- **v1.3.0** - Added HTTP transport layer
- **v1.4.0** - Added planning tools and plan management
- **v1.4.1** - Added memory tools
- **v1.5.0** - Internal refactoring and optimization
## 🎓 Use Cases
1. **Code Understanding** - Ask questions about your codebase
2. **Feature Planning** - Generate implementation plans
3. **Code Generation** - AI-powered code changes
4. **Refactoring** - Plan and execute refactoring tasks
5. **Documentation** - Generate documentation from code
6. **Testing** - Find and update tests
## 🔧 Technical Highlights
- **TypeScript** - Full type safety
- **Jest** - Comprehensive test suite
- **MCP SDK** - Official Model Context Protocol
- **Auggie SDK** - Production-grade context engine
- **Express** - HTTP server for VS Code
- **Chokidar** - File watching
- **Zod** - Runtime validation
## 📚 Documentation
- `README.md` - Quick start guide
- `ARCHITECTURE.md` - Detailed architecture
- `INDEX.md` - Documentation index
- `PLANNING_WORKFLOW.md` - Planning feature guide
- `TESTING.md` - Testing guide
- `TROUBLESHOOTING.md` - Common issues
## 🎯 Current Status
✅ **Production Ready**
- All 222 tests passing
- Comprehensive error handling
- Full TypeScript support
- Complete documentation
- VS Code extension available
## 🔮 Future Enhancements
Potential areas for expansion:
- Additional diagram types
- More execution modes
- Enhanced approval workflows
- Team collaboration features
- Cloud sync options
