contextpro-mcp 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are recorded here. The project follows [Sema
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-31
+
+- `contextpro-mcp --help` and `--version` print usage and the version instead of starting a server on a folder named after the flag. Unknown options and a `--root` that does not exist now fail with a one-line error instead of creating directories.
+- `init` writes a minimal config (`CONTEXTPRO_TOOL_PROFILE=lean`, no Ollama settings). `init vscode` uses VS Code's `servers` format, and `init vscode`/`init cursor` pass `--root ${workspaceFolder}`; an unexpanded `${...}` root falls back to the launch directory.
+- A Git repository directly inside the home folder (for example `~/myapp`) is accepted as a project root.
+- ContextPro writes `.contextpro/.gitignore`, so its local index state stays out of Git without editing the project's `.gitignore`.
+- An empty `exact_references` result is labelled unverified when the compiler could not check some files, with a hint to install the project's dependencies.
+- The README is now a one-minute quick start with verified commands for Claude Code, Codex, Cursor and OpenCode; internals moved to the configuration and agent guides.
+
 ## [1.4.0] - 2026-10-29
 
 - Upgraded zod to 4.6.7 to resolve GHSA-mrhx-c7xc-m3w5 (memory exhaustion when validating oversized constrained collections); tool behavior is unchanged, and nested object schemas are now advertised without `additionalProperties: false`.

package/INSTALL.md

@@ -1,110 +1,197 @@
 # Install ContextPro
 
-These instructions target the current checkout. Use the local build to get changes under review; do not assume an npm package with the same version contains them. Use Node.js 24 LTS and npm; the package engine range is 20–26. Install from source until a registry release is announced.
+ContextPro is published on npm as `contextpro-mcp`, and every client below starts it with `npx`. To run unreleased code from a checkout, see [Run from source](#run-from-source).
 
-## Local build
+## Prerequisites
+
+- Node.js 20–26 (24 LTS recommended) and npm. No API key or Ollama needed.
+- For TypeScript/JavaScript compiler references, install the target project's dependencies (`npm install`). Without them, `tsconfig` `extends` and type packages don't resolve, and files can't be checked.
+
+The examples use the unpinned package so they don't go stale. Teams that want reproducible setups can pin a release with `contextpro-mcp@<version>`.
+
+## Connect your client
+
+The "project root" is the repository ContextPro indexes. Without `--root`, the root is the directory the client starts the server in. ContextPro refuses to start in `/` or in your home folder itself. A project folder directly inside your home folder (for example `~/myapp`) is accepted when it is a Git repository (has `.git`); a non-repository folder there (for example `~/Downloads`) is refused unless `CONTEXTPRO_ALLOW_UNSAFE_ROOT=true`. Global configs and GUI apps often start servers from your home folder, so they should pass `--root`.
+
+### Claude Code
+
+Just for you, in one project:
 
 ```sh
-git clone https://github.com/AlaeddineMessadi/contextpro-mcp.git
-cd contextpro-mcp
-npm ci
-npm run build
-node build/index.js doctor --root /absolute/path/to/target-project
+cd your-project
+claude mcp add contextpro -e CONTEXTPRO_TOOL_PROFILE=lean -- npx -y contextpro-mcp --root "$PWD"
+claude mcp list   # contextpro: ... ✔ Connected
 ```
 
-Keep the actual Node executable path printed by `node -p 'process.execPath'`. Using it in all clients avoids differences between an interactive shell's Node and a desktop client's PATH. The server repairs incompatible SQLite dependencies in an isolated cache for the launching Node ABI. First repair requires npm and network access; see [native-module recovery](#native-module-recovery).
+Put the server name before `-e`. The `-e` flag takes several values, so a name after it is read as an environment variable and the command fails with `Invalid environment variable format`.
 
-The target root is the repository being indexed, which can differ from the ContextPro checkout. Add `.contextpro/` to that project's `.gitignore`. The directory also contains memory and restore points; it is not entirely disposable.
+For a team, commit the config and the agent instructions:
 
-## Client configuration
+```sh
+cd your-project
+npx -y contextpro-mcp init claude   # writes .mcp.json, AGENTS.md and CLAUDE.md
+claude
+```
 
-Replace all placeholder paths. These examples launch the same local build and use the default workflow profile. Set the profile to `lean` for three initially advertised tools. Existing custom credentials and settings should be preserved.
+Claude Code asks once to approve servers from a project `.mcp.json`. Until you start `claude` in the project and accept, `claude mcp list` shows "Pending approval". The generated config has no `--root`, so the root is the directory where you start `claude`: start it in the repository root. Started in a subdirectory, ContextPro silently indexes only that subdirectory. The same applies to any config without `--root`, such as OpenCode's `opencode.json`.
 
 ### Codex
 
-Merge this entry into the applicable Codex configuration, such as `~/.codex/config.toml`:
+```sh
+codex mcp add contextpro --env CONTEXTPRO_TOOL_PROFILE=lean -- npx -y contextpro-mcp --root /absolute/path/to/project
+```
+
+Codex reads `~/.codex/config.toml` by default (`$CODEX_HOME/config.toml` if set), which is global, so `--root` pins the project. Tool calls can still pass another `root`. The command writes:
 
 ```toml
 [mcp_servers.contextpro]
-command = "/absolute/path/to/node"
-args = ["/absolute/path/to/contextpro-mcp/build/index.js", "--root", "/absolute/path/to/target-project"]
+command = "npx"
+args = ["-y", "contextpro-mcp", "--root", "/absolute/path/to/project"]
 
 [mcp_servers.contextpro.env]
-CONTEXTPRO_TOOL_PROFILE = "workflow"
-CONTEXTPRO_PROVIDER = "ollama"
-CONTEXTPRO_EMBED_MODEL = "nomic-embed-text:latest"
+CONTEXTPRO_TOOL_PROFILE = "lean"
 ```
 
-### Claude Code
+`codex mcp list` only prints the config; it does not start the server. Use the [smoke test](#verify) to check it starts. `Auth: Unsupported` is normal for a local (stdio) server.
 
-Merge into the target project's `.mcp.json`:
+### Cursor and other `mcpServers` JSON clients
+
+`npx -y contextpro-mcp init cursor` writes `.cursor/mcp.json` with `--root ${workspaceFolder}`. That form has not yet been verified inside Cursor; the hand-written JSON below, with an absolute `--root`, is the verified path. Put it in `.cursor/mcp.json` or the client's own config file:
 
 ```json
 {
   "mcpServers": {
     "contextpro": {
-      "command": "/absolute/path/to/node",
-      "args": ["/absolute/path/to/contextpro-mcp/build/index.js", "--root", "/absolute/path/to/target-project"],
-      "env": {
-        "CONTEXTPRO_TOOL_PROFILE": "workflow",
-        "CONTEXTPRO_PROVIDER": "ollama",
-        "CONTEXTPRO_EMBED_MODEL": "nomic-embed-text:latest"
-      }
+      "command": "npx",
+      "args": ["-y", "contextpro-mcp", "--root", "/absolute/path/to/project"],
+      "env": { "CONTEXTPRO_TOOL_PROFILE": "lean" }
     }
   }
 }
 ```
 
+Keep `--root`: GUI apps may start servers from your home folder, where ContextPro refuses to start. If a client passes an unexpanded `${...}` variable as `--root`, ContextPro ignores it and uses the launch directory.
+
 ### OpenCode
 
-Merge into `opencode.json`:
+```sh
+cd your-project
+npx -y contextpro-mcp init opencode   # writes opencode.json and AGENTS.md
+opencode mcp list
+```
 
-```json
-{
-  "mcp": {
-    "contextpro": {
-      "type": "local",
-      "command": ["/absolute/path/to/node", "/absolute/path/to/contextpro-mcp/build/index.js", "--root", "/absolute/path/to/target-project"],
-      "enabled": true,
-      "environment": {
-        "CONTEXTPRO_TOOL_PROFILE": "workflow",
-        "CONTEXTPRO_PROVIDER": "ollama",
-        "CONTEXTPRO_EMBED_MODEL": "nomic-embed-text:latest"
-      }
-    }
-  }
-}
+### VS Code
+
+```sh
+cd your-project
+npx -y contextpro-mcp init vscode   # writes .vscode/mcp.json
 ```
 
-Restart the client after changes. A reconnect can reuse a cached launch command; `health` identifies the running executable and parser backend. Enable `health` through `discover_tools` if it is absent from the selected catalog.
+The generated file uses VS Code's format (`servers`, `type: "stdio"`, `--root ${workspaceFolder}`). This setup has not yet been verified inside VS Code.
+
+### What `init` does
+
+`npx -y contextpro-mcp init <claude|cursor|vscode|windsurf|opencode>` writes the client's project config with the `lean` profile and adds a managed ContextPro section to `AGENTS.md` (and `CLAUDE.md` for Claude). The VS Code and Cursor targets write `--root ${workspaceFolder}`; the Claude and OpenCode targets write no `--root`. The Windsurf target writes `.windsurf/mcp.json` and has not been verified inside Windsurf.
+
+- It merges JSON without replacing other servers or an existing customized ContextPro entry.
+- It also creates `.contextpro/config.json` (provider defaults and project identity), which the auto-written `.contextpro/.gitignore` covers.
+- `AGENTS.md` gets a managed block at the top and existing content is preserved. `CLAUDE.md` gets the same block, so Claude Code may read it twice.
+- Running it again is idempotent and preserves your own rules outside the managed markers.
+- `--no-agent-instructions` skips `AGENTS.md`/`CLAUDE.md`; `--runner bunx` uses Bun instead of npx; `--root <dir>` targets another directory.
 
-### Generated starters and packaged installs
+The agent instructions matter: the MCP config exposes the tools, while `AGENTS.md`/`CLAUDE.md` tells the agent when to use them. The full workflow is served on demand as `contextpro://instructions`. To add the instructions by hand, copy [INSTRUCTIONS.md](INSTRUCTIONS.md). A separate skill is optional; it does not enable tools or repair retrieval.
 
-The CLI can generate starter configurations and managed project instructions:
+ContextPro keeps its local state in `.contextpro/` and writes a `.contextpro/.gitignore` itself, so you don't need to change your `.gitignore`. Older versions: add `.contextpro/` to your .gitignore.
+
+## Verify
+
+Smoke test for any client. Run it in your project; it starts the server, lists its tools and exits:
 
 ```sh
-node /absolute/path/to/contextpro-mcp/build/index.js init claude --root /absolute/path/to/target-project --runner npx
-node /absolute/path/to/contextpro-mcp/build/index.js init opencode --root /absolute/path/to/target-project --runner npx
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | CONTEXTPRO_TOOL_PROFILE=lean npx -y contextpro-mcp --root "$PWD" 2>/dev/null | grep -o '"name":"[a-z_]*"'
+# expect four lines: "name":"contextpro" (the server info), then "name":"context", "name":"discover_tools", "name":"exact_references"
 ```
 
-Starters use a package runner, even when generated from a local checkout. Replace the generated launch command with the local examples above to run unreleased code. For a registry install, first verify access to the intended published package and pin its version deliberately.
+Check storage with `doctor`:
 
-`init` merges JSON without replacing other servers or an existing customized ContextPro entry. It installs a managed `AGENTS.md` section and, for Claude, a `CLAUDE.md` section. `--no-agent-instructions` skips those sections. Repeated init preserves custom rules outside the markers. Codex configuration is manual; do not assume every client is supported by the generator.
+```sh
+npx -y contextpro-mcp doctor --root /absolute/path/to/project
+```
 
-## Verify once
+Expect `Before: ok | storage=true | dbOpen=true` and `After: ok | …`. "Fix Applied: no" only means you didn't pass `--fix`.
 
-1. Restart the client and confirm the expected server is connected.
-2. Call `status` to inspect the root and index. In lean mode, enable it with `discover_tools(enable:["status"])`.
-3. Read a known small source target with `context` in lean mode, or `explain` in workflow mode.
-4. For first-time indexing or reported drift requiring a rebuild, enable/call `reindex`. `no_embed:true` builds structural evidence without eager corpus embeddings.
+`npx -y contextpro-mcp --help` lists the commands, and `--version` prints the installed version.
 
-This is installation diagnosis, not a checklist for every coding task. Missing embeddings do not disable structural tools. For retrieval with no query embedding attempt, use `search(preset:"keyword_only")` or direct `context(targets:[...])`.
+In the client, a first read looks like this. Use a line range: a whole file larger than `max_tokens` is omitted rather than cut.
 
-## Optional model setup
+```js
+context({ root: "/absolute/path/to/project", targets: [{ file: "src/index.ts", start: 1, end: 40 }], max_tokens: 1500 })
+```
+
+Replace `src/index.ts` with a file in your project. For callers of a symbol:
+
+```js
+exact_references({ root: "/absolute/path/to/project", file: "src/lib/foo.ts", symbol_name: "foo" })
+```
+
+Without Ollama, `context()` results include a "Discovery used lexical fallback" notice. That is expected and doesn't affect `exact_references`.
+
+To inspect the index, enable `status` with `discover_tools(enable:["status"])`. If the tool doesn't appear (some clients don't refresh their tool list), call it through `discover_tools({ root, call: { name: "status", arguments: {} } })`. For first-time indexing, or drift that needs a rebuild, enable and call `reindex`; `no_embed:true` builds structural data without embeddings. This is installation diagnosis, not something to run on every task.
+
+## Optional setup
+
+### Workflow profile
+
+`CONTEXTPRO_TOOL_PROFILE` picks the starting tool list. `lean` (3 tools) is recommended. `workflow` (14 tools for discovery, reads, impact and validation) is the server default when no profile is set; `core` has 39 and `full` all 68. See [profiles](docs/configuration.md#profiles).
+
+### Semantic search with Ollama
+
+Embeddings are optional. ContextPro tries a local Ollama at `OLLAMA_HOST` (default `http://127.0.0.1:11434`) automatically and falls back to keyword search when it's unavailable. Compiler references and structural search work either way. To enable semantic search, install Ollama and run `ollama pull nomic-embed-text`.
+
+The defaults are already provider `ollama` and model `nomic-embed-text:latest`; set them explicitly only to pin or change them:
+
+```json
+"env": {
+  "CONTEXTPRO_TOOL_PROFILE": "lean",
+  "CONTEXTPRO_PROVIDER": "ollama",
+  "CONTEXTPRO_EMBED_MODEL": "nomic-embed-text:latest"
+}
+```
+
+The `CONTEXTPRO_PROVIDER` and `CONTEXTPRO_EMBED_MODEL` lines above are the defaults. ContextPro needs its own embedding endpoint; it does not reuse a Claude or Codex session. Reindex after changing the model. For structural-only indexing with no embeddings, set `CONTEXTPRO_REINDEX_NO_EMBED=true` or pass `no_embed:true` to `reindex`.
+
+Chat-assisted operations are optional. Leave `CONTEXTPRO_CHAT_RERANK` and `CONTEXTPRO_AUTO_HUBS` off unless needed. Hosted credentials can make a default chat model available even without an explicit chat-model setting, so omitting that setting is not a network-off switch. See [provider settings](docs/configuration.md#providers).
 
-For local semantic retrieval, install and start Ollama, then pull the configured embedding model, for example `nomic-embed-text`. ContextPro needs its own embedding endpoint; it does not reuse a Claude or Codex session.
+## Run from source
+
+```sh
+git clone https://github.com/AlaeddineMessadi/contextpro-mcp.git
+cd contextpro-mcp
+npm ci
+npm run build
+node build/index.js doctor --root /absolute/path/to/your-project
+node -p 'process.execPath'
+```
+
+Use the printed Node executable and your checkout path in the client config. Using the same executable in every client avoids differences between your shell's Node and a desktop client's PATH. For example, in a Claude Code `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "contextpro": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/contextpro-mcp/build/index.js", "--root", "/absolute/path/to/your-project"],
+      "env": { "CONTEXTPRO_TOOL_PROFILE": "lean" }
+    }
+  }
+}
+```
 
-Chat-assisted operations are optional. Leave `CONTEXTPRO_CHAT_RERANK` and `CONTEXTPRO_AUTO_HUBS` off unless needed. Hosted credentials can make a default chat model available even without an explicit chat-model setting, so omitting that setting is not a universal network-off switch. See [provider settings](docs/configuration.md#providers).
+Restart the client after changes. A reconnect can reuse a cached launch command; `health` (enable it through `discover_tools`) shows the running executable and parser backend. The server repairs incompatible SQLite bindings in an isolated cache for the launching Node ABI; the first repair needs npm and network access.
 
 ## Native-module recovery
 
@@ -120,9 +207,12 @@ Do not rebuild shared `node_modules` merely to satisfy one client: clients using
 
 ## Worktrees and common problems
 
-- **Tools absent after a startup/handshake failure:** run the configured Node executable and server path directly to inspect stderr. `ERR_MODULE_NOT_FOUND` with a missing checkout `node_modules` directory means the installation is incomplete, not a discovery-profile problem. In that checkout, restore the locked dependencies with `npm ci` using the configured Node runtime, run `npm run build`, then reconnect/restart the MCP server in the client. Keep the configured checkout's dependencies and build while clients use it; deleting them to free disk space prevents startup. Native ABI failures have the separate recovery procedure above.
-- **Wrong repository/worktree:** subagents must pass their absolute worktree `root` on every call. Shell `cd` does not retarget a shared MCP server. Linked worktrees require explicit roots, including reindex calls; verify the chosen checkout before attempting recovery. Client-advertised roots may describe the parent agent.
-- **Stale embeddings:** check provider/model settings, then reindex. Interactive search does not rebuild the whole vector corpus.
-- **Slow or failed calls:** inspect `health` and `status`; use bounded results and keyword-only discovery when the provider is unavailable. Do not loop blindly on connection errors.
-- **Agent ignores MCP:** install concise project rules from [INSTRUCTIONS.md](INSTRUCTIONS.md). Prefer MCP when it adds useful context; allow native reads for tiny known targets and incomplete evidence.
-- **Disk growth:** follow [maintenance](docs/maintenance.md). Preserve memory and restore points while cleaning regenerable artifacts.
+- **`npm warn deprecated prebuild-install@7.1.3` from npx:** expected; it comes from a native dependency and does not affect ContextPro.
+- **`Unsafe project root` at startup:** the server was started in `/`, in your home folder, or in a non-Git folder directly inside it, usually without `--root`. Add `--root /absolute/path/to/project`. If your project sits directly in your home folder and is not a Git repository, move it one level deeper, run `git init`, or set `CONTEXTPRO_ALLOW_UNSAFE_ROOT=true`.
+- **`exact_references` finds nothing and warns that files could not be checked:** install the target project's dependencies (`npm install`) and retry.
+- **Tools absent after a startup failure:** run the configured command directly to read stderr. From source, `ERR_MODULE_NOT_FOUND` with a missing `node_modules` means the checkout is incomplete: run `npm ci` and `npm run build` with the configured Node, then restart the client. Keep the checkout's dependencies and build while clients use it.
+- **Wrong repository or worktree:** subagents must pass their absolute worktree `root` on every call. A shell `cd` does not retarget a shared MCP server. Linked worktrees require explicit roots, including for `reindex`. Client-advertised roots may describe the parent agent.
+- **Local state:** `.contextpro/` in the project holds the index, memory and restore points. It is not entirely disposable; follow [maintenance](docs/maintenance.md) before deleting it. `~/.contextpro` holds the workspace registry and `~/.cache/contextpro` the native-binding cache.
+- **Stale embeddings:** check provider and model settings, then reindex. Interactive search does not rebuild the whole vector corpus.
+- **Slow or failed calls:** inspect `health` and `status`; use bounded results and keyword-only discovery when the provider is unavailable. Do not loop on connection errors.
+- **Agent ignores ContextPro:** install the project rules with `init` or from [INSTRUCTIONS.md](INSTRUCTIONS.md).

package/INSTRUCTIONS.md

@@ -4,7 +4,7 @@ Append the following policy to your client's project rules, such as `AGENTS.md`
 
 ## Choose the smallest useful request
 
-Use ContextPro for unfamiliar repository discovery, structural context and cross-file evidence. With the lean profile, use `context(query:...)` to find and read evidence together, or `context(targets:[...])` to batch known source targets. With the default workflow profile, use `task_pack` or compact `search`; use `explain` for known symbols and `skeleton(exported_only:true)` for TS/JS public APIs.
+Use ContextPro for unfamiliar repository discovery, structural context and cross-file evidence. With the lean profile, use `context(query:...)` to find and read evidence together, or `context(targets:[...])` to batch known source targets. With the workflow profile (the server default when no profile is set; init installs lean), use `task_pack` or compact `search`; use `explain` for known symbols and `skeleton(exported_only:true)` for TS/JS public APIs.
 
 Pass the absolute active repository/worktree as `root` on every call. For `context`, use `max_tokens` from 512 to 12000 (default 4000, estimated UTF-8 bytes/4) and at most six exact targets. Include a known relative directory and concrete route or symbol names in discovery questions. Directory and named-usage hints influence ranking; they are not exhaustive scope or compiler references. Ask explicitly for an overview when you want a UI inventory. If evidence is omitted, narrow to exact targets or a native scope search instead of repeating the same broad query.
 

package/README.md

@@ -1,165 +1,90 @@
 # ContextPro
 
-**Compiler-exact references and bounded source context for coding agents, in a three-tool lean profile.**
+[![npm version](https://img.shields.io/npm/v/contextpro-mcp)](https://www.npmjs.com/package/contextpro-mcp)
+[![CI](https://github.com/AlaeddineMessadi/contextpro-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AlaeddineMessadi/contextpro-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/contextpro-mcp)](LICENSE)
 
-ContextPro is a local MCP server for TypeScript and JavaScript repositories. When an agent asks "who calls this?", it answers with the TypeScript compiler instead of a name search: aliases, re-exports and same-named symbols are told apart, and every result states its scope and whether it was truncated. When an agent needs source, it returns budgeted slices instead of whole files.
+**Exact find-all-references for your coding agent on TypeScript/JavaScript repos — answered by the TypeScript compiler, not grep.**
 
-[Get started](INSTALL.md) · [Agent guide](agent-guide.md) · [Benchmarks](docs/benchmarks/README.md) · [Documentation](docs/README.md) · [Contribute](CONTRIBUTING.md) · [Security](SECURITY.md)
+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.
 
-## What it is good at
-
-- **Renames and refactors in TS/JS codebases.** `exact_references` resolves bindings with the compiler and reports per-file call totals, reference kinds and truncation, so an agent knows what it has not seen.
-- **Parallel agents on one repository.** Indexes are scoped per Git worktree, check saved-file drift and reconcile in the background.
-- **A small tool catalog.** The lean profile exposes three of the 68 tools; the rest are discovered only when needed.
-- **Inspectable evidence.** Responses separate compiler-resolved references, textual candidates and heuristic fallbacks, and report freshness.
+## Quick start
 
-Python references work through a configured Pyright; other languages fall back to structural and textual evidence.
+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.
 
-## Honest results
+**Fastest try (Claude Code):**
 
-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:
+```sh
+cd your-project
+claude mcp add contextpro -e CONTEXTPRO_TOOL_PROFILE=lean -- npx -y contextpro-mcp --root "$PWD"
+claude mcp list   # contextpro: ... ✔ Connected
+```
 
-| 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 |
-| Eight paired coding tasks, previous ContextPro build vs connected-retrieval candidate | previous build 1/8, candidate 0/8 (six on private repositories; see connected-evidence report) |
+Keep the server name before `-e`, which would otherwise swallow it.
 
-Plain `grep` and file reads are often the cheapest choice when an agent already knows where to look. ContextPro is most useful when binding identity matters or the exact location is unknown. We welcome reproducible comparisons, including ones where another tool wins; see [how we compare](docs/comparison.md).
+**Claude Code, whole team** (commits `.mcp.json` plus agent instructions in `AGENTS.md` and `CLAUDE.md`):
 
-## Get started
+```sh
+npx -y contextpro-mcp init claude
+claude   # start it in the repository root and approve "contextpro" once
+```
 
-Use **Node.js 24 LTS** and npm. Install from source until a registry release is announced; the version in `package.json` is not proof of a published npm package.
+**Codex:**
 
 ```sh
-git clone https://github.com/AlaeddineMessadi/contextpro-mcp.git
-cd contextpro-mcp
-npm ci
-npm run build
-node build/index.js doctor --root /absolute/path/to/your-project
-node -p 'process.execPath'
+codex mcp add contextpro --env CONTEXTPRO_TOOL_PROFILE=lean -- npx -y contextpro-mcp --root /absolute/path/to/project
 ```
 
-Use the printed Node executable and your checkout path in the client configuration. For example, in Claude Code's project `.mcp.json`:
+**Cursor and other clients that read `mcpServers` JSON** (`.cursor/mcp.json` or the client's config file):
 
 ```json
-{
-  "mcpServers": {
-    "contextpro": {
-      "command": "/absolute/path/to/node",
-      "args": ["/absolute/path/to/contextpro-mcp/build/index.js", "--root", "/absolute/path/to/your-project"],
-      "env": { "CONTEXTPRO_TOOL_PROFILE": "lean" }
-    }
-  }
-}
+{ "mcpServers": { "contextpro": {
+    "command": "npx",
+    "args": ["-y", "contextpro-mcp", "--root", "/absolute/path/to/project"],
+    "env": { "CONTEXTPRO_TOOL_PROFILE": "lean" } } } }
 ```
 
-Replace every placeholder, add `.contextpro/` to the target project's `.gitignore`, then restart the client. [Installation instructions](INSTALL.md) cover Codex, Claude Code, OpenCode, indexing and native-module recovery. [Project instructions](INSTRUCTIONS.md) teach agents when ContextPro is useful and when to verify with native tools.
-
-Install the project instructions as well as the server: connecting MCP exposes tools,
-while `AGENTS.md` / `CLAUDE.md` teaches the agent when to use them. The detailed
-workflow is available on demand through `contextpro://instructions`. A separate
-skill is optional; it does not enable tools or repair retrieval.
+**OpenCode:** run `npx -y contextpro-mcp init opencode`, then `opencode mcp list`.
 
-## A small interface for real coding work
+**Try it.** Ask your agent:
 
-| Task | Start with | What to check |
-| --- | --- | --- |
-| Locate unfamiliar code and read evidence | `context(query:...)` | Retrieval is a ranked selection, not an exhaustive search |
-| Read several known targets | `context(targets:[...])` | Follow explicit omissions if more evidence is needed |
-| Find TS/JS references | `exact_references` | Declared scope, reference kinds and truncation |
-| Inspect an exported API | Discover `skeleton`, then use `exported_only:true` | Signatures do not prove behavior |
-| Assess a change | Discover `blast_radius` or `validate_scope` | Text matches are candidates; recommended checks still need to run |
-| Preserve a decision | Discover `memory_record_task` | Keep supporting evidence and revisit stale assumptions |
-| Inspect compiler errors or rename a binding | Discover `compiler_diagnostics` / `rename_preview` | TS/JS compiler or configured Pyright; inspect before `rename_apply` |
-| Record executed checks | `validate_scope`, then discover `validation_record` | Run checks in the coding host; receipts become stale when inputs change |
+- "Use contextpro to find every caller of `<function>` in `<file>`."
+- "Use contextpro to show me how `<feature>` works."
 
-Tool schemas are the argument reference. See the [agent guide](agent-guide.md) for examples, batching and context reuse.
+[INSTALL.md](INSTALL.md) covers VS Code, team approval, a smoke test that works without any client, running from source and troubleshooting.
 
-| Profile | Initial interface |
-| --- | --- |
-| `lean` | `context`, `exact_references`, `discover_tools` |
-| `workflow` (default) | 14 tools for discovery, reads, impact and validation |
-| `core` | 39 tools: common workflows plus editing and graphs |
-| `full` | All 68 registered tools, including 5 deprecated aliases |
-
-Set `CONTEXTPRO_TOOL_PROFILE` in the server environment. `discover_tools(enable:[...])` enables tools without executing them. If the client cannot refresh its catalog, use the supported `discover_tools({root,call:{name,arguments}})` dispatcher with the returned expert schema.
-
-Experimental connected retrieval (`CONTEXTPRO_CONNECTED_CONTEXT=true`) combines ranked source, one-hop imports/callers and relevant tests in `context` and `task_pack`. It remains opt-in while task-level performance is evaluated. Discover `feature_brief` for a cached, source-cited feature map; model-written interpretations require a separate opt-in. Query-based `context` packets accept `previous_context_id` while the agent still holds that packet; omit it after context loss. Exact target reads remain stateless. See [configuration and freshness rules](docs/configuration.md).
-
-The optional `context.intent` hint (`lookup`, `change`, `debug`, `review`, `overview`, or `auto`) enables question-aware source and document retrieval for one query. Shared indexing/compiler work is also opt-in through `contextpro daemon start` and `CONTEXTPRO_DAEMON=true`. Evidence-backed memory and handoffs build on the existing SQLite/artifact architecture; experimental features such as local task coordination are documented in configuration. [Configuration](docs/configuration.md#experimental-development-context) explains setup, limits and rollback; these features do not establish a measured coding-speed improvement.
-
-## Ask for the source you need
-
-Pass the absolute active repository or worktree as `root` on every call. Query
-budgets use `max_tokens` (512–12000, default 4000; estimated UTF-8 bytes divided by
-four). Exact batches accept up to six targets.
-
-This example uses ContextPro's own repository. In another project, use paths and
-declaration names observed in its source rather than guessed symbols.
-
-```js
-context({
-  root: "/absolute/path/to/contextpro-mcp",
-  query: "src/core/agent-setup.ts mergeAgentInstructions preserve existing project rules",
-  intent: "change",
-  max_tokens: 2500
-})
-context({
-  root: "/absolute/path/to/contextpro-mcp",
-  targets: [{file: "src/core/agent-setup.ts", symbol: "mergeAgentInstructions"}],
-  max_tokens: 1500
-})
-// Use compiler references when binding identity or cross-file callers matter.
-exact_references({
-  root: "/absolute/path/to/contextpro-mcp",
-  file: "src/core/agent-setup.ts",
-  symbol_name: "mergeAgentInstructions",
-  limit: 20
-})
-```
-
-These are task-dependent choices, not a checklist: stop when enough evidence is
-available. If a broad query favors documentation, read the discovered source
-symbol or a narrow line range directly. If references time out, continue with
-bounded source/native tracing and disclose its limits; lowering `limit` changes
-the display window, not compiler workspace scope. Read each tool's schema:
-`max_tokens` is a `context` budget, not an argument for `status` or `exact_references`.
-
-Known directory prefixes and route topics help query discovery retain the requested
-implementation. A named component or compound error code supplies additional local
-text evidence. These are bounded ranking hints, not hard directory filters or
-compiler-resolved references; connected dependencies may still come from elsewhere.
-For a UI inventory, ask explicitly for an overview. For a bug, name the affected
-symbol and source area. Check citations and omissions, then narrow to exact targets
-when needed rather than repeating the same broad query.
+## What it is good at
 
-## Evidence you can inspect
+- **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.
 
-ContextPro distinguishes source evidence, compiler-resolved references, textual candidates and heuristic fallbacks. Parser and TypeScript workers run in bounded child processes so a worker failure can be reported and recovered from without inherently terminating the MCP server.
+Python references work through a configured Pyright; other languages fall back to structural and text search.
 
-Freshness checks cover saved files, not unsaved editor buffers. Per-file reconciliation is not an atomic snapshot of a repository being edited concurrently. Reference precision depends on language and scope; configured Python uses Pyright LSP, while unconfigured Python heuristics and imported SCIP data retain their distinct provenance.
+## Honest results
 
-Local-first does not mean sandboxed. Tools run with your user permissions. Hosted embedding or chat providers receive the inputs sent to them, and chat-assisted operations are optional. Read the [security model](SECURITY.md) and [provider configuration](docs/configuration.md) before using sensitive repositories.
+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.
 
-## Build with us
+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.
 
-Useful contributions include small bug reproductions, language fixtures, reference-completeness tests, realistic benchmarks, clearer setup guides and performance fixes with before/after evidence.
+| 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 |
 
-```sh
-npm run build
-npm test
-npm run docs:check
-npm run release:check
-npm run pack:check
-```
+For simple lookups, plain grep is cheaper. We welcome reproducible comparisons, including ones where another tool wins; see [how we compare](docs/comparison.md).
 
-Start with [CONTRIBUTING.md](CONTRIBUTING.md), [open issues](https://github.com/AlaeddineMessadi/contextpro-mcp/issues) or the [roadmap](docs/roadmaps/contextpro-roadmap.md). [Maintenance](docs/maintenance.md) explains safe cleanup and runtime-specific testing.
+## Learn more
 
-For questions, see [support](SUPPORT.md). Report vulnerabilities privately through the process in [SECURITY.md](SECURITY.md). Community participation follows our [code of conduct](CODE_OF_CONDUCT.md).
+- [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 around compiler-backed references, worktree-scoped indexes and bounded retrieval. Upstream has been quiet since July 2026, so development continues here. It is distributed under the [MIT license](LICENSE). The original ForLoop copyright notice is preserved. See [NOTICE](NOTICE) for attribution. References to other projects do not imply endorsement.
+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).

package/SECURITY.md

@@ -12,16 +12,18 @@ Include the affected version or commit, Node/OS/client versions, a minimal redac
 
 ## Supported versions
 
-Security fixes target the latest maintained release and `main`. Until the first registry release, identify reports by Git commit. Older versions do not have a promised backport window. Node.js 24 LTS is recommended; CI also checks the Node 20 engine floor. The package's older engine floor is a compatibility declaration, not a promise to maintain end-of-life runtimes.
+Security fixes target the latest maintained release and `main`. Identify reports by npm version or Git commit. Older versions do not have a promised backport window. Node.js 24 LTS is recommended; CI also checks the Node 20 engine floor. The package's older engine floor is a compatibility declaration, not a promise to maintain end-of-life runtimes.
 
 ## Trust and data boundaries
 
 - **Same-user permissions.** ContextPro is a local stdio MCP process, not a sandbox. Filesystem, edit and command-related operations can use the launching user's access. Choose a trusted project root and review your client's tool permissions.
 - **Untrusted repositories.** Code, comments, docs, tool results and memory can contain malicious instructions. Agents must treat them as data. Installing dependencies or running a repository's tests, hooks, linters or commands may execute its code.
-- **Local state.** `.contextpro/` can contain indexed source, task artifacts, history, memory and restore points. Keep it out of Git and protect it like the repository. It is not entirely disposable cache. The workspace registry can reveal local project paths.
+- **Local state.** `.contextpro/` can contain indexed source, task artifacts, history, memory and restore points. ContextPro writes `.contextpro/.gitignore` to keep it out of Git; protect it like the repository. It is not entirely disposable cache. The workspace registry can reveal local project paths.
 - **Providers.** Hosted embedding/chat endpoints receive their request inputs, which may include source code. Local Ollama is an option. Structural tools do not require an embedding endpoint; use direct reads or keyword-only retrieval to avoid query-embedding attempts. Merely omitting a chat-model setting is not a network-off guarantee when hosted credentials are present.
 - **Native dependency recovery.** Automatic ABI repair may invoke npm and download dependencies into an isolated cache. Set `CONTEXTPRO_NATIVE_AUTO_REPAIR=false` when installation must be managed explicitly.
 - **Diagnostics.** Opt-in tool traces and agent benchmark transcripts can reveal paths, arguments, source and usage metadata. Keep them private and redact before sharing. Do not upload `.env` files or account credentials.
 - **Correctness limits.** Freshness and scope checks reduce errors; they do not prove an arbitrary change safe. Unsaved buffers, concurrent edits, dynamic calls and incomplete imported indexes require verification.
+- **Evidence labels.** Responses distinguish source evidence, compiler-resolved references, textual candidates and heuristic fallbacks. Freshness checks cover saved files, not unsaved editor buffers, and per-file reconciliation is not an atomic snapshot of a repository being edited concurrently. Configured Python uses Pyright LSP; unconfigured Python heuristics and imported SCIP data keep their own provenance labels.
+- **Worker isolation.** Parser and TypeScript workers run in bounded child processes, so a worker failure is reported and recovered from without necessarily stopping the MCP server. This is fault isolation, not a security sandbox.
 
 See [configuration](docs/configuration.md) and [maintenance](docs/maintenance.md) for provider controls and safe cleanup. A clean dependency audit or secret scan is a point-in-time check, not a security certification.