MCP Intelligence Context

A Repository Intelligence MCP server that indexes a codebase's files, symbols, imports and dependency graph, and hands Copilot/agents a small, focused context package instead of making them scan the entire repository.

Why

When an agent gets an ambiguous question about a large repo, it often has to repeatedly list directories, open unrelated files, and re-derive structure before finding the relevant code — burning tokens and time. This project builds a persistent, incrementally-updated index of the repo (files, symbols, imports, reverse dependencies) and exposes MCP tools that return only the context relevant to a query, with an approximate token budget.

How it works

1. index_repository walks the repo (honoring .gitignore), parses Python (via ast) and JS/TS (via lightweight regex heuristics) files for functions/classes/methods/imports/exports, and builds a reverse dependency graph. The index is cached at .mcp_intel_cache/index.json and refreshed incrementally (only changed files are re-parsed, based on mtime/size).
2. search_code / get_relevant_context rank files by symbol-name, filename, docstring/summary, and import matches (lexical/symbol search — no embeddings in this MVP) and return a token-budgeted context package: symbol tables + small code excerpts, not whole files. get_relevant_context also reports a token_savings comparison against a naive full-repo-scan baseline, so the savings are visible in the tool's own response.
3. get_file_summary / get_dependencies let an agent drill into a specific file's symbols or blast radius (importers/imports) without reading the whole file.
4. Tools report a staleness warning if the cached index is older than 5 minutes and no live watcher is active. In practice, the first tool call for a repo starts a background file watcher (via watchdog) that applies create/modify/delete events to the in-memory index immediately, so the index stays continuously up to date as the code changes — no manual reindex needed during a session. The on-disk cache is flushed on a debounce (~2s) so rapid saves don't cause a write per keystroke.

Repository layout

src/mcp_intelligence_context/   Python MCP server package
  walker.py                     gitignore-aware file walker
  parsers/                      Python (ast) and JS/TS (regex) symbol extraction
  indexer.py                    builds/caches the RepoIndex, resolves imports
  watcher.py                    background file watcher that keeps the index live
  search.py                     lexical/symbol search + reverse-dep lookups
  context_builder.py            token-budgeted context package assembly
  server.py                     MCP tool definitions (stdio server)
vscode-extension/                VS Code extension wrapper (setup/reindex/status commands)
scripts/                         one-command bootstrap for new users

Quick Start (New Users)

If you are new to MCP and just want this working in VS Code quickly:

git clone https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git
cd MCP-INTELLIGENCE-CONTEXT
bash scripts/setup_mcp_workspace.sh

What this script does:

1. Installs (or updates) mcp-intelligence-context with pipx.
2. Writes .vscode/mcp.json for this workspace.
3. Restricts indexing to the current workspace folder by setting MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder}.

Then in VS Code:

1. Command Palette -> MCP: List Servers.
2. Start/Restart mcp-intelligence-context.
3. In Copilot Chat tool picker, enable mcp-intelligence-context.

If the script says pipx is missing, install it once:

brew install pipx
pipx ensurepath

Running the MCP server standalone

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context        # or: python -m mcp_intelligence_context.server

Point the repo to index by setting MCP_INTEL_REPO_ROOT, or pass repo_root explicitly to any tool call (defaults to the server's current working directory).

Installing without cloning this repo

Other users don't need a local checkout — install directly from the git repository (or from PyPI, once published there):

python3 -m venv .venv
.venv/bin/pip install "git+https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git"
# once published: .venv/bin/pip install mcp-intelligence-context

The mcp-intelligence-context console script and MCP_INTEL_REPO_ROOT env var work exactly the same either way — only the pip install source differs.

Register with an MCP client (e.g. VS Code)

Add to .vscode/mcp.json in the target workspace:

{
  "servers": {
    "mcp-intelligence-context": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_intelligence_context.server"],
      "env": { "MCP_INTEL_REPO_ROOT": "${workspaceFolder}" }
    }
  }
}

VS Code extension

vscode-extension/ bundles a thin wrapper with three commands:

• MCP Intelligence: Setup Server — creates a venv and installs the Python package, then writes the .vscode/mcp.json entry above.
• MCP Intelligence: Reindex Repository — forces a re-index of the open workspace.
• MCP Intelligence: Show Status — prints the cached index's file count, git commit, and age.

By default, "Setup Server" installs the package from this project's git repository into a venv under the extension's private storage — no local clone required. Two settings control this:

• mcpIntelligenceContext.serverPath — point at a local editable checkout (used for development on this monorepo); leave empty otherwise.
• mcpIntelligenceContext.pythonPackageSource — override the pip install target (e.g. a PyPI package name) when serverPath is empty.

To build it:

cd vscode-extension
npm install
npm run compile

Then press F5 in VS Code (with vscode-extension/ open) to launch an Extension Development Host.

Available MCP tools

Tool	Purpose
index_repository	Build/refresh the index for a repo root
get_repo_overview	Top-level directories, language breakdown, core modules
search_code	Ranked file/symbol hits for a query
get_file_summary	Symbol table, imports, exports for one file
get_dependencies	What a file imports and who imports it
get_relevant_context	Token-budgeted context package for a query, plus a token_savings estimate vs. a naive full-repo scan

Evaluating whether this actually helps

eval/ contains a small, honest benchmark against this repo's own code (no LLM calls, no fabricated numbers): 10 hand-written queries with known ground-truth files, comparing our indexed tool against a naive baseline (list the tree, grep, read whole matching files).

.venv/bin/python eval/run_eval.py

It reports hit@1/hit@3 (does the top result point at the right file), average token reduction, and latency. This only measures retrieval/token mechanics — it does not measure whether a real Copilot answer is actually better, since that requires live model calls.

Current limitations (MVP)

• JS/TS parsing is regex-based (not a full AST), so unusual syntax may be missed. Python parsing uses the standard ast module and is exact.
• Search is lexical/symbol-based only (with stopword filtering and accumulated multi-signal scoring); no embeddings/semantic search yet.
• The file watcher applies per-file changes but does not re-walk .gitignore changes themselves at runtime — if .gitignore is edited, run index_repository with refresh=true once to pick up the new rules.

Security considerations before broader/production use

Already fixed:

• Shell injection — the VS Code extension previously interpolated workspace settings into shell command strings; it now uses execFile with argument arrays (no shell), and refuses to run "Setup Server" in untrusted workspaces.
• Symlink escape — the walker skips symlinks that resolve outside the repo root (blocks a planted symlink from exposing files like /etc/passwd).
• Secret leakage — filenames matching common credential patterns (.env, *.pem, id_rsa, credentials.json, etc., see SENSITIVE_FILENAME_PATTERNS in config.py) are skipped even if not gitignored, so their contents can't end up in tool output.
• Corrupted-cache crash — a malformed/tampered .mcp_intel_cache/index.json now triggers a clean rebuild instead of crashing the server on launch.
• ReDoS — the JS/TS regex parser skips pathologically long single lines (minified files) to avoid catastrophic-backtracking DoS.
• Unrestricted repo_root — set MCP_INTEL_ALLOWED_ROOTS (a :-separated list of absolute paths) to restrict which directories the server will index; unset by default to preserve today's flexible single-user behavior.

Still architectural, not fully solved — read before deploying beyond a single local user:

• Not safe as a shared/multi-tenant network service. This is designed as a local, one-process-per-user stdio server. The in-memory index/watcher caches have no per-user isolation or authentication. Do not expose this as a shared HTTP/SSE endpoint without adding per-caller sandboxing and auth.
• Dependencies are unpinned (>= only) — pin exact versions or use a lock file for reproducible, vetted production installs (this already bit us once with an mcp 1.x → 2.0 breaking API change).
• No automated regression tests for this codebase itself yet — changes are currently verified via the manual eval/ harness and ad hoc runs, not a CI-gated test suite.