Context Engine MCP Server
The Context Engine MCP Server is a local-first, agent-agnostic platform for workspace indexing, semantic search, AI-assisted planning, code review, memory management, and security validation.
Workspace Indexing & Retrieval
Index 50+ file types for semantic search (
index_workspace,semantic_search,codebase_retrieval)Retrieve full/partial file contents (
get_file) and token-aware context for AI prompts (get_context_for_prompt)Enhance simple prompts into detailed, codebase-aware prompts (
enhance_prompt)Manage index health: check status, reindex, or clear (
index_status,reindex_workspace,clear_index)
Memory Management
Persist preferences, architecture decisions, and project facts across sessions (
add_memory,list_memories)
Planning & Execution
Generate AI-powered implementation plans with dependency graphs, risk assessments, and Mermaid diagrams (
create_plan,refine_plan,visualize_plan)Execute plan steps with AI-generated code changes, preview or apply (
execute_plan)Save, load, list, and delete plans (
save_plan,load_plan,list_plans,delete_plan)Track step-by-step progress and version history; roll back plan versions (
start_step,complete_step,fail_step,view_progress,view_history,compare_plan_versions,rollback_plan)Gate execution with human approval workflows (
request_approval,respond_approval)
Code Review
AI-powered review of diffs or git changes with structured findings (P0–P3 priority, confidence scores) (
review_changes,review_diff,review_git_diff,review_auto)Reactive PR review with parallel execution, session management, commit-aware caching, and telemetry (
reactive_review_pr,get_review_status,pause_review,resume_review,get_review_telemetry)Deterministic invariant checks against YAML-defined rules (
check_invariants) and static analysis via TypeScript/Semgrep (run_static_analysis)
Security & Validation
Detect and mask 15+ secret types before sending content to an LLM (
scrub_secrets)Multi-tier content validation: bracket balancing, JSON structure, TODO detection, hardcoded URLs, and automatic secret scrubbing (
validate_content)
Tool Discovery
Inspect all available server tools and capabilities (
tool_manifest)
Provides comprehensive tools for automatic retrieval and review of code changes, including staged, unstaged, branch, and commit-level diffs.
Enables the visualization of structured execution plans by generating and displaying Mermaid-formatted diagrams.
Integrates with local static analysis tools like tsc to provide deterministic feedback and analysis during the code review process.
Supports deterministic invariant checking using YAML-based rule files to enforce project-specific constraints during reviews.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Context Engine MCP Server find where the user authentication logic is implemented"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.jsThen in Codex, confirm the tools are visible and try:
use semantic_search to find authentication logicRelated MCP server: LLM Memory MCP Server
Beginner Quick Start
If you just want to get Context Engine running locally, follow these steps:
Install Node.js 18+.
Clone this repository and open it in a terminal at the repo root.
Install dependencies:
npm installBuild the server:
npm run buildRun the verification checks:
npm run verifyStart the MCP server:
node dist/index.jsBy default, Context Engine now resolves the workspace like this:
explicit
--workspacewinsotherwise 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:
First-time setup: Register the MCP server once in your client.
Daily use: Open any repo and let the server resolve the workspace automatically.
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.jsWindows 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.
Run
npm installandnpm run build.Register the MCP server once with
node dist/index.js.Confirm the client launches the MCP server from the repo I am working in.
If the client launches from the wrong folder, add
--workspace <absolute-path-to-workspace>as an override.Confirm the server appears in the client and that
tool_manifest()or an equivalent tool list works.Run one quick retrieval test, for example
semantic_search, to confirm the connection is working.If startup says the workspace is unindexed or stale, let the background indexing finish or run
index_workspacemanually.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=falseforce 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-mcplauncher for convenience; it starts the same server and does not add featuresPersistent 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.jsOptional validation commands:
npm run ci:check:no-legacy-provider
npm run ci:check:legacy-capability-parity
npm run ci:check:legacy-capability-parity:strictDocumentation Quick Links
Docs Map: docs/README.md
Setup: docs/MCP_CLIENT_SETUP.md
Windows Deployment: docs/WINDOWS_DEPLOYMENT_GUIDE.md
Troubleshooting: docs/archive/TROUBLESHOOTING.md
Testing: docs/archive/TESTING.md
Architecture: ARCHITECTURE.md
Memory Operations: docs/MEMORY_OPERATIONS_RUNBOOK.md
Archive: docs/archive/INDEX.md
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 toolsadd_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 choicesdecisions: Architecture decisions, technology choices, design rationalefacts: 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 asreview_findingorfailed_attemptpriority:critical,helpful, orarchivetags,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 RelationshipsARead-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 IndexADestructive
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 PlanBDestructive
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 CallersARead-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 TelemetryARead-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 StatusARead-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 MemoriesARead-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 PlanBRead-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 AutoARead-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 ChangesARead-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:
Basic review: Provide diff content
Focused review: Set categories="security,correctness"
Strict review: Set confidence_threshold=0.8
Include context lines: Set changed_lines_only=false
Inputs: diff (required), base_ref, categories, max_findings, +6 more.
review_diffReview DiffBRead-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 AnalysisARead-onlyIdempotent
Run local static analyzers (tsc and optional semgrep) and return structured findings.
Inputs: task, options, background, changed_files.
scrub_secretsScrub SecretsARead-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 DefinitionARead-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 ManifestARead-onlyIdempotent
Discover available tools and capabilities exposed by the server.
Inputs: no named parameters. Returns: tools, version, features, capabilities, +1 more
validate_contentValidate ContentARead-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 HistoryBRead-onlyIdempotent
View version history for a plan.
Inputs: plan_id (required), limit, include_plans.
view_progressView ProgressBRead-onlyIdempotent
View execution progress for a plan.
Inputs: plan_id (required).
visualize_planVisualize PlanARead-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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA 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.7427 npm6MIT
- AlicenseNot gradedqualityCmaintenanceA local-first, team-ready MCP server providing durable memory for LLM-based coding workflows with multiple storage backends and fast search.4MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.2MIT
- AlicenseNot gradedqualityDmaintenanceLocal-first MCP server for AI coding agents that provides isolated code search, memory ledger, context rot detection, and cost governance.7 npm2MIT