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

🪟 Windows Deployment: docs/WINDOWS_DEPLOYMENT_GUIDE.md

🏗️ Architecture: TECHNICAL_ARCHITECTURE.md for deep technical dive

Architecture

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

┌────────────────────────────┐
│ Coding Agents (Clients)    │  Layer 4: Claude, Cursor, etc.
│ Codex | Claude | Cursor    │
└────────────▲───────────────┘
             │ MCP (tools)
┌────────────┴───────────────┐
│ MCP Interface Layer        │  Layer 3: server.ts, tools/
│ (standardized tool API)    │
└────────────▲───────────────┘
             │ internal API
┌────────────┴───────────────┐
│ Context Service Layer      │  Layer 2: serviceClient.ts
│ (query orchestration)      │
└────────────▲───────────────┘
             │ domain calls
┌────────────┴───────────────┐
│ Core Context Engine        │  Layer 1: Auggie SDK
│ (indexing, retrieval)      │
└────────────▲───────────────┘
             │ storage
┌────────────┴───────────────┐
│ Storage / Index Backend    │  Layer 5: Auggie's internal
│ (vectors, metadata)        │
└────────────────────────────┘

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

review_diff({
  diff: "<unified diff>",
  changed_files: ["src/file.ts"],
  options: {
    enable_static_analysis: true,
    static_analyzers: ["tsc", "semgrep"],
    static_analysis_timeout_ms: 60000
  }
})

Run Static Analysis Standalone

run_static_analysis({
  changed_files: ["src/file.ts"],
  options: {
    analyzers: ["tsc", "semgrep"],
    timeout_ms: 60000,
    max_findings_per_analyzer: 20
  }
})

Check Custom Invariants

check_invariants({
  diff: "<unified diff>",
  changed_files: ["src/file.ts"],
  invariants_path: ".review-invariants.yml"
})

Invariants Configuration

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

invariants:
  - id: no-console-log
    pattern: "console\\.log"
    message: "Remove console.log statements before committing"
    severity: MEDIUM

  - id: no-todo-comments
    pattern: "TODO|FIXME"
    message: "Resolve TODO/FIXME comments"
    severity: LOW

  - id: require-error-handling
    pattern: "catch\\s*\\(\\s*\\)"
    message: "Empty catch blocks should log or handle errors"
    severity: HIGH

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:

{
  "stats": {
    "timings_ms": {
      "preflight": 45,
      "invariants": 12,
      "static_analysis": 3200,
      "context_fetch": 890,
      "secrets_scrub": 5,
      "llm_structural": 1200,
      "llm_detailed": 2400
    }
  }
}

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

create_plan({
  task: "Implement user authentication with JWT tokens",
  generate_diagrams: true
})

2. Save the Plan

save_plan({
  plan: "<plan JSON>",
  name: "JWT Authentication",
  tags: ["auth", "security"]
})

3. Execute Step-by-Step

// Start a step
start_step({ plan_id: "plan_abc123", step_number: 1 })

// Complete it
complete_step({
  plan_id: "plan_abc123",
  step_number: 1,
  notes: "Created User model"
})

// Check progress
view_progress({ plan_id: "plan_abc123" })

4. Track History

// View version history
view_history({ plan_id: "plan_abc123" })

// Compare versions
compare_plan_versions({
  plan_id: "plan_abc123",
  from_version: 1,
  to_version: 2
})

// Rollback if needed
rollback_plan({ plan_id: "plan_abc123", version: 1 })

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

// Store a preference
add_memory({
  category: "preferences",
  content: "Prefers functional programming patterns over OOP"
})

// Store an architecture decision with a title
add_memory({
  category: "decisions",
  title: "Authentication Strategy",
  content: "Chose JWT with refresh tokens for stateless authentication. Sessions were considered but rejected due to horizontal scaling requirements."
})

// Store a project fact
add_memory({
  category: "facts",
  content: "The API uses PostgreSQL 15 with pgvector extension for embeddings"
})

Automatic Memory Retrieval

Memories are automatically included in get_context_for_prompt results when relevant:

// Memories are retrieved alongside code context
const context = await get_context_for_prompt({
  query: "How should I implement authentication?"
})
// Returns: code context + relevant memories about auth decisions

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. Codex CLI - Recommended/default provider path in this documentation:

   codex login
   codex login status

Installation

# Clone or navigate to the repository
cd context-engine

# Install dependencies
npm install

# Build the project
npm run build

Usage

Standalone Mode

Using the Management Script (Windows)

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

# Start the server with indexing and file watching
manage-server.bat start

# Check server status
manage-server.bat status

# Restart the server
manage-server.bat restart

# Stop the server
manage-server.bat stop

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)

# Start server with current directory
node dist/index.js

# Start with specific workspace
node dist/index.js --workspace /path/to/project

# Index workspace before starting
node dist/index.js --workspace /path/to/project --index

# Enable file watcher for automatic incremental indexing (v1.1.0)
node dist/index.js --workspace /path/to/project --watch

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:

{
  "mcpServers": {
    "context-engine": {
      "command": "node",
      "args": [
        "/absolute/path/to/context-engine/dist/index.js",
        "--workspace",
        "/path/to/your/project"
      ]
    }
  }
}

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

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server
npm start

Project Structure

context-engine/
├── src/
│   ├── index.ts              # Entry point with CLI parsing
│   ├── mcp/
│   │   ├── server.ts         # MCP server implementation
│   │   ├── serviceClient.ts  # Context service layer
│   │   ├── tools/
│   │   │   ├── index.ts      # index_workspace tool
│   │   │   ├── search.ts     # semantic_search tool
│   │   │   ├── file.ts       # get_file tool
│   │   │   ├── context.ts    # get_context_for_prompt tool
│   │   │   ├── enhance.ts    # enhance_prompt tool
│   │   │   ├── status.ts     # index_status tool (v1.1.0)
│   │   │   ├── lifecycle.ts  # reindex/clear tools (v1.1.0)
│   │   │   ├── manifest.ts   # tool_manifest tool (v1.1.0)
│   │   │   ├── plan.ts       # Planning tools (v1.4.0)
│   │   │   └── planManagement.ts  # Plan persistence/workflow tools (v1.4.0)
│   │   ├── services/         # Business logic services (v1.4.0)
│   │   │   ├── planningService.ts        # Plan generation, DAG analysis
│   │   │   ├── planPersistenceService.ts # Save/load/list plans
│   │   │   ├── approvalWorkflowService.ts # Approval request handling
│   │   │   ├── executionTrackingService.ts # Step progress tracking
│   │   │   └── planHistoryService.ts     # Version history, rollback
│   │   ├── types/            # TypeScript type definitions (v1.4.0)
│   │   │   └── planning.ts   # Planning-related types
│   │   └── prompts/          # AI prompt templates (v1.4.0)
│   │       └── planning.ts   # Planning system prompts
│   ├── watcher/              # File watching (v1.1.0)
│   │   ├── FileWatcher.ts    # Core watcher logic
│   │   ├── types.ts          # Event types
│   │   └── index.ts          # Exports
│   └── worker/               # Background indexing (v1.1.0)
│       ├── IndexWorker.ts    # Worker thread
│       └── messages.ts       # IPC messages
├── tests/                    # Unit tests (186 tests)
├── plan.md                   # Architecture documentation
├── package.json
├── tsconfig.json
└── README.md

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

Windows PATH fallback example: CE_OPENAI_SESSION_CMD=cmd and CE_OPENAI_SESSION_ARGS_JSON=["/d","/s","/c","D:\\npm-global\\codex.cmd"] | CE_SKIP_UNCHANGED_INDEXING | Skip re-indexing unchanged files (requires CE_INDEX_STATE_STORE=true) | false | | CE_HASH_NORMALIZE_EOL | Normalize CRLF/LF when hashing (recommended with state store across Windows/Linux) | false | | CE_METRICS | Enable in-process metrics collection (Prometheus format) | false | | CE_HTTP_METRICS | Expose GET /metrics when running with --http | false | | CE_AI_REQUEST_TIMEOUT_MS | Default timeout for AI calls (searchAndAsk) in milliseconds | 120000 | | CE_SEMANTIC_EMPTY_ARRAY_COMPAT_FALLBACK | Compatibility mode: when true, explicit provider [] re-enables local keyword fallback | false | | CE_SEARCH_AND_ASK_QUEUE_MAX | Max queued searchAndAsk requests before rejecting (0 = unlimited) | 50 | | CE_TSC_INCREMENTAL | Enable incremental tsc runs for static analysis | true | | CE_TSC_BUILDINFO_DIR | Directory to store tsbuildinfo cache (defaults to OS temp) | (os tmp) | | CE_SEMGREP_MAX_FILES | Max files per semgrep invocation before chunking | 100 | | CE_PLAN_AI_REQUEST_TIMEOUT_MS | Timeout for planning AI calls in milliseconds (create_plan, refine_plan, step execution) | 300000 | | CE_HTTP_PLAN_TIMEOUT_MS | HTTP POST /api/v1/plan request timeout in milliseconds | 360000 |

Metrics (optional)

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

export CE_METRICS=true
export CE_HTTP_METRICS=true
node dist/index.js --workspace /path/to/project --http --port 3333

Then fetch:

curl http://localhost:3333/metrics

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:

export CONTEXT_ENGINE_OFFLINE_ONLY=true

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 codex login and codex login status.

No search results

Index your workspace first:

node dist/index.js --workspace /path/to/project --index

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. Verify that CONTEXT_ENGINE_OFFLINE_ONLY is not inherited by your shell/service process

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:

[mcp_servers.context-engine]
command = "node"
args = ["/absolute/path/to/context-engine/dist/index.js", "--workspace", "/path/to/your/project"]
tool_timeout_sec = 600  # 10 minutes for complex planning tasks

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

# Run all tests
npm test

# Quieter ESM run (use if you see pipe/stream errors)
node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand --silent

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Interactive MCP testing
npm run inspector

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

License

MIT