# 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:

```bash
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:

```bash
brew install pipx
pipx ensurepath
```

## Running the MCP server standalone

```bash
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):

```bash
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:

```json
{
  "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:

```bash
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).

```bash
.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.