@gmickel/gno 1.9.0 → 1.10.0

package/src/mcp/tools/get.ts

@@ -10,11 +10,11 @@ import type { DocumentRow, StorePort } from "../../store/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
-import { parseRef } from "../../cli/commands/ref-parser";
 import {
   getDocumentCapabilities,
   type DocumentCapabilities,
 } from "../../core/document-capabilities";
+import { parseRef } from "../../core/ref-parser";
 import { runTool, type ToolResult } from "./index";
 
 interface GetInput {

package/src/mcp/tools/index.ts

@@ -23,6 +23,7 @@ import { handleJobStatus } from "./job-status";
 import {
   handleBacklinks,
   handleGraph,
+  handleGraphQuery,
   handleGraphNeighbors,
   handleGraphPath,
   handleLinks,
@@ -31,7 +32,7 @@ import {
 import { handleListJobs } from "./list-jobs";
 import { handleListTags } from "./list-tags";
 import { handleMultiGet } from "./multi-get";
-import { handleQuery } from "./query";
+import { handleQuery, handleQueryDiagnose } from "./query";
 import { handleRemoveCollection } from "./remove-collection";
 import { handleSearch } from "./search";
 import { handleStatus } from "./status";
@@ -64,6 +65,8 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "Vector semantic search. Finds conceptually similar docs with different wording. Best after embeddings are current; use intent to disambiguate short terms. Use gno_query for default hybrid retrieval.",
   query:
     "Hybrid search (BM25 + vector + optional expansion/reranking). Recommended default. Use intent for ambiguous terms, queryModes to combine term/intent/hyde strategies, fast=true for quick lookup, thorough=true when recall matters, and candidateLimit to trade latency for coverage.",
+  queryDiagnose:
+    "Diagnose why one target document does or does not appear for a query. Use when an important doc is missing, a filter may exclude it, or you need stage-by-stage BM25/vector/fusion/graph/rerank evidence before changing retrieval strategy.",
   get: "Retrieve one document by gno:// URI, docid (#abc123), or collection/path. After search results include line, pass fromLine and lineCount to fetch only the relevant range before expanding to the full document.",
   multiGet:
     "Retrieve multiple documents by refs array or glob pattern. Use after gno_search/gno_query to batch top result URIs/docids; set maxBytes and lineNumbers to control context size.",
@@ -499,6 +502,16 @@ export const queryInputSchema = z.object({
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });
 
+export const queryDiagnoseInputSchema = queryInputSchema.extend({
+  target: z
+    .string()
+    .trim()
+    .min(1, "Target reference cannot be empty")
+    .describe(
+      "Target document reference to diagnose (gno URI, docid, or collection/path)"
+    ),
+});
+
 const getInputSchema = z.object({
   ref: z
     .string()
@@ -715,6 +728,67 @@ const graphPathInputSchema = graphInputSchema.extend({
     .describe("Maximum relationship hops to search"),
 });
 
+export const graphQueryInputSchema = z.object({
+  ref: z
+    .string()
+    .trim()
+    .min(1, "Reference cannot be empty")
+    .describe(
+      "Root document reference for typed-edge traversal: gno URI, docid, or collection/path"
+    ),
+  direction: z
+    .enum(["both", "out", "in"])
+    .default("both")
+    .describe("Which typed edges to traverse"),
+  edgeType: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Semantic edge type filter, e.g. mentions or works_at"),
+  relation: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Alias for edgeType; must match edgeType when both are set"),
+  maxDepth: z
+    .number()
+    .int()
+    .min(1)
+    .max(6)
+    .optional()
+    .describe("Maximum typed-edge hops to traverse"),
+  depth: z
+    .number()
+    .int()
+    .min(1)
+    .max(6)
+    .optional()
+    .describe("Alias for maxDepth"),
+  maxNodes: z
+    .number()
+    .int()
+    .min(1)
+    .max(1000)
+    .default(100)
+    .describe("Returned node cap"),
+  frontierLimit: z
+    .number()
+    .int()
+    .min(1)
+    .max(1000)
+    .default(100)
+    .describe("Per-depth frontier cap"),
+  visitedLimit: z
+    .number()
+    .int()
+    .min(1)
+    .max(5000)
+    .default(500)
+    .describe("SQL traversal visited-row cap"),
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Result Type
 // ─────────────────────────────────────────────────────────────────────────────
@@ -846,6 +920,13 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleQuery(args, ctx)
   );
 
+  server.tool(
+    "gno_query_diagnose",
+    MCP_TOOL_DESCRIPTIONS.queryDiagnose,
+    queryDiagnoseInputSchema.shape,
+    (args) => handleQueryDiagnose(args, ctx)
+  );
+
   server.tool(
     "gno_get",
     MCP_TOOL_DESCRIPTIONS.get,
@@ -902,6 +983,13 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleGraph(args, ctx)
   );
 
+  server.tool(
+    "gno_graph_query",
+    "Run bounded traversal over typed doc_edges from one root document. Use for explicit relationship questions like 'what does Alice work_at within 2 hops?' or to inspect typed graph hints; returns schemaVersion, root, nodes, edges, caps, and truncation.",
+    graphQueryInputSchema.shape,
+    (args) => handleGraphQuery(args, ctx)
+  );
+
   server.tool(
     "gno_graph_neighbors",
     "Find graph neighbors around a document/node. Use for relationship questions, missed obvious related docs, or unfamiliar corpus navigation after gno_query identifies a seed; returns incoming/outgoing wiki, markdown, and optional similarity edges. Follow with gno_get for targeted reads.",

package/src/mcp/tools/links.ts

@@ -10,14 +10,18 @@ import type {
   BacklinkRow,
   DocLinkRow,
   DocumentRow,
+  GraphQueryDirection,
+  GraphQueryResult,
   GraphLink,
   GraphNode,
   GraphResult,
 } from "../../store/types";
 import type { ToolContext } from "../server";
 
-import { parseRef } from "../../cli/commands/ref-parser";
+import { normalizeContentTypes } from "../../config";
 import { MCP_ERRORS } from "../../core/errors";
+import { diagnoseGraphQuery } from "../../core/graph-query";
+import { parseRef } from "../../core/ref-parser";
 import { normalizeCollectionName } from "../../core/validation";
 import { getActivePreset } from "../../llm/registry";
 import { createVectorIndexPort } from "../../store/vector";
@@ -648,6 +652,18 @@ interface GraphPathInput extends GraphInput {
   maxDepth?: number;
 }
 
+interface GraphQueryInput {
+  ref: string;
+  direction?: GraphQueryDirection;
+  edgeType?: string;
+  relation?: string;
+  maxDepth?: number;
+  depth?: number;
+  maxNodes?: number;
+  frontierLimit?: number;
+  visitedLimit?: number;
+}
+
 interface GraphNeighbor {
   node: GraphNode;
   direction: "out" | "in";
@@ -860,6 +876,72 @@ function formatGraphNeighborsResult(data: GraphNeighborsResult): string {
   return lines.join("\n");
 }
 
+function formatGraphQueryResult(data: GraphQueryResult): string {
+  const lines = [
+    `Typed graph query from ${data.root.uri}: ${data.nodes.length} nodes, ${data.edges.length} edges`,
+    `Direction: ${data.meta.direction}, depth: ${data.meta.maxDepth}`,
+  ];
+  if (data.meta.edgeType) {
+    lines.push(`Edge type: ${data.meta.edgeType}`);
+  }
+  if (data.meta.truncated) {
+    lines.push("Traversal truncated by configured caps");
+  }
+  for (const edge of data.edges.slice(0, 20)) {
+    lines.push(
+      `  ${edge.source} -> ${edge.target} (${edge.edgeType}, ${edge.confidence}, ${edge.edgeSource})`
+    );
+  }
+  return lines.join("\n");
+}
+
+export function handleGraphQuery(
+  args: GraphQueryInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_graph_query",
+    async () => {
+      const edgeTypeValue = args.edgeType?.trim();
+      const relationValue = args.relation?.trim();
+      if (edgeTypeValue && relationValue && edgeTypeValue !== relationValue) {
+        throw new Error(
+          "VALIDATION: edgeType and relation are aliases and must match when both are provided"
+        );
+      }
+      if (
+        args.maxDepth !== undefined &&
+        args.depth !== undefined &&
+        args.maxDepth !== args.depth
+      ) {
+        throw new Error(
+          "VALIDATION: maxDepth and depth are aliases and must match when both are provided"
+        );
+      }
+
+      const result = await diagnoseGraphQuery(ctx.store, args.ref, {
+        direction: args.direction ?? "both",
+        edgeType: edgeTypeValue || relationValue || undefined,
+        maxDepth: args.maxDepth ?? args.depth,
+        maxNodes: args.maxNodes,
+        frontierLimit: args.frontierLimit,
+        visitedLimit: args.visitedLimit,
+        contentTypeRules: normalizeContentTypes(ctx.config.contentTypes ?? [])
+          .rules,
+      });
+      if (!result.success) {
+        throw new Error(
+          `${result.isValidation ? "VALIDATION" : "RUNTIME"}: ${result.error}`
+        );
+      }
+
+      return result.data;
+    },
+    formatGraphQueryResult
+  );
+}
+
 export function handleGraphNeighbors(
   args: GraphNeighborsInput,
   ctx: ToolContext

package/src/mcp/tools/multi-get.ts

@@ -10,7 +10,7 @@ import type { DocumentRow, StorePort } from "../../store/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
-import { parseRef } from "../../cli/commands/ref-parser";
+import { parseRef } from "../../core/ref-parser";
 import { runTool, type ToolResult } from "./index";
 
 interface MultiGetInput {

package/src/mcp/tools/query.ts

@@ -11,6 +11,7 @@ import type {
   GenerationPort,
   RerankPort,
 } from "../../llm/types";
+import type { QueryDiagnoseResult } from "../../pipeline/diagnose";
 import type {
   QueryModeInput,
   SearchResult,
@@ -20,11 +21,16 @@ import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import {
+  fingerprintContentTypeRules,
+  normalizeContentTypes,
+} from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
 import { normalizeStructuredQueryInput } from "../../core/structured-query";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
+import { diagnoseQueryTarget } from "../../pipeline/diagnose";
 import { type HybridSearchDeps, searchHybrid } from "../../pipeline/hybrid";
 import {
   createVectorIndexPort,
@@ -56,6 +62,10 @@ interface QueryInput {
   tagsAny?: string[];
 }
 
+interface QueryDiagnoseInput extends QueryInput {
+  target: string;
+}
+
 /**
  * Enrich results with absPath derived from each result's URI.
  */
@@ -128,6 +138,29 @@ function formatSearchResults(data: SearchResults): string {
   return lines.join("\n");
 }
 
+function formatQueryDiagnoseResult(data: QueryDiagnoseResult): string {
+  if (data.target.status !== "diagnosed") {
+    return `Target ${data.target.ref}: ${data.target.status}`;
+  }
+
+  const lines = [
+    `Query diagnose for ${data.target.uri ?? data.target.ref}`,
+    `Mode: ${data.meta.mode}, results: ${data.meta.totalResults}`,
+    "",
+  ];
+
+  for (const stage of data.stages) {
+    const rank = stage.rank === null ? "-" : `#${stage.rank}`;
+    const score = stage.score === null ? "-" : Number(stage.score).toFixed(3);
+    const reason = stage.dropReason ? `, ${stage.dropReason}` : "";
+    lines.push(
+      `${stage.id}: ${stage.status}, present=${stage.present}, rank=${rank}, score=${score}${reason}`
+    );
+  }
+
+  return lines.join("\n");
+}
+
 /**
  * Handle gno_query tool call.
  */
@@ -311,3 +344,177 @@ export function handleQuery(
     formatSearchResults
   );
 }
+
+/**
+ * Handle gno_query_diagnose tool call.
+ */
+export function handleQueryDiagnose(
+  args: QueryDiagnoseInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_query_diagnose",
+    // oxlint-disable-next-line max-lines-per-function -- mirrors query setup for diagnostic trace ports
+    async () => {
+      let collection: string | undefined;
+      if (args.collection) {
+        const canonical = ctx.collections.find(
+          (c) => c.name.toLowerCase() === args.collection?.toLowerCase()
+        );
+        if (!canonical) {
+          throw new Error(`Collection not found: ${args.collection}`);
+        }
+        collection = canonical.name;
+      }
+
+      const normalizedInput = normalizeStructuredQueryInput(
+        args.query,
+        args.queryModes ?? []
+      );
+      if (!normalizedInput.ok) {
+        throw new Error(normalizedInput.error.message);
+      }
+      const queryText = normalizedInput.value.query;
+      const queryModes =
+        normalizedInput.value.queryModes.length > 0
+          ? normalizedInput.value.queryModes
+          : undefined;
+
+      const preset = getActivePreset(ctx.config);
+      const llm = new LlmAdapter(ctx.config);
+      const policy = resolveDownloadPolicy(process.env, {});
+      const downloadProgress = createNonTtyProgressRenderer();
+
+      let embedPort: EmbeddingPort | null = null;
+      let expandPort: GenerationPort | null = null;
+      let rerankPort: RerankPort | null = null;
+      let vectorIndex: VectorIndexPort | null = null;
+      const embedUri = resolveModelUri(
+        ctx.config,
+        "embed",
+        undefined,
+        collection
+      );
+
+      try {
+        const hasStructuredModes = Boolean(queryModes?.length);
+        const depthPolicy = resolveDepthPolicy({
+          presetId: preset.id,
+          fast: args.fast,
+          thorough: args.thorough,
+          expand: args.expand,
+          rerank: args.rerank,
+          candidateLimit: args.candidateLimit,
+          hasStructuredModes,
+        });
+        const { noExpand, noRerank } = depthPolicy;
+
+        if (!args.fast) {
+          const embedResult = await llm.createEmbeddingPort(embedUri, {
+            policy,
+            onProgress: (progress) => downloadProgress("embed", progress),
+          });
+          if (embedResult.ok) {
+            embedPort = embedResult.value;
+          }
+        }
+
+        if (!noExpand && !hasStructuredModes) {
+          const genResult = await llm.createExpansionPort(
+            resolveModelUri(ctx.config, "expand", undefined, collection),
+            {
+              policy,
+              onProgress: (progress) => downloadProgress("expand", progress),
+            }
+          );
+          if (genResult.ok) {
+            expandPort = genResult.value;
+          }
+        }
+
+        if (!noRerank) {
+          const rerankResult = await llm.createRerankPort(
+            resolveModelUri(ctx.config, "rerank", undefined, collection),
+            {
+              policy,
+              onProgress: (progress) => downloadProgress("rerank", progress),
+            }
+          );
+          if (rerankResult.ok) {
+            rerankPort = rerankResult.value;
+          }
+        }
+
+        if (embedPort) {
+          const embedInitResult = await embedPort.init();
+          if (embedInitResult.ok) {
+            const dimensions = embedPort.dimensions();
+            const db = ctx.store.getRawDb();
+            const vectorResult = await createVectorIndexPort(db, {
+              model: embedUri,
+              dimensions,
+            });
+            if (vectorResult.ok) {
+              vectorIndex = vectorResult.value;
+            }
+          }
+        }
+
+        const deps: HybridSearchDeps = {
+          store: ctx.store,
+          config: ctx.config,
+          vectorIndex,
+          embedPort,
+          expandPort,
+          rerankPort,
+        };
+        const contentTypeRules = normalizeContentTypes(
+          ctx.config.contentTypes ?? []
+        ).rules;
+
+        const result = await diagnoseQueryTarget(deps, queryText, {
+          target: args.target,
+          limit: args.limit ?? 5,
+          minScore: args.minScore,
+          collection,
+          queryLanguageHint: args.lang,
+          intent: args.intent,
+          candidateLimit: depthPolicy.candidateLimit,
+          exclude: args.exclude,
+          since: args.since,
+          until: args.until,
+          categories: args.categories,
+          author: args.author,
+          noExpand,
+          noRerank,
+          graph: args.graph === true,
+          noGraph: args.noGraph || args.fast,
+          queryModes,
+          tagsAll: normalizeTagFilters(args.tagsAll),
+          tagsAny: normalizeTagFilters(args.tagsAny),
+          contentTypeRules,
+          contentTypeRulesFingerprint:
+            fingerprintContentTypeRules(contentTypeRules),
+        });
+
+        if (!result.ok) {
+          throw new Error(result.error.message);
+        }
+
+        return result.value;
+      } finally {
+        if (embedPort) {
+          await embedPort.dispose();
+        }
+        if (expandPort) {
+          await expandPort.dispose();
+        }
+        if (rerankPort) {
+          await rerankPort.dispose();
+        }
+      }
+    },
+    formatQueryDiagnoseResult
+  );
+}