@lzehrung/codegraph 2.1.1 → 2.2.0

package/docs/mcp.md

@@ -12,7 +12,21 @@ Stdio is the default transport and is the best fit when the MCP client launches
 codegraph mcp serve --root . --stdio
 ```
 
-Streamable HTTP is useful when multiple IDE, terminal, or agent instances should share one repo-local server:
+For one reusable repo-local HTTP server, use the lifecycle wrapper:
+
+```bash
+codegraph server start --root /path/to/repo --warmup
+codegraph server status --root /path/to/repo --json
+codegraph server stop --root /path/to/repo
+```
+
+`server start` serializes lifecycle changes, launches `mcp serve`, waits for a same-root process and startup identity proved by a challenged `/health` response, then records the process at `.codegraph/server.json`. It defaults to `127.0.0.1:7331`; use `--host` explicitly for a non-loopback bind, `--replace` only to restart a live server for the same root, and `--startup-timeout-ms <1-86400000>` when a warmup needs more than the 15-second default.
+
+`server start --json` emits `status: "started"`, the registry fields, and `update`. `server status` retries challenged HTTP health checks and reports a verification remedy instead of removing metadata for an unreachable or identity-mismatched server. `server stop` removes only confirmed stale metadata or signals a Codegraph process whose proven health identity matches the registry.
+
+The v2 registry contains process metadata and a non-secret credential ID; the secret stays in the per-user Codegraph state directory, outside the project and separate from package files and compiler cache data. A live v1 registry is never signaled, so stop its old process manually before a new start.
+
+Use `mcp serve` directly when another process manager owns the server:
 
 ```bash
 codegraph mcp serve --root /path/to/repo --port 7331 --warmup
@@ -29,11 +43,11 @@ codegraph mcp serve --root . --port 7331 --warmup-symbols
 
 The shared HTTP endpoint is `http://127.0.0.1:7331/mcp`. HTTP binds to `127.0.0.1` by default; pass `--host <host>` only when another machine or container must reach it.
 
-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.
+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). The CLI option is valid only with `--stdio`; HTTP transport has its own 30-minute idle session eviction.
 
 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.
+Each MCP server permits four concurrent tool calls by default across every HTTP request and protocol session; a saturated server 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. Completed legacy requests refresh session activity before idle eviction is considered.
 
 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.
 
@@ -41,11 +55,13 @@ Use stdio for a client-owned subprocess. Use HTTP for one long-running codegraph
 
 codegraph uses the official MCP SDK v2 to serve current 2026-07-28 clients while retaining compatibility with 2025-era clients. MCP protocol connections and HTTP protocol sessions keep separate transport state, but all share the server's one warm codegraph analysis session for the configured root. Tool request schemas set `additionalProperties: false` and reject unknown fields with an actionable invalid-parameter error instead of silently ignoring typos.
 
+Malformed tool arguments return JSON-RPC `-32602`; unknown tool names return typed JSON-RPC method errors. Expected execution failures, including missing files, out-of-root paths, and read-only build refusal, return a `tools/call` result with `isError: true` and sanitized/redacted path text rather than a protocol internal error.
+
 HTTP enforces Host and Origin policies. A missing `Origin` is accepted for non-browser clients; unapproved, malformed, and opaque origins are rejected. This is not authentication: binding `--host` to a non-loopback address exposes an unauthenticated endpoint intended only for trusted networks or containers.
 
 ## Runtime identity and updates
 
-The MCP initialize response advertises the codegraph package version captured when the server starts. The server checks its captured package metadata path at most once every 30 seconds during tool calls; a changed or temporarily unavailable installation produces a deduplicated stderr warning but does not fail the request or terminate the server.
+The MCP initialize response advertises the codegraph package version captured when the server starts. MCP tool calls share one cached checker that reads captured package metadata at most once every 30 seconds and emits a deduplicated stderr warning when the installation changes or is unavailable. The health endpoint uses its own cached silent checker, so a health call and a tool call can each read package metadata in the same interval without failing the request or terminating the server.
 
 On Windows, installed-package servers map the verified native addon from `%LOCALAPPDATA%\codegraph\native-cache\v1`, not from npm's package directory. An old server may therefore remain healthy after npm installs a new release, but it must be restarted to use the new JavaScript runtime and cache identity.
 
@@ -84,7 +100,7 @@ Compact contracts for high-traffic tools (`src/mcp/tools.ts`). Write gating: onl
 
 | 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                    |
+| `search`         | `query`  | `mode`: hybrid\|symbol\|path\|text\|graph\|sql; optional `from`, `depth`, `limit` | `depth` 1, `limit` 20                                         | `depth` 5, `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                    |
@@ -104,7 +120,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. 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.
+Use `refresh_index` to rebuild the snapshot, reset SQLite artifact state, or recover after a change burst exceeds automatic limits. Concurrent refresh, artifact build, and automatic SQLite artifact refresh operations serialize per MCP server so each bundle is written consistently. 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`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzehrung/codegraph",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "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.1",
+    "@lzehrung/codegraph-core": "2.2.0",
     "@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.1"
+    "@lzehrung/codegraph-native": "^1.11.0"
   }
 }

package/dist/languages/definitions/loadLanguage.d.ts

@@ -1,2 +0,0 @@
-export { loadTreeSitterLanguage, loadTypeScriptGrammars } from "../../parserBackend.js";
-//# sourceMappingURL=loadLanguage.d.ts.map

package/dist/languages/definitions/loadLanguage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loadLanguage.d.ts","sourceRoot":"","sources":["../../../src/languages/definitions/loadLanguage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/languages/definitions/loadLanguage.js

@@ -1,2 +0,0 @@
-export { loadTreeSitterLanguage, loadTypeScriptGrammars } from "../../parserBackend.js";
-//# sourceMappingURL=loadLanguage.js.map

package/dist/languages/definitions/loadLanguage.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"loadLanguage.js","sourceRoot":"","sources":["../../../src/languages/definitions/loadLanguage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/parserBackend.d.ts

@@ -1,57 +0,0 @@
-export interface SyntaxPoint {
-    row: number;
-    column: number;
-}
-export interface ParserSyntaxNode {
-    readonly id?: number;
-    type: string;
-    text: string;
-    startIndex: number;
-    endIndex: number;
-    startPosition: SyntaxPoint;
-    endPosition: SyntaxPoint;
-    parent: ParserSyntaxNode | null;
-    namedChildren: ParserSyntaxNode[];
-    previousSibling?: ParserSyntaxNode | null;
-    previousNamedSibling?: ParserSyntaxNode | null;
-    child(index: number): ParserSyntaxNode | null;
-    childForFieldName(fieldName: string): ParserSyntaxNode | null;
-}
-export interface ParserSyntaxTree {
-    rootNode: ParserSyntaxNode & {
-        descendantForIndex(startIndex: number, endIndex: number): ParserSyntaxNode;
-        descendantForPosition(start: SyntaxPoint, end: SyntaxPoint): ParserSyntaxNode;
-    };
-    walk(): unknown;
-}
-export interface ParserLanguage {
-    readonly name?: string;
-}
-export interface QueryPoint {
-    row: number;
-    column: number;
-    index: number;
-}
-export interface QueryCapture {
-    name: string;
-    text: string;
-    nodeType: string;
-    start: QueryPoint;
-    end: QueryPoint;
-}
-export interface QueryMatch {
-    patternIndex: number;
-    captures: QueryCapture[];
-}
-export declare function __resetParserBackendModuleForTests(): void;
-export declare function isNonNativeParserAvailable(): boolean;
-export declare function isNonNativeParserUnavailableError(error: unknown): boolean;
-export declare function loadTreeSitterLanguage(packageName: string): ParserLanguage;
-export declare function loadTypeScriptGrammars(): {
-    typescript: ParserLanguage;
-    tsx: ParserLanguage;
-};
-export declare function parseWithLanguage(_source: string, _language: ParserLanguage): ParserSyntaxTree;
-export declare function isParserSyntaxTree(tree: unknown): tree is ParserSyntaxTree;
-export declare function executeQueryAsNativeMatches(_source: string, _language: ParserLanguage, _queryText: string, _tree?: ParserSyntaxTree): QueryMatch[];
-//# sourceMappingURL=parserBackend.d.ts.map

package/dist/parserBackend.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parserBackend.d.ts","sourceRoot":"","sources":["../src/parserBackend.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,WAAW,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,eAAe,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C,oBAAoB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC9C,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,gBAAgB,GAAG;QAC3B,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC;QAC3E,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,gBAAgB,CAAC;KAC/E,CAAC;IACF,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AASD,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzE;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAE1E;AAED,wBAAgB,sBAAsB,IAAI;IACxC,UAAU,EAAE,cAAc,CAAC;IAC3B,GAAG,EAAE,cAAc,CAAC;CACrB,CAKA;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,gBAAgB,CAE9F;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,gBAAgB,CAE1E;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,gBAAgB,GACvB,UAAU,EAAE,CAEd"}

package/dist/parserBackend.js

@@ -1,33 +0,0 @@
-const NON_NATIVE_PARSER_UNAVAILABLE_PREFIX = "Non-native Tree-sitter parser is unavailable";
-const NON_NATIVE_PARSER_UNAVAILABLE_SUFFIX = "native parser is the only grammar backend";
-function createUnavailableError(feature) {
-    return new Error(`${NON_NATIVE_PARSER_UNAVAILABLE_PREFIX} for ${feature}; ${NON_NATIVE_PARSER_UNAVAILABLE_SUFFIX}`);
-}
-export function __resetParserBackendModuleForTests() {
-    // Kept for tests that reset parser backends between cases.
-}
-export function isNonNativeParserAvailable() {
-    return false;
-}
-export function isNonNativeParserUnavailableError(error) {
-    return error instanceof Error && error.message.includes(NON_NATIVE_PARSER_UNAVAILABLE_PREFIX);
-}
-export function loadTreeSitterLanguage(packageName) {
-    return { name: packageName };
-}
-export function loadTypeScriptGrammars() {
-    return {
-        typescript: { name: "tree-sitter-typescript/typescript" },
-        tsx: { name: "tree-sitter-typescript/tsx" },
-    };
-}
-export function parseWithLanguage(_source, _language) {
-    throw createUnavailableError("syntax-tree parsing");
-}
-export function isParserSyntaxTree(tree) {
-    return typeof tree === "object" && tree !== null && "rootNode" in tree && "walk" in tree;
-}
-export function executeQueryAsNativeMatches(_source, _language, _queryText, _tree) {
-    throw createUnavailableError("query execution");
-}
-//# sourceMappingURL=parserBackend.js.map

package/dist/parserBackend.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"parserBackend.js","sourceRoot":"","sources":["../src/parserBackend.ts"],"names":[],"mappings":"AAoDA,MAAM,oCAAoC,GAAG,8CAA8C,CAAC;AAC5F,MAAM,oCAAoC,GAAG,2CAA2C,CAAC;AAEzF,SAAS,sBAAsB,CAAC,OAAe;IAC7C,OAAO,IAAI,KAAK,CAAC,GAAG,oCAAoC,QAAQ,OAAO,KAAK,oCAAoC,EAAE,CAAC,CAAC;AACtH,CAAC;AAED,MAAM,UAAU,kCAAkC;IAChD,2DAA2D;AAC7D,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,KAAc;IAC9D,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,oCAAoC,CAAC,CAAC;AAChG,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,sBAAsB;IAIpC,OAAO;QACL,UAAU,EAAE,EAAE,IAAI,EAAE,mCAAmC,EAAE;QACzD,GAAG,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,SAAyB;IAC1E,MAAM,sBAAsB,CAAC,qBAAqB,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,UAAU,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,SAAyB,EACzB,UAAkB,EAClB,KAAwB;IAExB,MAAM,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;AAClD,CAAC"}