ContextPro
# ContextPro
[](https://www.npmjs.com/package/contextpro-mcp)
[](https://github.com/AlaeddineMessadi/contextpro-mcp/actions/workflows/ci.yml)
[](LICENSE)
**Exact find-all-references for your coding agent on TypeScript/JavaScript repos — answered by the TypeScript compiler, not grep.**
ContextPro is a local [MCP](https://modelcontextprotocol.io) server for agents such as Claude Code, Codex, Cursor and OpenCode. Its compiler-backed "find all references" means a rename or refactor is far less likely to miss callers that import the function under another name or through a re-export (within the files the compiler can check). It also serves source reads with a size limit, so the agent gets the lines it needs instead of whole files. It runs on your machine and needs no API key.
## Quick start
Requirements: Node.js 20–26 (24 LTS recommended). No API key or Ollama needed. For compiler references, install the target project's dependencies first (`npm install`); otherwise files can't be checked.
**Fastest try (Claude Code):**
```sh
cd your-project
claude mcp add contextpro -e CONTEXTPRO_TOOL_PROFILE=lean -- npx -y contextpro-mcp
claude mcp list # contextpro: ... ✔ Connected
```
Keep the server name before `-e`, which would otherwise swallow it.
**Claude Code, whole team** (commits `.mcp.json` plus agent instructions in `AGENTS.md` and `CLAUDE.md`):
```sh
npx -y contextpro-mcp init claude
claude # start it in the repository root and approve "contextpro" once
```
**Codex:**
```sh
codex mcp add contextpro --env CONTEXTPRO_TOOL_PROFILE=lean -- npx -y contextpro-mcp
```
Codex starts the server in the folder where you start `codex`, so start it in your project.
**Cursor:** run `npx -y contextpro-mcp init cursor` in your project. It writes `.cursor/mcp.json` with the workspace folder as the root.
**Other clients that read `mcpServers` JSON** (in the project's own config file):
```json
{ "mcpServers": { "contextpro": {
"command": "npx",
"args": ["-y", "contextpro-mcp"],
"env": { "CONTEXTPRO_TOOL_PROFILE": "lean" } } } }
```
Never put a fixed `--root` in a global config: every project would then use that one repository.
**OpenCode:** run `npx -y contextpro-mcp init opencode`, then `opencode mcp list`.
**Try it.** Ask your agent:
- "Use contextpro to find every caller of `<function>` in `<file>`."
- "Use contextpro to show me how `<feature>` works."
[INSTALL.md](INSTALL.md) covers VS Code, team approval, a smoke test that works without any client, running from source and troubleshooting.
## What it is good at
- **Safe renames and refactors.** The compiler tells apart aliased imports, re-exports and different functions that share a name, and the answer says how many results exist and whether any were cut off.
- **Reading just enough source.** The agent asks for a file, a symbol or a line range under a size budget and is told what was left out.
- **Several agents on one repository.** Each Git worktree gets its own index, kept up to date as files change.
- **A small tool list.** The recommended `lean` setup shows the agent three tools (`context`, `exact_references` and `discover_tools`); the other 65 stay hidden until the agent asks for them.
Python references work through a configured Pyright; other languages fall back to structural and text search.
## Honest results
ContextPro has not been shown to make agents finish tasks faster. Our own trials, published in [docs/benchmarks](docs/benchmarks/README.md), include the losses.
It is worth trying for renames and refactors where aliased or re-exported callers matter, or when you don't know where the code lives.
| Measured | Result |
| --- | --- |
| Compiler reference checks on two fixtures (barrel aliases, same-named bindings) | 24 of 24 timed queries passed |
| Response size on six retrieval tasks vs a scripted `rg`/`git` baseline | about 41% fewer response tokens, but about 6.8× slower per call |
| Matched agent trials (2 read-only tasks), lean profile vs native tools | **23.8% more** total input, **19.2% more** wall time |
| Matched agent trials (2 read-only tasks), workflow profile vs native tools | **128.7% more** total input |
For simple lookups, plain grep is cheaper. We welcome reproducible comparisons, including ones where another tool wins; see [how we compare](docs/comparison.md).
## Learn more
- [Install and troubleshoot](INSTALL.md)
- [Agent guide](agent-guide.md): how agents should call the tools, with examples
- [Configuration](docs/configuration.md): tool profiles, providers and environment variables
- [Security model](SECURITY.md): what runs locally and what a hosted provider would see
- [All documentation](docs/README.md) · [Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md)
## License and origins
ContextPro began as a fork of [Context+](https://github.com/ForLoopCodes/contextplus) by ForLoop and has since been largely rewritten. It is distributed under the [MIT license](LICENSE); the original ForLoop copyright notice is preserved, see [NOTICE](NOTICE).
TDQS
Scored across 14 tools
Most tools have clearly distinct roles: grep vs search vs blast_radius vs exact_references are explicitly differentiated by literal/semantic/binding behavior, and status/reindex/task_pack cover separate lifecycle stages. There is still some conceptual overlap among skeleton, explain, artifact_read, and task_pack as ways to retrieve context, but the descriptions give enough guidance to select between them.
All names use snake_case casing, but the semantic pattern is mixed: some are verbs (search, grep, reindex, explain), some are nouns (skeleton, status, task_pack), and others are noun_verb or verb_noun compounds (artifact_read, memory_record_task). The names remain readable, but there is no single predictable verb_noun convention throughout.
At 14 tools, the set is well within a reasonable range for a code-context and analysis server. Each tool appears to serve a distinct workflow: indexing, search, symbol analysis, task packaging, memory, validation, and reporting.
The surface covers index lifecycle, semantic and literal search, reference analysis, symbol extraction, task context assembly, and memory persistence, which is broad for the domain. There are minor gaps: no explicit artifact write/list operation, no direct source-reading/context tool despite being referenced in descriptions, and no separate memory recall/list tool beyond task_pack.