@opencodehub/mcp 0.1.0

package/dist/tools/shared.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared scaffolding for MCP tool handlers.
+ *
+ * Each tool depends on a `ToolContext` that carries the connection pool
+ * (for checkout/release) plus the registry home override (to let tests
+ * point at a fake `~/.codehub`). The factory functions in `server.ts`
+ * construct one `ToolContext` per server and pass it into every
+ * `registerXxxTool` call.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { FsAbstraction } from "@opencodehub/analysis";
+import type { Embedder } from "@opencodehub/embedder";
+import { type Store } from "@opencodehub/storage";
+import { z } from "zod";
+import type { ConnectionPool } from "../connection-pool.js";
+import { type ResolvedRepo } from "../repo-resolver.js";
+/**
+ * Factory for opening an embedder on demand. The default factory imports
+ * `@opencodehub/embedder` and calls `openOnnxEmbedder()`; tests inject a
+ * fake so they don't need gte-modernbert-base weights on disk. The factory
+ * must throw on failure — the `query` tool treats any throw as
+ * "embedder unavailable, warn + fall back to BM25".
+ */
+export type EmbedderFactory = () => Promise<Embedder>;
+export interface ToolContext {
+    readonly pool: ConnectionPool;
+    readonly home?: string;
+    /**
+     * Optional override for how the `query` tool opens an embedder when the
+     * `embeddings` table is populated. Production callers leave this unset
+     * and the tool lazy-imports `@opencodehub/embedder`.
+     */
+    readonly openEmbedder?: EmbedderFactory;
+    /**
+     * Optional factory for the file-reading abstraction used when tools need
+     * to slice source files (e.g. `query` snippet extraction,
+     * `remove_dead_code` edit planning). Production callers leave this unset
+     * and the tools use `createNodeFs()`.
+     */
+    readonly fsFactory?: () => FsAbstraction;
+}
+export type RegisteredServer = McpServer;
+/**
+ * Transport-agnostic tool result shape. The MCP-registered handler
+ * adapts this into the SDK's `CallToolResult`. Keep this minimal — `text`
+ * is the rendered agent-readable body; `structuredContent` carries the
+ * machine-readable payload (with `next_steps`, `error`, `_meta.*` as
+ * usual); `isError` mirrors the MCP semantics.
+ */
+export interface ToolResult {
+    readonly structuredContent: unknown;
+    readonly text: string;
+    readonly isError?: boolean;
+}
+/**
+ * Convert an MCP `CallToolResult` to the transport-agnostic `ToolResult`.
+ * The SDK result always carries at least one `{ type: 'text', text }`
+ * content entry in our tools, so the extraction is lossless in practice.
+ */
+export declare function toToolResult(r: CallToolResult): ToolResult;
+/**
+ * Convert a transport-agnostic `ToolResult` back to the MCP SDK shape.
+ * The MCP-registered handler uses this so it can return exactly the
+ * `CallToolResult` shape the SDK expects.
+ */
+export declare function fromToolResult(r: ToolResult): CallToolResult;
+/**
+ * Shared zod shape for `{ repo, repo_uri }` — every per-repo MCP tool
+ * spreads this into its `inputSchema` so callers can pass either the
+ * registry name (`repo`) or a Sourcegraph-style URI (`repo_uri`). When
+ * both are provided, `repo_uri` wins at the resolver.
+ */
+export declare const repoArgShape: {
+    readonly repo: z.ZodOptional<z.ZodString>;
+    readonly repo_uri: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Shape of the `{ repo, repo_uri }` arg pair accepted by tool handlers.
+ *
+ * Permits explicit `undefined` values so tool-handler arg types (which
+ * declare `repo?: string | undefined` under `exactOptionalPropertyTypes`)
+ * are structurally assignable without wrapping.
+ */
+export interface RepoArgs {
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+}
+/**
+ * Acquire a store for the given repo argument, invoke `fn`, and release
+ * the handle unconditionally. Errors from repo resolution become
+ * structured NO_INDEX/NOT_FOUND envelopes; DuckDB errors become DB_ERROR.
+ * The inner function always returns a CallToolResult so the surface of
+ * this helper is the same type.
+ *
+ * `arg` accepts either a bare registry name (back-compat with pre-M6
+ * callers), an `undefined` (single-repo defaulting), or the full
+ * `{ repo?, repo_uri? }` object. The resolver handles the alias logic.
+ */
+export declare function withStore(ctx: ToolContext, arg: RepoArgs | string | undefined, fn: (store: Store, resolved: ResolvedRepo) => Promise<CallToolResult>): Promise<CallToolResult>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/tools/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAqB,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAoB,KAAK,YAAY,EAAe,MAAM,qBAAqB,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,aAAa,CAAC;CAC1C;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,cAAc,GAAG,UAAU,CAS1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,GAAG,cAAc,CAQ5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;CAaf,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,EAClC,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,KAAK,OAAO,CAAC,cAAc,CAAC,GACpE,OAAO,CAAC,cAAc,CAAC,CA2CzB"}

package/dist/tools/shared.js

@@ -0,0 +1,114 @@
+/**
+ * Shared scaffolding for MCP tool handlers.
+ *
+ * Each tool depends on a `ToolContext` that carries the connection pool
+ * (for checkout/release) plus the registry home override (to let tests
+ * point at a fake `~/.codehub`). The factory functions in `server.ts`
+ * construct one `ToolContext` per server and pass it into every
+ * `registerXxxTool` call.
+ */
+import { describeArtifacts } from "@opencodehub/storage";
+import { z } from "zod";
+import { toolAmbiguousRepoError, toolError, toolErrorFromUnknown } from "../error-envelope.js";
+import { RepoResolveError, resolveRepo } from "../repo-resolver.js";
+/**
+ * Convert an MCP `CallToolResult` to the transport-agnostic `ToolResult`.
+ * The SDK result always carries at least one `{ type: 'text', text }`
+ * content entry in our tools, so the extraction is lossless in practice.
+ */
+export function toToolResult(r) {
+    const first = r.content[0];
+    const text = first && first.type === "text" ? first.text : "";
+    const out = {
+        structuredContent: r.structuredContent,
+        text,
+    };
+    if (r.isError)
+        out.isError = true;
+    return out;
+}
+/**
+ * Convert a transport-agnostic `ToolResult` back to the MCP SDK shape.
+ * The MCP-registered handler uses this so it can return exactly the
+ * `CallToolResult` shape the SDK expects.
+ */
+export function fromToolResult(r) {
+    const sc = r.structuredContent;
+    const out = {
+        content: [{ type: "text", text: r.text }],
+        ...(sc !== undefined ? { structuredContent: sc } : {}),
+    };
+    if (r.isError)
+        out.isError = true;
+    return out;
+}
+/**
+ * Shared zod shape for `{ repo, repo_uri }` — every per-repo MCP tool
+ * spreads this into its `inputSchema` so callers can pass either the
+ * registry name (`repo`) or a Sourcegraph-style URI (`repo_uri`). When
+ * both are provided, `repo_uri` wins at the resolver.
+ */
+export const repoArgShape = {
+    repo: z
+        .string()
+        .optional()
+        .describe("Registered repo name. Required when ≥ 2 repos are registered; optional when exactly one is. Prefer `repo_uri` for cross-host portability."),
+    repo_uri: z
+        .string()
+        .optional()
+        .describe("Sourcegraph-style repo URI (e.g. `github.com/org/repo`, or `local:<hash>` for unpublished repos). Accepted as an alias for `repo`; wins when both are provided."),
+};
+/**
+ * Acquire a store for the given repo argument, invoke `fn`, and release
+ * the handle unconditionally. Errors from repo resolution become
+ * structured NO_INDEX/NOT_FOUND envelopes; DuckDB errors become DB_ERROR.
+ * The inner function always returns a CallToolResult so the surface of
+ * this helper is the same type.
+ *
+ * `arg` accepts either a bare registry name (back-compat with pre-M6
+ * callers), an `undefined` (single-repo defaulting), or the full
+ * `{ repo?, repo_uri? }` object. The resolver handles the alias logic.
+ */
+export async function withStore(ctx, arg, fn) {
+    let resolved;
+    try {
+        const opts = ctx.home !== undefined ? { home: ctx.home } : {};
+        resolved = await resolveRepo(arg, opts);
+    }
+    catch (err) {
+        if (err instanceof RepoResolveError) {
+            if (err.code === "AMBIGUOUS_REPO" && err.ambiguous !== undefined) {
+                return toolAmbiguousRepoError({
+                    message: err.message,
+                    hint: err.hint,
+                    choices: err.ambiguous.choices,
+                    totalMatches: err.ambiguous.totalMatches,
+                });
+            }
+            return toolError(err.code, err.message, err.hint);
+        }
+        return toolErrorFromUnknown(err);
+    }
+    let store;
+    try {
+        store = await ctx.pool.acquire(resolved.repoPath, resolved.dbPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Enumerate every in-tree backend's artifact filename so the hint is
+        // useful regardless of which backend produced the index. Pulling the
+        // filenames from `describeArtifacts` keeps two-store deployments in
+        // sync with a single source of truth.
+        const candidates = ["duck", "lbug"]
+            .map((b) => `.codehub/${describeArtifacts(b).graphFile}`)
+            .join(" or ");
+        return toolError("DB_ERROR", `Failed to open store at ${resolved.dbPath}: ${msg}`, `Ensure the repo was indexed and that the ${candidates} file is readable.`);
+    }
+    try {
+        return await fn(store, resolved);
+    }
+    finally {
+        await ctx.pool.release(resolved.repoPath);
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/tools/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,iBAAiB,EAAc,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAqB,WAAW,EAAE,MAAM,qBAAqB,CAAC;AA4CvF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,CAAiB;IAC5C,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,MAAM,GAAG,GAAoE;QAC3E,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;QACtC,IAAI;KACL,CAAC;IACF,IAAI,CAAC,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;IAClC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,CAAa;IAC1C,MAAM,EAAE,GAAG,CAAC,CAAC,iBAA2D,CAAC;IACzE,MAAM,GAAG,GAAmB;QAC1B,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC;IACF,IAAI,CAAC,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;IAClC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,2IAA2I,CAC5I;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iKAAiK,CAClK;CACK,CAAC;AAcX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAgB,EAChB,GAAkC,EAClC,EAAqE;IAErE,IAAI,QAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,QAAQ,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBACjE,OAAO,sBAAsB,CAAC;oBAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,OAAO;oBAC9B,YAAY,EAAE,GAAG,CAAC,SAAS,CAAC,YAAY;iBACzC,CAAC,CAAC;YACL,CAAC;YACD,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,KAAY,CAAC;IACjB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,qEAAqE;QACrE,qEAAqE;QACrE,oEAAoE;QACpE,sCAAsC;QACtC,MAAM,UAAU,GAAI,CAAC,MAAM,EAAE,MAAM,CAAW;aAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;aACxD,IAAI,CAAC,MAAM,CAAC,CAAC;QAChB,OAAO,SAAS,CACd,UAAU,EACV,2BAA2B,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,EACpD,4CAA4C,UAAU,oBAAoB,CAC3E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;YAAS,CAAC;QACT,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC"}

package/dist/tools/signature.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `signature` — return a symbol's declaration header with bodies elided.
+ *
+ * Token-saving alternative to reading a whole file. For a class or interface,
+ * emits the type declaration followed by every child method / property as a
+ * stub: signature line + language-appropriate body placeholder (`;`, `{ }`,
+ * or `pass` / `...` for Python). For a standalone function, emits a single
+ * signature stub.
+ *
+ * Resolution mirrors `context`: `name` is required (or `uid` when the caller
+ * already has a node id), with optional `filePath` / `kind` / `repo` for
+ * disambiguation. A multi-candidate match returns the candidate list, not
+ * one arbitrary pick (EC-04 behaviour from context.ts).
+ *
+ * SQL shape:
+ *   - one `SELECT … FROM nodes WHERE name/id=?` to resolve the target,
+ *   - one follow-up `SELECT … FROM relations JOIN nodes …` for
+ *     HAS_METHOD + HAS_PROPERTY children when the target is a type.
+ *
+ * Signature text comes from `CallableShape.signature` when populated by the
+ * parse / complexity phases; otherwise we reconstruct `name(p1,...,pN): T`
+ * from `parameter_count` + `return_type`. Language detection keys off the
+ * file extension alone — the node rows don't carry an explicit language tag.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface SignatureArgs {
+    readonly name?: string | undefined;
+    readonly uid?: string | undefined;
+    readonly filePath?: string | undefined;
+    readonly kind?: string | undefined;
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+}
+export declare function runSignature(ctx: ToolContext, args: SignatureArgs): Promise<ToolResult>;
+export declare function registerSignatureTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=signature.d.ts.map

package/dist/tools/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/tools/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOzE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAyDrB,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAgF7F;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiB/E"}

package/dist/tools/signature.js

@@ -0,0 +1,332 @@
+/**
+ * `signature` — return a symbol's declaration header with bodies elided.
+ *
+ * Token-saving alternative to reading a whole file. For a class or interface,
+ * emits the type declaration followed by every child method / property as a
+ * stub: signature line + language-appropriate body placeholder (`;`, `{ }`,
+ * or `pass` / `...` for Python). For a standalone function, emits a single
+ * signature stub.
+ *
+ * Resolution mirrors `context`: `name` is required (or `uid` when the caller
+ * already has a node id), with optional `filePath` / `kind` / `repo` for
+ * disambiguation. A multi-candidate match returns the candidate list, not
+ * one arbitrary pick (EC-04 behaviour from context.ts).
+ *
+ * SQL shape:
+ *   - one `SELECT … FROM nodes WHERE name/id=?` to resolve the target,
+ *   - one follow-up `SELECT … FROM relations JOIN nodes …` for
+ *     HAS_METHOD + HAS_PROPERTY children when the target is a type.
+ *
+ * Signature text comes from `CallableShape.signature` when populated by the
+ * parse / complexity phases; otherwise we reconstruct `name(p1,...,pN): T`
+ * from `parameter_count` + `return_type`. Language detection keys off the
+ * file extension alone — the node rows don't carry an explicit language tag.
+ */
+// biome-ignore-all lint/complexity/useLiteralKeys: dot-access disallowed on Record index signatures
+import { z } from "zod";
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { stalenessFromMeta } from "../staleness.js";
+import { fromToolResult, repoArgShape, toToolResult, withStore, } from "./shared.js";
+const SignatureInput = {
+    name: z
+        .string()
+        .optional()
+        .describe("Symbol name to inspect (class, interface, function, method). Mutually exclusive with `uid`."),
+    uid: z
+        .string()
+        .optional()
+        .describe("Pre-resolved node id (skips name lookup). Mutually exclusive with `name`."),
+    filePath: z
+        .string()
+        .optional()
+        .describe("Optional file-path suffix to disambiguate same-named symbols."),
+    kind: z
+        .string()
+        .optional()
+        .describe("Optional NodeKind to disambiguate (e.g. 'Class' vs 'Function')."),
+    ...repoArgShape,
+};
+/** Kinds treated as aggregate "type declarations" with method / property children. */
+const TYPE_KINDS = new Set([
+    "Class",
+    "Interface",
+    "Struct",
+    "Trait",
+    "Enum",
+    "Record",
+    "Union",
+    "Impl",
+    "Namespace",
+    "Module",
+    "Protocol",
+]);
+const CALLABLE_KINDS = new Set(["Function", "Method", "Constructor"]);
+const PROPERTY_KINDS = new Set(["Property", "Const", "Static", "Variable", "Field"]);
+export async function runSignature(ctx, args) {
+    const call = await withStore(ctx, args, async (store, resolved) => {
+        try {
+            if (args.name === undefined && args.uid === undefined) {
+                return withNextSteps("signature requires either `name` or `uid`.", { target: null, candidates: [] }, ["re-call `signature` with `name` or `uid`"], stalenessFromMeta(resolved.meta));
+            }
+            const matches = await resolveMatches(store.graph, args);
+            if (matches.length === 0) {
+                const probe = args.name ?? args.uid ?? "<unspecified>";
+                return withNextSteps(`No symbol matched "${probe}" in ${resolved.name}.`, { target: null, candidates: [] }, ["call `query` with a broader phrase to locate similar symbols"], stalenessFromMeta(resolved.meta));
+            }
+            if (matches.length > 1) {
+                const probe = args.name ?? args.uid ?? "<unspecified>";
+                const list = matches
+                    .map((c, i) => `${i + 1}. [${c.kind}] ${c.filePath}  (${c.id})`)
+                    .join("\n");
+                return withNextSteps(`"${probe}" is ambiguous (${matches.length} matches):\n${list}`, { target: null, candidates: matches }, ["re-call `signature` with `kind` or `filePath` to pick a specific match"], stalenessFromMeta(resolved.meta));
+            }
+            const target = matches[0];
+            if (!target) {
+                return withNextSteps("No symbol matched.", { target: null, candidates: [] }, ["call `query` with a broader phrase to locate similar symbols"], stalenessFromMeta(resolved.meta));
+            }
+            const language = detectLanguage(target.filePath);
+            let members = [];
+            if (TYPE_KINDS.has(target.kind)) {
+                members = await fetchMembers(store.graph, target.id);
+            }
+            const stub = renderStub(target, members, language);
+            const next = [
+                `call \`context\` with symbol="${target.name}" for callers / callees`,
+            ];
+            if (members.length > 0) {
+                next.push(`class has ${members.length} members — use \`context\` on individual members for full signatures`);
+            }
+            return withNextSteps(stub, {
+                target,
+                language,
+                memberCount: members.length,
+                members,
+                stub,
+            }, next, stalenessFromMeta(resolved.meta));
+        }
+        catch (err) {
+            return toolErrorFromUnknown(err);
+        }
+    });
+    return toToolResult(call);
+}
+export function registerSignatureTool(server, ctx) {
+    server.registerTool("signature", {
+        title: "Symbol declaration + stubbed members",
+        description: "Return a class/interface declaration plus its method and property signatures with bodies elided (stub syntax per language). For a standalone function, returns a single signature. Saves tokens vs reading the whole file.",
+        inputSchema: SignatureInput,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => fromToolResult(await runSignature(ctx, args)));
+}
+async function resolveMatches(graph, args) {
+    let candidates;
+    if (args.uid !== undefined) {
+        candidates = await graph.listNodes({ ids: [args.uid] });
+    }
+    else if (args.name !== undefined) {
+        const opts = args.kind !== undefined ? { kinds: [args.kind] } : {};
+        let res = await graph.listNodesByName(args.name, opts);
+        if (args.filePath !== undefined) {
+            const sub = args.filePath;
+            res = res.filter((n) => n.filePath.includes(sub));
+        }
+        candidates = res;
+    }
+    else {
+        return [];
+    }
+    // Match prior ORDER BY file_path LIMIT 25.
+    const sorted = [...candidates].sort((a, b) => a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0);
+    return sorted.slice(0, 25).map(nodeToRow);
+}
+async function fetchMembers(graph, ownerId) {
+    const edges = await graph.listEdges({
+        types: ["HAS_METHOD", "HAS_PROPERTY"],
+        fromIds: [ownerId],
+        limit: 500,
+    });
+    if (edges.length === 0)
+        return [];
+    const partnerIds = Array.from(new Set(edges.map((e) => e.to)));
+    const partners = await graph.listNodes({ ids: partnerIds });
+    const out = partners.map(nodeToRow);
+    out.sort((a, b) => {
+        const as = a.startLine ?? Number.POSITIVE_INFINITY;
+        const bs = b.startLine ?? Number.POSITIVE_INFINITY;
+        if (as !== bs)
+            return as - bs;
+        return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+    });
+    return out;
+}
+function nodeToRow(n) {
+    const any = n;
+    const out = {
+        id: n.id,
+        name: n.name,
+        kind: n.kind,
+        filePath: n.filePath,
+    };
+    const sl = any["startLine"];
+    if (typeof sl === "number" && Number.isFinite(sl))
+        out.startLine = sl;
+    const el = any["endLine"];
+    if (typeof el === "number" && Number.isFinite(el))
+        out.endLine = el;
+    const sig = any["signature"];
+    if (typeof sig === "string" && sig.length > 0)
+        out.signature = sig;
+    const pc = any["parameterCount"];
+    if (typeof pc === "number" && Number.isFinite(pc))
+        out.parameterCount = pc;
+    const rt = any["returnType"];
+    if (typeof rt === "string" && rt.length > 0)
+        out.returnType = rt;
+    return out;
+}
+function detectLanguage(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith(".py") || lower.endsWith(".pyi"))
+        return "python";
+    if (lower.endsWith(".ts") ||
+        lower.endsWith(".tsx") ||
+        lower.endsWith(".js") ||
+        lower.endsWith(".jsx") ||
+        lower.endsWith(".mjs") ||
+        lower.endsWith(".cjs")) {
+        return "typescript";
+    }
+    if (lower.endsWith(".java") || lower.endsWith(".kt") || lower.endsWith(".kts"))
+        return "java";
+    if (lower.endsWith(".go"))
+        return "go";
+    if (lower.endsWith(".rs"))
+        return "rust";
+    if (lower.endsWith(".cs"))
+        return "csharp";
+    if (lower.endsWith(".rb"))
+        return "ruby";
+    return "other";
+}
+/**
+ * Render the target node and its children into a language-appropriate stub.
+ *
+ * For TypeScript/Java/C#: `class Foo { ... }` or `interface Foo { ... }` with
+ * per-member `name(args): ReturnType;` lines. For Python: `class Foo:` with
+ * indented `def name(...) -> ReturnType: ...` / `name: ReturnType` lines.
+ * For Rust/Go we fall back to a language-agnostic text form — the phases
+ * don't always populate `signature` in those languages.
+ */
+function renderStub(target, members, language) {
+    if (!TYPE_KINDS.has(target.kind)) {
+        return renderCallableOrDeclaration(target, language, 0);
+    }
+    if (language === "python") {
+        const header = `class ${target.name}:`;
+        if (members.length === 0)
+            return `${header}\n    pass`;
+        const lines = [header];
+        for (const m of members) {
+            lines.push(renderCallableOrDeclaration(m, language, 4));
+        }
+        return lines.join("\n");
+    }
+    // Default brace-style: TS / Java / C# / Rust / Go / other.
+    const typeWord = typeKeyword(target.kind, language);
+    const header = `${typeWord} ${target.name} {`;
+    if (members.length === 0)
+        return `${header}\n}`;
+    const lines = [header];
+    for (const m of members) {
+        lines.push(renderCallableOrDeclaration(m, language, 2));
+    }
+    lines.push("}");
+    return lines.join("\n");
+}
+function typeKeyword(kind, language) {
+    if (kind === "Interface")
+        return "interface";
+    if (kind === "Struct")
+        return language === "rust" || language === "go" ? "struct" : "class";
+    if (kind === "Trait")
+        return language === "rust" ? "trait" : "interface";
+    if (kind === "Enum")
+        return "enum";
+    if (kind === "Record")
+        return "record";
+    if (kind === "Union")
+        return "union";
+    if (kind === "Impl")
+        return "impl";
+    if (kind === "Namespace")
+        return "namespace";
+    if (kind === "Module")
+        return "module";
+    return "class";
+}
+function renderCallableOrDeclaration(node, language, indent) {
+    const pad = " ".repeat(indent);
+    if (CALLABLE_KINDS.has(node.kind)) {
+        const sig = callableSignature(node, language);
+        if (language === "python")
+            return `${pad}${sig}: ...`;
+        // TS / Java / C# / Rust / Go: emit as a signature declaration.
+        return `${pad}${sig};`;
+    }
+    if (PROPERTY_KINDS.has(node.kind)) {
+        return `${pad}${propertyLine(node, language)};`;
+    }
+    // Unknown child kind — fall back to name only.
+    return `${pad}${node.name};`;
+}
+/**
+ * Prefer the parse-phase-populated `signature` column verbatim. Strip any
+ * leading visibility keyword so classes don't end up with `public public foo`
+ * in the stub; trailing body braces are stripped because we render the stub
+ * body ourselves (`;` or `: ...`).
+ */
+function callableSignature(node, language) {
+    if (node.signature !== undefined) {
+        // Trim trailing body / block if present (e.g. `foo(): T { ... }`).
+        const trimmed = node.signature.trim();
+        const braceIdx = trimmed.indexOf("{");
+        const core = braceIdx === -1 ? trimmed : trimmed.slice(0, braceIdx).trim();
+        // Drop trailing semicolons so the renderer can add its own.
+        return core.replace(/;$/, "").trim();
+    }
+    // Reconstruct from parameterCount + returnType.
+    const argCount = node.parameterCount ?? 0;
+    const argList = Array.from({ length: argCount }, (_, i) => `arg${i}`).join(", ");
+    const ret = node.returnType ?? (language === "python" ? "None" : "void");
+    if (language === "python") {
+        return `def ${node.name}(${argList}) -> ${ret}`;
+    }
+    if (language === "go") {
+        return `func ${node.name}(${argList}) ${ret}`;
+    }
+    if (language === "rust") {
+        return `fn ${node.name}(${argList}) -> ${ret}`;
+    }
+    // TS / Java / C# fallback.
+    return `${node.name}(${argList}): ${ret}`;
+}
+function propertyLine(node, language) {
+    const ret = node.returnType;
+    if (language === "python") {
+        return ret !== undefined ? `${node.name}: ${ret}` : `${node.name} = ...`;
+    }
+    if (language === "go") {
+        return ret !== undefined ? `${node.name} ${ret}` : node.name;
+    }
+    if (language === "rust") {
+        return ret !== undefined ? `${node.name}: ${ret}` : node.name;
+    }
+    return ret !== undefined ? `${node.name}: ${ret}` : node.name;
+}
+//# sourceMappingURL=signature.js.map

package/dist/tools/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/tools/signature.ts"],"names":[],"mappings":"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"}

package/dist/tools/sql.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `sql` — raw read-only SQL / Cypher over the local graph store.
+ *
+ * The tool accepts either `sql` (DuckDB backend) or `cypher` (graph-db
+ * backend, `CODEHUB_STORE=lbug`) — exactly one per call. The read-only
+ * guards (`assertReadOnlySql` / `assertReadOnlyCypher`) reject any write
+ * verb before the statement reaches the underlying engine.
+ *
+ * - SQL path: `SqlGuardError` on violation → INVALID_INPUT envelope.
+ * - Cypher path: `CypherGuardError` on violation → INVALID_INPUT envelope.
+ * - Cypher path without `CODEHUB_STORE=lbug` → INVALID_INPUT with a
+ *   "cypher unavailable" hint.
+ * - Both `sql` and `cypher` supplied → INVALID_INPUT "choose one".
+ *
+ * A default 5 s timeout caps runaway queries (DuckDB itself has no SQL
+ * timeout — the adapter interrupts via a JS timer; the graph-db adapter
+ * honours `timeoutMs` through its pool).
+ *
+ * The tool description embeds the node-kind and relation-type vocabulary
+ * so agents can author correct queries without a separate schema probe.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface SqlArgs {
+    readonly sql?: string | undefined;
+    readonly cypher?: string | undefined;
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+    readonly timeout_ms?: number | undefined;
+}
+export declare function runSql(ctx: ToolContext, args: SqlArgs): Promise<ToolResult>;
+export declare function registerSqlTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=sql.d.ts.map

package/dist/tools/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/tools/sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOzE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAiCrB,UAAU,OAAO;IACf,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAWD,wBAAsB,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAqHjF;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAoBzE"}