Skip to main content
Glama
Context Engine MCP Server

Context Engine MCP Server

by Kirachon

Context Engine MCP Server

A local-first, agent-agnostic Model Context Protocol (MCP) server for workspace indexing, retrieval, planning, and review workflows, with a setup path that works well for Codex and other OpenAI-powered agents.

New here? Start with the beginner quick start below.

If you want client-specific setup help, see docs/MCP_CLIENT_SETUP.md.

If you are on Windows, see docs/WINDOWS_DEPLOYMENT_GUIDE.md.

Historical docs live in docs/archive/INDEX.md if you need the old planning and migration notes.

OpenAI / Codex Showcase

If you want to see what this project demonstrates for OpenAI-style agent workflows, start here:

  • Local workspace indexing and retrieval

  • Review and planning workflows layered on top of the same MCP server

  • Beginner-friendly install and client setup

  • Windows support and copy-paste setup examples

  • AI-agent-friendly instructions for self-setup

Why This Matters

  • It shows how an OpenAI-powered agent can connect to a real workspace and start using tools right away.

  • It combines retrieval, review, and planning in one MCP server instead of relying on one-off scripts.

  • It gives both humans and AI agents a simple, repeatable setup path, which makes demos and onboarding easier.

Fastest demo path:

npm install
npm run build
codex mcp add context-engine -- node dist/index.js

Then in Codex, confirm the tools are visible and try:

use semantic_search to find authentication logic

Related MCP server: LLM Memory MCP Server

Beginner Quick Start

If you just want to get Context Engine running locally, follow these steps:

  1. Install Node.js 18+.

  2. Clone this repository and open it in a terminal at the repo root.

  3. Install dependencies:

npm install
  1. Build the server:

npm run build
  1. Run the verification checks:

npm run verify
  1. Start the MCP server:

node dist/index.js

By default, Context Engine now resolves the workspace like this:

  • explicit --workspace wins

  • otherwise it uses the current folder

  • if you launched from a nested folder inside a git repo, it falls back to the nearest git root

  • if no git root exists, it stays on the current folder and logs a warning

On first run, if the index is missing or stale, startup can kick off background indexing automatically. The server still starts first, but the first query may be slower until indexing finishes.

Connect It To Your MCP Client

The server speaks MCP over stdio, so most clients can launch it with the same command.

First-Time Setup vs Daily Use

Use this mental model:

  1. First-time setup: Register the MCP server once in your client.

  2. Daily use: Open any repo and let the server resolve the workspace automatically.

  3. Override only when needed: Pass --workspace <absolute-path> if the client launches from the wrong folder or you want a different repo on purpose.

Codex CLI

codex mcp add context-engine -- node dist/index.js

Windows example

codex mcp add context-engine -- node "D:\GitProjects\context-engine\dist\index.js"

Claude Code, Claude Desktop, Cursor, Antigravity

See docs/MCP_CLIENT_SETUP.md for copy-paste config examples for each client.

Ready-to-use sample config files live in examples/mcp-clients/. Optional skill packages for AI workflows live in examples/skills/.

If an AI agent is setting this up

Paste this into the agent if you want it to do the setup for you:

Set up Context Engine MCP for this workspace.

  1. Run npm install and npm run build.

  2. Register the MCP server once with node dist/index.js.

  3. Confirm the client launches the MCP server from the repo I am working in.

  4. If the client launches from the wrong folder, add --workspace <absolute-path-to-workspace> as an override.

  5. Confirm the server appears in the client and that tool_manifest() or an equivalent tool list works.

  6. Run one quick retrieval test, for example semantic_search, to confirm the connection is working.

  7. If startup says the workspace is unindexed or stale, let the background indexing finish or run index_workspace manually.

If the client is Codex CLI, use:

codex mcp add context-engine -- node dist/index.js

Startup Behavior

When the server starts without --workspace, it tries to be repo-aware:

  • repo root launch: uses that repo

  • nested repo folder launch: upgrades to the nearest git root

  • non-git folder launch: stays on the current folder and warns clearly

If startup auto-index is enabled, missing or stale workspaces start background indexing automatically.

Operator override:

  • disable startup auto-index with CE_AUTO_INDEX_ON_STARTUP=false

  • force a specific workspace with --workspace "D:\path\to\repo"

Architecture

This implementation follows a clean 5-layer architecture:

┌────────────────────────────┐
│ Coding Agents (Clients)    │  Layer 4: Codex, 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
┌────────────┴───────────────┐
│ Retrieval + Review Engine  │  Layer 1: local-native runtime
│ (indexing, retrieval)      │
└────────────▲───────────────┘
             │ storage/state
┌────────────┴───────────────┐
│ Local State / Artifacts    │  Layer 5: workspace state + evidence
│ (index, cache, receipts)   │
└────────────────────────────┘

Layer Responsibilities

  • Layer 1: local-native indexing, retrieval, review support, and provider orchestration

  • Layer 2: context assembly, snippet formatting, deduplication, limits, and caching

  • Layer 3: MCP tools, validation, and request/response contracts

  • Layer 4: coding agents and MCP clients that consume the tools

  • Layer 5: persisted index state, caches, rollout receipts, and generated artifacts

Features

MCP Tools

The server exposes tools across these areas:

  • Core context and retrieval

  • Memory

  • Planning and execution

  • Plan management

  • Code review

  • Reactive review

Use tool_manifest() in the MCP server to inspect the current tool inventory directly.

Key Characteristics

  • Local-first runtime for indexing and retrieval, with OpenAI-backed planning/review workflows layered on top

  • Agent-agnostic MCP interface

  • Local-native retrieval provider as the active runtime

  • Thin context-engine-mcp launcher for convenience; it starts the same server and does not add features

  • Persistent state and evidence artifacts for rollout-proof workflows

  • Planning, review, and validation workflows built into the server

  • Optional benchmarking, parity, and governance gates for safer changes

Quick Start

npm install
npm run build
npm run verify
node dist/index.js

Optional validation commands:

npm run ci:check:no-legacy-provider
npm run ci:check:legacy-capability-parity
npm run ci:check:legacy-capability-parity:strict

Current Status

  • Retrieval is local-native and index-backed

  • Planning and review use the OpenAI session path

  • Legacy-provider references that remain are historical docs, tests, or migration guardrails

  • Current hardening focuses on fast paths, cancellation, and prompt efficiency rather than provider replacement

Available Tools

28 tools
add_memoryAdd MemoryA

Store a memory for future sessions. Memories are persisted as markdown files and automatically retrieved via semantic search when relevant.

Categories:

  • preferences: Coding style, tool preferences, personal workflow choices

  • decisions: Architecture decisions, technology choices, design rationale

  • facts: Project facts, environment info, codebase structure

Examples:

  • Add preference: "Prefers TypeScript strict mode"

  • Add decision: "Chose JWT for authentication because..."

  • Add fact: "API runs on port 3000"

Optional metadata fields improve ranking and traceability across sessions:

  • subtype: finer-grained label such as review_finding or failed_attempt

  • priority: critical, helpful, or archive

  • tags, source, linked_files, linked_plans, evidence, owner, timestamps

Memories are stored in .memories/ directory and indexed for semantic retrieval.

Inputs: content (required), category (required), tags, owner, +9 more.

call_relationshipsCall RelationshipsA
Read-onlyIdempotent

Return deterministic local callers and/or callees of a known function or method symbol.

Use this tool when you need to:

  • See which functions invoke a given symbol (callers) and where

  • Inspect which identifiers a function invokes inside its own body (callees)

  • Complement symbol_definition (single declaration site) and symbol_references (non-declaration usages)

Caller heuristic: lines containing ( that are not declaration-like; the nearest enclosing declaration is reported as callerSymbol when detectable. Callee heuristic: locates the symbol's definition and scans the brace-delimited body for identifiers followed by '('. Brace-language only in v1; non-brace bodies (e.g., Python) yield empty callees.

Inputs: symbol (required), top_k, direction, bypass_cache, +4 more. Returns: symbol, callees, callers, metadata, +2 more

clear_indexClear IndexA
Destructive

Remove saved index state and clear caches without rebuilding.

Inputs: no named parameters.

complete_stepComplete StepC

Mark a step as completed with optional notes.

Inputs: plan_id (required), step_number (required), notes, files_modified.

delete_planDelete PlanB
Destructive

Delete a saved plan from storage.

Inputs: plan_id (required).

fail_stepFail StepB

Mark a step as failed with error details.

Inputs: error (required), plan_id (required), step_number (required), skip, +2 more.

find_callersFind CallersA
Read-onlyIdempotent

Return deterministic callers of a known function or method symbol.

This tool prefers persisted graph call edges and falls back explicitly when graph coverage is unavailable or incomplete.

Use when you want call sites for one symbol without the broader combined output of call_relationships.

Inputs: symbol (required), top_k, bypass_cache, exclude_paths, +3 more. Returns: symbol, callers, metadata

get_review_telemetryGet Review TelemetryA
Read-onlyIdempotent

Get detailed telemetry data for a review session.

Returns:

  • Token usage statistics

  • Cache hit/miss rates

  • Execution timing per step

  • Reactive configuration in use

Inputs: session_id (required).

index_statusIndex StatusA
Read-onlyIdempotent

Retrieve current index health metadata (status, last indexed time, file count, staleness).

Inputs: no named parameters. Returns: status, guidance, composite, freshness, +3 more

list_memoriesList MemoriesA
Read-onlyIdempotent

List all stored memories, optionally filtered by category.

Shows file stats, entry counts, and content preview for each memory category.

Inputs: category.

load_planLoad PlanB
Read-onlyIdempotent

Load a previously saved plan by ID or name.

Inputs: name, plan_id.

reactive_review_prReactive Review PRA

Start a reactive PR code review session.

This tool initiates an AI-powered code review with advanced features:

  • Commit-aware caching: Caches context by commit hash for efficiency

  • Parallel execution: Reviews multiple files concurrently

  • Session management: Pause, resume, and track progress

  • Telemetry: Token usage, cache hit rates, execution timing

Environment Variables:

  • REACTIVE_ENABLED=true: Master switch for reactive features

  • REACTIVE_PARALLEL_EXEC=true: Enable parallel execution

  • REACTIVE_MAX_WORKERS=3: Maximum concurrent workers

Returns: Session ID for tracking. Use get_review_status to monitor progress.

Inputs: base_ref (required), commit_hash (required), changed_files (required), title, +4 more.

refine_planRefine PlanA

Refine an existing implementation plan based on feedback or clarifications.

Use this tool to iterate on a plan after reviewing it or answering clarifying questions.

When to use this tool:

  • After reviewing a plan and wanting adjustments

  • To answer questions the plan raised

  • To add more detail to specific steps

  • To change the approach based on new information

Input:

  • The current plan (JSON from a previous create_plan call)

  • Your feedback or clarifications

  • Optionally, specific steps to focus on

Inputs: current_plan (required), feedback, focus_steps, clarifications.

reindex_workspaceReindex WorkspaceA

Clear current index state and rebuild it from scratch.

Inputs: task, background.

request_approvalRequest ApprovalB

Create an approval request for a plan or specific steps.

Inputs: plan_id (required), step_numbers.

respond_approvalRespond ApprovalA

Respond to a pending approval request (approve, reject, or request modifications).

Inputs: action (required), request_id (required), comment, modifications.

review_autoReview AutoA
Read-onlyIdempotent

Smart wrapper that chooses review_diff when a diff is provided; otherwise chooses review_git_diff for the current git workspace.

Inputs: base, diff, task, tool, +7 more.

review_changesReview ChangesA
Read-onlyIdempotent

Review code changes from a diff using AI-powered analysis.

This tool performs a structured code review on a unified diff, identifying issues across correctness, security, performance, maintainability, style, and documentation.

Key Features:

  • Structured output with findings, priority levels (P0-P3), and confidence scores

  • Changed lines filter: focuses on modified code (can be toggled)

  • Confidence scoring: each finding has a 0-1 confidence score

  • Actionable suggestions: includes fix suggestions where applicable

Priority Levels:

  • P0 (Critical): Must fix before merge - bugs, security vulnerabilities

  • P1 (High): Should fix before merge - likely bugs, significant issues

  • P2 (Medium): Consider fixing - code smells, minor issues

  • P3 (Low): Nice to have - style issues, minor improvements

Categories:

  • correctness: Bugs, logic errors, edge cases

  • security: Vulnerabilities, injection risks, auth issues

  • performance: Inefficiencies, memory leaks, N+1 queries

  • maintainability: Code clarity, modularity, complexity

  • style: Formatting, naming conventions

  • documentation: Comments, docstrings, API docs

Output Schema: Returns JSON with: findings[], overall_correctness, overall_explanation, overall_confidence_score, changes_summary, and metadata.

Usage Examples:

  1. Basic review: Provide diff content

  2. Focused review: Set categories="security,correctness"

  3. Strict review: Set confidence_threshold=0.8

  4. Include context lines: Set changed_lines_only=false

Inputs: diff (required), base_ref, categories, max_findings, +6 more.

review_diffReview DiffB
Read-onlyIdempotent

Enterprise-grade diff-first review with deterministic preflight and structured JSON output.

Inputs: diff (required), task, options, base_sha, +3 more.

run_static_analysisRun Static AnalysisA
Read-onlyIdempotent

Run local static analyzers (tsc and optional semgrep) and return structured findings.

Inputs: task, options, background, changed_files.

scrub_secretsScrub SecretsA
Read-onlyIdempotent

Scrub secrets from content before sending to LLM.

Detects and masks 15+ types of secrets:

  • AWS keys, OpenAI/Anthropic API keys

  • GitHub tokens, Stripe keys, Firebase/Supabase keys

  • Private keys (PEM), JWTs, connection strings

  • Generic API keys and passwords

Use this before including user content in prompts.

Inputs: content (required), show_end, show_start.

start_stepStart StepB

Mark a step as in-progress to begin execution.

Inputs: plan_id (required), step_number (required).

symbol_definitionSymbol DefinitionA
Read-onlyIdempotent

Return the single best deterministic declaration site for a known identifier.

Use this tool when you need to:

  • Jump straight to the canonical declaration of a function, class, type, interface, or constant

  • Get one definitive answer (file, line, kind, snippet) rather than a ranked list

  • Complement symbol_search (ranked) and symbol_references (non-declaration usages)

Inputs: symbol (required), bypass_cache, exclude_paths, include_paths, +2 more. Returns: file, kind, line, found, +6 more

tool_manifestTool ManifestA
Read-onlyIdempotent

Discover available tools and capabilities exposed by the server.

Inputs: no named parameters. Returns: tools, version, features, capabilities, +1 more

validate_contentValidate ContentA
Read-onlyIdempotent

Run multi-tier validation on content.

Tier 1 (Deterministic):

  • Balanced brackets/braces

  • Valid JSON structure

  • Non-empty content

Tier 2 (Heuristic):

  • TODO/FIXME detection in code

  • Console statement detection

  • Hardcoded URL detection

  • Line length checks

Also scrubs secrets automatically (can be disabled).

Inputs: content (required), file_path, content_type, scrub_secrets.

view_historyView HistoryB
Read-onlyIdempotent

View version history for a plan.

Inputs: plan_id (required), limit, include_plans.

view_progressView ProgressB
Read-onlyIdempotent

View execution progress for a plan.

Inputs: plan_id (required).

visualize_planVisualize PlanA
Read-onlyIdempotent

Generate diagrams from an implementation plan.

Use this to visualize the plan's structure in different ways.

Diagram types:

  • dependencies: Shows step dependencies as a DAG (who blocks whom)

  • architecture: Shows the architecture diagram if one was generated

  • gantt: Shows steps as a Gantt chart timeline

Returns Mermaid diagram code that can be rendered.

Inputs: plan (required), diagram_type.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools have distinct purposes, but pairs like call_relationships/find_callers and clear_index/reindex_workspace are closely related, potentially causing confusion. Overall descriptions help differentiate, but minor overlaps exist.

    Naming Consistency4/5

    The majority use verb_noun snake_case (e.g., add_memory, complete_step), but a few use noun_noun (index_status, symbol_definition) or adjective_noun (reactive_review_pr), creating slight inconsistency. The pattern is largely predictable.

    Tool Count3/5

    At 28 tools, the server is borderline heavy for a single purpose. The broad 'context engine' scope partially justifies the count, but it feels overloaded compared to well-scoped servers.

    Completeness2/5

    Notable gaps exist: no create_plan tool despite load/delete/refine, and get_review_status is referenced in reactive_review_pr but not provided. Missing lifecycle operations hinder agent workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A local-first MCP server that provides AI agents with safe codebase access through file discovery, hybrid lexical-semantic search, and project introspection. It features durable local memory and semantic indexing while keeping all data and processing entirely on your local machine.
      74
      27 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.
      2
      MIT