Context Engine MCP Server

A local-first, agent-agnostic Model Context Protocol (MCP) server implementation using the Auggie SDK as the core context engine.

📚 New here? Check out INDEX.md for a complete documentation guide!

🚀 Quick Start: QUICKSTART.md → GETTING_STARTED.md → API_REFERENCE.md

🏗️ Architecture: TECHNICAL_ARCHITECTURE.md for deep technical dive

Architecture

This implementation follows a clean 5-layer architecture as outlined in plan.md:

Layer Responsibilities

• Layer 1 (Core Engine): Auggie SDK handles file ingestion, chunking, embedding, and semantic retrieval

• Layer 2 (Service): Orchestrates context, formats snippets, deduplicates, enforces limits

• Layer 3 (MCP Interface): Exposes tools, validates I/O, maps calls to service layer

• Layer 4 (Agents): Consume context and generate responses

• Layer 5 (Storage): Persists embeddings and metadata

Features

MCP Tools (41 tools available)

Core Context Tools (10)

1. index_workspace(force?) - Index workspace files for semantic search

   • force (optional): Force re-indexing even if files haven't changed

2. codebase_retrieval(query, top_k?) - PRIMARY semantic search with JSON output for programmatic use

   • query: Natural language search query

   • top_k (optional): Number of results to return (default: 5)

3. semantic_search(query, top_k?, mode?, bypass_cache?, timeout_ms?) - Semantic code search with markdown-formatted output

   • query: Natural language search query

   • top_k (optional): Number of results to return (default: 5)

   • mode (optional): "fast" (default) or "deep" for higher recall at higher latency

   • bypass_cache (optional): When true, bypass caches for this call

   • timeout_ms (optional): Cap time spent in retrieval pipeline (ms)

4. get_file(path) - Retrieve complete file contents

   • path: Relative path to file from workspace root

5. get_context_for_prompt(query, max_files?, token_budget?, include_related?, min_relevance?, bypass_cache?) - Get comprehensive context bundle for prompt enhancement

   • query: Context request description

   • max_files (optional): Maximum files to include (default: 5)

   • token_budget (optional): Token budget for the bundle (default: 8000)

   • include_related (optional): Include related/imported files (default: true)

   • min_relevance (optional): Minimum relevance score (default: 0.3)

   • bypass_cache (optional): When true, bypass caches for this call

6. enhance_prompt(prompt) - AI-powered prompt enhancement with codebase context

   • prompt: Simple prompt to enhance

7. index_status() - View index health metadata (status, fileCount, lastIndexed, isStale)

8. reindex_workspace() - Clear and rebuild the entire index from scratch

9. clear_index() - Remove index state without rebuilding

10. tool_manifest() - Discovery tool for available capabilities

Memory System (2)

11. add_memory(category, content, title?) - Store persistent memories for future sessions

    • category: 'preferences', 'decisions', or 'facts'

    • content: The memory content to store (max 5000 characters)

    • title (optional): Title for the memory

12. list_memories(category?) - List all stored memories

    • category (optional): Filter to a specific category

Planning & Execution (4)

13. create_plan(task, options?) - Generate structured execution plans with DAG analysis

    • task: Task or goal to plan for

    • generate_diagrams (optional): Generate Mermaid diagrams (default: true)

14. refine_plan(current_plan, feedback?, clarifications?) - Refine existing plans based on feedback

15. visualize_plan(plan, diagram_type?) - Generate visual representations (Mermaid diagrams)

16. execute_plan(plan, ...) - Execute plan steps with AI-powered code generation

Plan Management (13)

17. save_plan(plan, name?, tags?, overwrite?) - Save plans to persistent storage

18. load_plan(plan_id \| name) - Load previously saved plans

19. list_plans(status?, tags?, limit?) - List saved plans with filtering

20. delete_plan(plan_id) - Delete saved plans from storage

21. request_approval(plan_id, step_numbers?) - Create approval requests for plans or specific steps

22. respond_approval(request_id, action, comments?) - Respond to approval requests

23. start_step(plan_id, step_number) - Mark a step as in-progress

24. complete_step(plan_id, step_number, notes?, files_modified?) - Mark a step as completed

25. fail_step(plan_id, step_number, error, ...) - Mark a step as failed

26. view_progress(plan_id) - View execution progress and statistics

27. view_history(plan_id, limit?, include_plans?) - View version history of a plan

28. compare_plan_versions(plan_id, from_version, to_version) - Generate diff between versions

29. rollback_plan(plan_id, version, reason?) - Rollback to a previous plan version

Code Review (5)

30. review_changes(diff, file_contexts?, options?) - AI-powered code review with structured output

31. review_git_diff(target?, base?, include_patterns?, options?) - Review code changes from git automatically

32. review_diff(diff, changed_files?, options?) - Enterprise review with risk scoring and static analysis

    • Risk scoring (1-5) based on deterministic preflight

    • Change classification (feature/bugfix/refactor/infra/docs)

    • Optional static analysis (TypeScript, Semgrep)

    • Per-phase timing telemetry

33. check_invariants(diff, changed_files?, invariants_path?) - Run YAML invariants deterministically (no LLM)

34. run_static_analysis(changed_files?, options?) - Run local static analyzers (tsc, semgrep)

Reactive Review (7)

35. reactive_review_pr(...) - Start a session-based, parallelized code review

36. get_review_status(session_id) - Track progress of a reactive review

37. pause_review(session_id) - Pause a running review session

38. resume_review(session_id) - Resume a paused session

39. get_review_telemetry(session_id) - Detailed metrics (tokens, speed, cache hits)

40. scrub_secrets(content) - Mask API keys and sensitive data

41. validate_content(content, content_type, ...) - Multi-tier validation for AI-generated content

Key Characteristics

• ✅ Local-first: No cloud dependencies, no exposed ports, no data leakage

• ✅ Agent-agnostic: Works with any MCP-compatible coding agent

• ✅ LLM-agnostic: No LLM-specific logic in the engine

• ✅ Storage-agnostic: Auggie SDK handles storage abstraction

• ✅ Extensible: Clean separation allows easy feature additions

• ✅ Real-time watching: Automatic incremental indexing on file changes (v1.1.0)

• ✅ Background indexing: Non-blocking indexing via worker threads (v1.1.0)

• ✅ Offline policy: Enforce local-only operation with environment variable (v1.1.0)

• ✅ Planning mode: AI-powered implementation planning with DAG analysis (v1.4.0)

• ✅ Execution tracking: Step-by-step execution with dependency management (v1.4.0)

• ✅ Version control: Plan versioning with diff and rollback support (v1.4.0)

• ✅ Approval workflows: Built-in approval system for plans and steps (v1.4.0)

• ✅ Defensive programming: Comprehensive null/undefined handling (v1.4.1)

• ✅ Cross-session memory: Persistent memory system for preferences, decisions, and facts (v1.4.1)

• ✅ AI-powered code review: Structured code review with confidence scoring and priority levels (v1.7.0)

• ✅ Git integration: Automatic diff retrieval for staged, unstaged, branch, and commit changes (v1.7.0)

• ✅ Reactive Optimization: 180-600x faster reactive reviews via AI Agent Executor, Multi-layer Caching, Batching, and Worker Pool Optimization (v1.8.0)

• ✅ High Availability: Circuit breakers, adaptive timeouts, and zombie session detection (v1.8.0)

• ✅ Static analysis integration: Optional TypeScript and Semgrep analyzers for deterministic feedback (v1.9.0)

• ✅ Invariants checking: YAML-based custom rules for deterministic code review (v1.9.0)

• ✅ Per-phase telemetry: Detailed timing breakdowns for review pipeline optimization (v1.9.0)

Reactive Review Optimizations (v1.8.0)

Version 1.8.0 introduces massive performance improvements to the reactive code review system, reducing review times from 30-50 minutes to 3-15 seconds for typical PRs.

Optimization Stack

Total Performance Improvement

Static Analysis & Invariants (v1.9.0)

Version 1.9.0 introduces optional static analysis and deterministic invariants checking for enhanced code review capabilities.

Static Analysis Features

Usage

Enable Static Analysis in review_diff

Run Static Analysis Standalone

Check Custom Invariants

Invariants Configuration

Create .review-invariants.yml in your workspace root:

Benefits

• ✅ Deterministic: No LLM required for invariants/static analysis

• ✅ Fast: Local execution, no API calls

• ✅ CI-Friendly: Structured JSON output suitable for CI/CD pipelines

• ✅ Customizable: YAML-based rules, configurable analyzers

• ✅ Opt-in: Disabled by default, enable as needed

Per-Phase Telemetry

The review_diff tool now reports detailed timing breakdowns in stats.timings_ms:

This allows you to:

• Identify performance bottlenecks in the review pipeline

• Optimize timeout settings for your workflow

• Monitor static analysis overhead

• Track LLM usage patterns

Planning Workflow (v1.4.0+)

The Context Engine now includes a complete planning and execution system:

1. Create a Plan

2. Save the Plan

3. Execute Step-by-Step

4. Track History

See EXAMPLES.md for complete planning workflow examples.

Memory System (v1.4.1)

The Context Engine includes a cross-session memory system that persists preferences, decisions, and project facts across sessions.

Memory Categories

Adding Memories

Automatic Memory Retrieval

Memories are automatically included in get_context_for_prompt results when relevant:

Memory Files

Memories are stored in .memories/ as markdown files:

• preferences.md - Coding style preferences

• decisions.md - Architecture decisions

• facts.md - Project facts

These files are human-editable and can be version controlled with Git.

Prerequisites

1. Node.js 18+

2. Auggie CLI - Install globally:

   npm install -g @augmentcode/auggie

3. Authentication - Run auggie login or set environment variables:

   export AUGMENT_API_TOKEN="your-token" export AUGMENT_API_URL="https://api.augmentcode.com"

Installation

Usage

Standalone Mode

Using the Management Script (Windows)

For Windows users, a convenient batch file is provided for managing the server:

The management script automatically:

• Uses the current directory as workspace

• Enables indexing (--index)

• Enables file watching (--watch)

• Logs output to .server.log

• Tracks the process ID in .server.pid

Manual Start (All Platforms)

CLI Options

With Codex CLI

1. Build the project:

   npm run build

2. Add the MCP server to Codex CLI:

   codex mcp add context-engine -- node /absolute/path/to/context-engine/dist/index.js --workspace /path/to/your/project

   Or edit ~/.codex/config.toml directly:

   [mcp_servers.context-engine] command = "node" args = [ "/absolute/path/to/context-engine/dist/index.js", "--workspace", "/path/to/your/project" ]

3. Restart Codex CLI

4. Type /mcp in the TUI to verify the server is connected

With Other MCP Clients (Antigravity, Claude Desktop, Cursor)

For other MCP clients, add this server to your client's MCP configuration:

See QUICKSTART.md - Step 5B for detailed instructions for each client.

Development

Project Structure

Example Usage

Once connected to Codex CLI, you can use natural language:

• "Search for authentication logic in the codebase"

• "Show me the database schema files"

• "Get context about the API endpoints"

• "Find error handling patterns"

The server will automatically use the appropriate tools to provide relevant context.

Environment Variables

Metrics (optional)

To expose a Prometheus-style endpoint, start the server in HTTP mode and enable both flags:

Then fetch:

Notes:

• Metrics are intended to use low-cardinality labels (avoid per-query/per-path labels).

• The in-process registry caps total series to prevent unbounded memory growth.

Offline-Only Mode (v1.1.0)

To enforce that no data is sent to remote APIs, set:

When enabled, the server will fail to start if a remote API URL is configured. This is useful for enterprise environments with strict data locality requirements.

Troubleshooting

Server not showing up in Codex CLI

1. Check ~/.codex/config.toml for syntax errors

2. Ensure paths are absolute

3. Restart Codex CLI

4. Run codex mcp list to see configured servers

5. Use /mcp command in the TUI to check connection status

Authentication errors

Run auggie login or verify environment variables are set correctly.

No search results

Index your workspace first:

File watcher not detecting changes (v1.1.0)

1. Ensure you started the server with --watch flag

2. Check that the file is not in .gitignore or .contextignore

3. Wait for the debounce period (default: 500ms) after the last change

4. Check server logs for watcher status messages

Offline-only mode blocking startup (v1.1.0)

If you see an error about offline-only mode:

1. Remove the CONTEXT_ENGINE_OFFLINE_ONLY environment variable, or

2. Configure a localhost API URL in AUGMENT_API_URL

Tool timeout errors during plan generation (v1.4.0)

The create_plan tool can take longer than default MCP client timeouts for complex tasks. If you experience timeout errors, increase the timeout in your MCP client configuration:

For Codex CLI

Edit ~/.codex/config.toml and add or modify the tool_timeout_sec setting under the [mcp_servers.context-engine] section:

For Other MCP Clients

Consult your client's documentation for timeout configuration. Common locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

• Cursor: .cursor/mcp.json in your workspace

• Antigravity: Check client-specific configuration files

Add a timeout setting appropriate for your client's configuration format. A value of 600 seconds (10 minutes) is recommended for complex planning tasks.

Testing

Test Status: 397 tests passing (100% completion) ✅

License

MIT