@lzehrung/codegraph 2.1.0 → 2.1.1

package/docs/mcp.md

@@ -31,7 +31,11 @@ The shared HTTP endpoint is `http://127.0.0.1:7331/mcp`. HTTP binds to `127.0.0.
 
 Stdio servers exit when the client closes stdin, when an IPC parent disconnects, or after `--idle-timeout-ms` of inactivity (default 30 minutes; `0` disables the idle timer). That keeps orphaned `mcp serve --stdio` processes from lingering after an IDE or agent exits.
 
-HTTP protocol sessions track last activity, cap concurrent legacy sessions (default 32), and evict idle sessions on a timer (default 30 minutes). Capacity and idle eviction skip sessions with in-flight requests or open SSE streams; when every slot is active, a new `initialize` receives an actionable JSON-RPC capacity error instead of evicting a working client. Transport errors and protocol session closes also remove the session.
+HTTP protocol sessions track last activity, cap concurrent legacy sessions (default 32), and evict idle sessions on a timer (default 30 minutes). Capacity and idle eviction skip sessions with in-flight requests or open SSE streams; when every slot is active, a new `initialize` receives an actionable JSON-RPC capacity error instead of evicting a working client. Request validation errors return a 4xx response while leaving the session usable; explicit `DELETE`, idle eviction, and an actual transport close remove the session.
+
+Each MCP protocol session permits four concurrent tool calls by default; a saturated session returns a retryable busy error rather than queueing unbounded work. The programmatic server options `mcpToolConcurrency`, `httpBodyTimeoutMs`, and `mcpToolTimeoutMs` tune concurrency, the 30-second HTTP request-body deadline, and the 30-minute per-tool execution deadline; an HTTP body that misses its deadline receives `408 Request Timeout`, while an expired tool call is aborted and names its configured limit. `httpBodyTimeoutMs` must be a whole number of milliseconds from `1` through `2_147_483_647`; `mcpToolTimeoutMs` must be a whole number from `0` through `2_147_483_647`; HTTP server startup rejects other values.
+
+Client cancellation returns promptly, but does not discard shared index or artifact work. A cancelled call continues to occupy its concurrency slot until its underlying operation settles, preventing a burst of abandoned requests from exceeding the configured resource bound; the MCP SDK aborts the individual in-flight HTTP request when its response socket closes without closing the shared protocol session. Shutdown rejects new calls and waits for active work before invalidating shared session resources.
 
 Use stdio for a client-owned subprocess. Use HTTP for one long-running codegraph process per repository, then point every MCP-capable IDE, terminal, or agent client at the same local URL. Exact config keys vary by client, but the MCP settings should use HTTP/Streamable HTTP transport plus the `/mcp` URL instead of a `command`/`args` stdio launch.
 
@@ -66,14 +70,29 @@ The server exposes the same bounded primitives as the CLI and library session la
 - `get_file`: bounded project file read with `offset`/`limit` line pagination, exact `number<TAB>line` content, and optional direct graph context.
 - `get_symbol`: resolve a stable search or explain handle.
 - `goto`: definition lookup by portable handle, qualified `file::symbol` path, or file position.
-- `refs`: references by portable handle, qualified `file::symbol` path, or file position. The response pairs `references` with `limit`, `totalSeen`, `truncated`, and `omitted`; `truncated` is exact because the lookup probes one reference past the limit. When truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full corpus-wide counts.
-- `file_deps`, `path`: dependency navigation; pass `direction: "deps"` or `"rdeps"` to `file_deps`. `file_deps.file` accepts a portable symbol handle or qualified symbol path and traverses its declaring file. `dependencies`/`reverseDependencies` carry the same `limit`/`totalSeen`/`truncated`/`omitted` metadata as `refs`, so a capped prefix is always distinguishable from a complete result; when truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full graph-wide counts.
+- `refs`: references by portable handle, qualified `file::symbol` path, or file position. Collection `limit` defaults to 25 and caps at 500 (`DEFAULT_MCP_COLLECTION_LIMIT` / `MAX_MCP_COLLECTION_LIMIT` in `src/mcp/tools.ts`). The response pairs `references` with `limit`, `totalSeen`, `truncated`, and `omitted`; `truncated` is exact because the lookup probes one reference past the limit. When truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full corpus-wide counts.
+- `file_deps`, `path`: dependency navigation; pass `direction: "deps"` or `"rdeps"` to `file_deps`. `file_deps` uses the same collection `limit` default 25 / max 500 as `refs`. `file_deps.file` accepts a portable symbol handle or qualified symbol path and traverses its declaring file. `dependencies`/`reverseDependencies` carry the same `limit`/`totalSeen`/`truncated`/`omitted` metadata as `refs`, so a capped prefix is always distinguishable from a complete result; when truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full graph-wide counts.
 - `impact`: compact git-range impact analysis (`format: "compact"`, `impacted`, diagnostics). Bounded by default.
 - `review`: git-range review report (`riskSummary`, `reviewTasks`, candidate tests). MCP is a bounded transport: `projectFiles`, `changedFiles` (including per-file `symbols`), `graphDelta`, and `candidateTests` are capped at the response's `limits` with exact per-collection `omittedCounts`, and `summary` totals stay accurate for the full report. Library callers that need the complete unbounded report call `buildReviewReport` directly instead of going through MCP.
-- `query_sqlite`: bounded read-only SQLite artifact query with freshness metadata.
+- `query_sqlite`: bounded read-only SQLite artifact query with freshness metadata. Row `limit` defaults to 100 and caps at 500 (`src/sqlite/rowBounds.ts`).
 - `refresh_index`: invalidate the in-memory session and optionally rebuild the base or symbol snapshot.
 - `artifact_build`: artifact creation, available only with write access enabled.
 
+## Per-tool schema summary
+
+Compact contracts for high-traffic tools (`src/mcp/tools.ts`). Write gating: only `artifact_build` requires write access (`--allow-build`); all others are read-only.
+
+| Tool             | Required | Key enums / fields                                                                | Defaults                                                      | Maxima                                  | Write gate            |
+| ---------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------- | --------------------- |
+| `search`         | `query`  | `mode`: hybrid\|symbol\|path\|text\|graph\|sql; optional `from`, `depth`, `limit` | `depth` 1, `limit` 20                                         | `limit` 100                             | no                    |
+| `explore`        | `query`  | optional `limit`, `maxPackets`, `maxPaths`, `includeSource`                       | `limit` 5, `maxPackets` 3, `maxPaths` 3, `includeSource` true | `limit` 50, packets/paths 10            | no                    |
+| `packet_get`     | `target` | optional `maxSymbols`, `maxSnippets`, `maxDuplicates`                             | (unset uses server defaults)                                  | symbols 200, snippets 50, duplicates 20 | no                    |
+| `query_sqlite`   | `query`  | optional `params[]`, `limit`                                                      | `limit` 100                                                   | `limit` 500                             | no                    |
+| `refresh_index`  | (none)   | optional `warmup`: off\|base\|symbols                                             | (omit = invalidate only)                                      | -                                       | no                    |
+| `artifact_build` | (none)   | optional `outDir`, `sqlite`, `graphJson`, `report`, `questions`, `force`          | -                                                             | -                                       | yes (`--allow-build`) |
+
+`refs` / `file_deps` collection limits: default 25, maximum 500. Legacy alias tool names are accepted by `tools/call` but omitted from `tools/list`.
+
 ## Session lifecycle
 
 MCP keeps one codegraph session warm for the configured root. That makes follow-up calls cheaper than separate CLI invocations. Startup is lazy unless `--warmup` or `--warmup-symbols` is passed.
@@ -85,7 +104,7 @@ Text and hybrid searches reuse a prepared handle for `.codegraph-cache/index-v1/
 
 If the sidecar is busy or unavailable, MCP uses the same exact in-memory matcher. [How it works](./how-it-works.md#cache-and-session-behavior) explains the search cache.
 
-Use `refresh_index` to rebuild the snapshot, reset SQLite artifact state, or recover after a change burst exceeds automatic limits. With write access, `query_sqlite` refreshes codegraph SQLite artifacts after small edits; otherwise it refuses stale rows. `artifact_build` refuses stale indexes, so run `refresh_index` after large change bursts.
+Use `refresh_index` to rebuild the snapshot, reset SQLite artifact state, or recover after a change burst exceeds automatic limits. Concurrent refresh requests serialize; each request runs its own requested `warmup` (`off`, `base`, or `symbols`) after an active refresh completes. With write access, `query_sqlite` refreshes codegraph SQLite artifacts after small edits; otherwise it refuses stale rows. `artifact_build` refuses stale indexes, so run `refresh_index` after large change bursts.
 `get_file` reads live bytes from disk after path confinement. It does not require a fresh index; only an explicit `includeGraphContext: true` checks indexed freshness and adds direct graph context, so returned file bytes and `totalLines` remain live even when `freshness` reports stale context.
 Tool schemas are flat JSON objects for broad client compatibility; argument combinations such as `refs` handle-vs-position mode are validated by the server. Legacy paired names (`callers`, `callees`, `supertypes`, `subtypes`, `deps`, and `rdeps`) remain accepted by `tools/call` as aliases, but only the unified tools appear in `tools/list`.
 
@@ -108,14 +127,14 @@ Positions use 1-based lines and 0-based UTF-16 columns, matching the rest of cod
 
 Position-based `goto` and `refs` requests (`file`, `line`, `column`) remain the primary navigation form. Alternatively, `goto.handle` and `refs.handle` accept an exact qualified identity, `<project-relative-file>::<local-symbol>`, without coordinates; each tool rejects mixed modes. `file_deps.file` accepts that identity or a portable `symbol:` handle, resolves its declaration, and returns file-graph dependencies; use `calls` for symbol-level callers and callees. Duplicate local names return an ambiguity error rather than selecting one.
 
-MCP tool name ↔ CLI command mapping for the common handle-driven follow-ups:
+MCP tool name <-> CLI command mapping for the common handle-driven follow-ups:
 
-- `workspace_symbols` ↔ `codegraph symbols`
-- `search` ↔ `codegraph search`
-- `packet_get` ↔ `codegraph packet get`
-- `get_symbol` ↔ `codegraph explain`
-- `calls` ↔ `codegraph callers` / `codegraph callees`
-- `type_hierarchy` ↔ `codegraph supertypes` / `codegraph subtypes`
+- `workspace_symbols` <-> `codegraph symbols`
+- `search` <-> `codegraph search`
+- `packet_get` <-> `codegraph packet get`
+- `get_symbol` <-> `codegraph explain`
+- `calls` <-> `codegraph callers` / `codegraph callees`
+- `type_hierarchy` <-> `codegraph supertypes` / `codegraph subtypes`
 
 ### Rename preview
 
@@ -200,7 +219,7 @@ An MCP `explore` request whose entire query resolves to an indexed project-relat
 - Tool calls do not accept per-request root overrides.
 - Tools are read-only by default.
 - `artifact_build` requires `--allow-build` and a fresh or auto-refreshed MCP index.
-- `query_sqlite` rejects mutating SQL, recursive queries, synthetic payload functions, and stale artifact queries it cannot refresh safely.
+- `query_sqlite` rejects mutating SQL, recursive queries, synthetic payload functions, and stale artifact queries it cannot refresh safely. Each query has a 10-second execution deadline.
 - `get_file` rejects raw reads and structural text-config summaries over the 16 MiB input limit. Accepted reads use separate output-page bounds from `maxBytes`, `offset`, and `limit`; binary input is rejected, and sensitive formats require `allowSensitive: true` for raw values.
 - SQLite responses are row- and byte-bounded.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzehrung/codegraph",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -82,7 +82,7 @@
   "license": "MIT",
   "description": "Multi-language repository map for agents and humans: MCP tools, dependency graphs, symbol indexes, impact review, and bounded source evidence.",
   "dependencies": {
-    "@lzehrung/codegraph-core": "2.1.0",
+    "@lzehrung/codegraph-core": "2.1.1",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "fast-glob": "^3.3.3",
@@ -99,6 +99,6 @@
     "@emnapi/runtime": "1.11.3"
   },
   "optionalDependencies": {
-    "@lzehrung/codegraph-native": "^1.9.0"
+    "@lzehrung/codegraph-native": "^1.9.1"
   }
 }