@gmickel/gno 1.4.2 → 1.5.0

package/src/mcp/tools/index.ts

@@ -21,6 +21,8 @@ import { handleJobStatus } from "./job-status";
 import {
   handleBacklinks,
   handleGraph,
+  handleGraphNeighbors,
+  handleGraphPath,
   handleLinks,
   handleSimilar,
 } from "./links";
@@ -451,6 +453,10 @@ export const queryInputSchema = z.object({
     .boolean()
     .optional()
     .describe("Override: enable/disable cross-encoder reranking"),
+  noGraph: z
+    .boolean()
+    .optional()
+    .describe("Disable bounded one-hop graph neighbor expansion"),
   tagsAll: z.array(z.string()).optional().describe("Require ALL of these tags"),
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });
@@ -637,6 +643,40 @@ const graphInputSchema = z.object({
     .describe("Max similar docs per node when includeSimilar=true"),
 });
 
+const graphNeighborsInputSchema = graphInputSchema.extend({
+  ref: z
+    .string()
+    .trim()
+    .min(1, "Reference cannot be empty")
+    .describe(
+      "Document/node reference: gno URI, #docid, collection/path, relPath, or exact title"
+    ),
+  direction: z
+    .enum(["both", "out", "in"])
+    .default("both")
+    .describe("Which graph edges to follow from the reference node"),
+});
+
+const graphPathInputSchema = graphInputSchema.extend({
+  from: z
+    .string()
+    .trim()
+    .min(1, "From reference cannot be empty")
+    .describe("Starting document/node reference"),
+  to: z
+    .string()
+    .trim()
+    .min(1, "To reference cannot be empty")
+    .describe("Target document/node reference"),
+  maxDepth: z
+    .number()
+    .int()
+    .min(1)
+    .max(12)
+    .default(6)
+    .describe("Maximum relationship hops to search"),
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Result Type
 // ─────────────────────────────────────────────────────────────────────────────
@@ -798,32 +838,46 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
 
   server.tool(
     "gno_links",
-    "Get outgoing wiki ([[links]]) and markdown links from a document.",
+    "Get outgoing wiki ([[links]]) and markdown links from one document. Use after gno_query when you need immediate local expansion from a known source document; use gno_graph_neighbors for bidirectional graph navigation.",
     linksInputSchema.shape,
     (args) => handleLinks(args, ctx)
   );
 
   server.tool(
     "gno_backlinks",
-    "Find all documents that link TO a given document (incoming references).",
+    "Find all documents that link TO a given document. Use after gno_query/gno_get to discover incoming references around a known target; use gno_graph_path for 'how are X and Y connected?' questions.",
     backlinksInputSchema.shape,
     (args) => handleBacklinks(args, ctx)
   );
 
   server.tool(
     "gno_similar",
-    "Find semantically similar documents using vector embeddings. Requires embeddings to exist for source document.",
+    "Find semantically similar documents using vector embeddings. Use for local expansion when wording differs; use gno_query as the default retrieval entry point and gno_graph_neighbors/path for explicit relationship questions.",
     similarInputSchema.shape,
     (args) => handleSimilar(args, ctx)
   );
 
   server.tool(
     "gno_graph",
-    "Get knowledge graph of document connections (wiki links, markdown links, optional similarity edges).",
+    "Get graph report/stats plus nodes/edges for corpus navigation. Use for unfamiliar corpus structure, hubs/isolates/unresolved links, or custom graph analysis; do not replace normal retrieval with this. Start with gno_query for content questions, then graph tools for relationship context, then gno_get for targeted reads.",
     graphInputSchema.shape,
     (args) => handleGraph(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.",
+    graphNeighborsInputSchema.shape,
+    (args) => handleGraphNeighbors(args, ctx)
+  );
+
+  server.tool(
+    "gno_graph_path",
+    "Find the shortest relationship path between two documents/nodes. Use for prompts like 'how are X and Y connected?' or to explain corpus relationships. Use gno_query for finding candidate refs first, then gno_get on path nodes for evidence.",
+    graphPathInputSchema.shape,
+    (args) => handleGraphPath(args, ctx)
+  );
+
   if (ctx.enableWrite) {
     server.tool(
       "gno_capture",

package/src/mcp/tools/links.ts

@@ -10,6 +10,8 @@ import type {
   BacklinkRow,
   DocLinkRow,
   DocumentRow,
+  GraphLink,
+  GraphNode,
   GraphResult,
 } from "../../store/types";
 import type { ToolContext } from "../server";
@@ -635,8 +637,48 @@ interface GraphInput {
   similarTopK?: number;
 }
 
+interface GraphNeighborsInput extends GraphInput {
+  ref: string;
+  direction?: "both" | "out" | "in";
+}
+
+interface GraphPathInput extends GraphInput {
+  from: string;
+  to: string;
+  maxDepth?: number;
+}
+
+interface GraphNeighbor {
+  node: GraphNode;
+  direction: "out" | "in";
+  edge: GraphLink;
+}
+
+interface GraphNeighborsResult {
+  source: GraphNode;
+  neighbors: GraphNeighbor[];
+  meta: GraphResult["meta"] & {
+    direction: "both" | "out" | "in";
+    totalNeighbors: number;
+  };
+}
+
+interface GraphPathResult {
+  from: GraphNode;
+  to: GraphNode;
+  path: {
+    nodes: GraphNode[];
+    edges: GraphLink[];
+  } | null;
+  meta: GraphResult["meta"] & {
+    maxDepth: number;
+    found: boolean;
+    hops: number;
+  };
+}
+
 function formatGraphResult(data: GraphResult): string {
-  const { nodes, links, meta } = data;
+  const { meta, report } = data;
   const lines: string[] = [];
 
   lines.push(
@@ -659,22 +701,51 @@ function formatGraphResult(data: GraphResult): string {
 
   lines.push("");
   lines.push("Top nodes by degree:");
-  const topNodes = [...nodes].sort((a, b) => b.degree - a.degree).slice(0, 10);
-  for (const node of topNodes) {
+  for (const node of report.hubs) {
     const title = node.title ? ` "${node.title}"` : "";
     lines.push(`  [${node.id}] ${node.uri}${title} (degree: ${node.degree})`);
   }
 
-  const edgeTypes = new Map<string, number>();
-  for (const link of links) {
-    edgeTypes.set(link.type, (edgeTypes.get(link.type) ?? 0) + 1);
+  if (report.bridgeCandidates.length > 0) {
+    lines.push("");
+    lines.push("Bridge candidates:");
+    for (const node of report.bridgeCandidates) {
+      const title = node.title ? ` "${node.title}"` : "";
+      lines.push(`  [${node.id}] ${node.uri}${title} (degree: ${node.degree})`);
+    }
   }
 
   lines.push("");
   lines.push("Edge breakdown:");
-  for (const [type, count] of edgeTypes) {
+  for (const [type, count] of Object.entries(report.edgeTypes)) {
     lines.push(`  ${type}: ${count}`);
   }
+  lines.push("Confidence:");
+  for (const [confidence, count] of Object.entries(report.edgeConfidence)) {
+    lines.push(`  ${confidence}: ${count}`);
+  }
+
+  if (report.communities.skipped) {
+    lines.push("");
+    lines.push("Communities: skipped for graph size");
+  } else {
+    lines.push("");
+    lines.push(`Communities: ${report.communities.total}`);
+    for (const community of report.communities.top.slice(0, 5)) {
+      lines.push(
+        `  ${community.id}: ${community.label} (${community.size} docs, ${community.edgeCount} internal edges)`
+      );
+    }
+  }
+
+  lines.push("");
+  lines.push(
+    `Unresolved links: ${report.unresolvedLinks.total} (wiki: ${report.unresolvedLinks.byType.wiki}, markdown: ${report.unresolvedLinks.byType.markdown})`
+  );
+  lines.push(
+    `Audit: inferred ${report.audit.inferredEdges}, ambiguous ${report.audit.ambiguousEdges}, similarity ${report.audit.similarityEdges}`
+  );
+  lines.push(`Isolated documents: ${report.isolated.total}`);
 
   return lines.join("\n");
 }
@@ -720,3 +791,229 @@ export function handleGraph(
     formatGraphResult
   );
 }
+
+async function getValidatedGraph(
+  args: GraphInput,
+  ctx: ToolContext
+): Promise<GraphResult> {
+  let collection: string | undefined;
+  if (args.collection) {
+    collection = normalizeCollectionName(args.collection);
+    const exists = ctx.collections.some(
+      (c) => c.name.toLowerCase() === collection?.toLowerCase()
+    );
+    if (!exists) {
+      throw new Error(
+        `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${args.collection}`
+      );
+    }
+  }
+
+  const result = await ctx.store.getGraph({
+    collection,
+    limitNodes: args.limit ?? 2000,
+    limitEdges: args.edgeLimit ?? 10000,
+    includeSimilar: args.includeSimilar ?? false,
+    threshold: args.threshold ?? 0.7,
+    linkedOnly: args.linkedOnly ?? true,
+    similarTopK: args.similarTopK ?? 5,
+  });
+
+  if (!result.ok) {
+    throw new Error(result.error.message);
+  }
+
+  return result.value;
+}
+
+function resolveGraphNode(graph: GraphResult, ref: string): GraphNode | null {
+  const normalized = ref.trim().toLowerCase();
+  return (
+    graph.nodes.find((node) => {
+      const title = node.title?.toLowerCase();
+      return (
+        node.id.toLowerCase() === normalized ||
+        node.uri.toLowerCase() === normalized ||
+        node.relPath.toLowerCase() === normalized ||
+        `${node.collection}/${node.relPath}`.toLowerCase() === normalized ||
+        title === normalized
+      );
+    }) ?? null
+  );
+}
+
+function formatGraphNeighborsResult(data: GraphNeighborsResult): string {
+  if (data.neighbors.length === 0) {
+    return `No graph neighbors found for ${data.source.uri} (direction=${data.meta.direction})`;
+  }
+
+  const lines = [
+    `Found ${data.neighbors.length} graph neighbors for ${data.source.uri}:`,
+    "",
+  ];
+  for (const item of data.neighbors) {
+    const title = item.node.title ? ` "${item.node.title}"` : "";
+    lines.push(
+      `  [${item.direction}] ${item.node.uri}${title} (${item.edge.type}, ${item.edge.confidence}, weight: ${item.edge.weight})`
+    );
+  }
+  return lines.join("\n");
+}
+
+export function handleGraphNeighbors(
+  args: GraphNeighborsInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_graph_neighbors",
+    async () => {
+      const graph = await getValidatedGraph(args, ctx);
+      const source = resolveGraphNode(graph, args.ref);
+      if (!source) {
+        throw new Error(
+          `${MCP_ERRORS.NOT_FOUND.code}: Graph node not found: ${args.ref}`
+        );
+      }
+
+      const direction = args.direction ?? "both";
+      const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+      const neighbors: GraphNeighbor[] = [];
+
+      for (const edge of graph.links) {
+        if (direction !== "in" && edge.source === source.id) {
+          const node = nodesById.get(edge.target);
+          if (node) neighbors.push({ node, direction: "out", edge });
+        }
+        if (direction !== "out" && edge.target === source.id) {
+          const node = nodesById.get(edge.source);
+          if (node) neighbors.push({ node, direction: "in", edge });
+        }
+      }
+
+      neighbors.sort((a, b) => {
+        if (a.direction !== b.direction) {
+          return a.direction.localeCompare(b.direction);
+        }
+        if (a.edge.type !== b.edge.type) {
+          return a.edge.type.localeCompare(b.edge.type);
+        }
+        return a.node.uri.localeCompare(b.node.uri);
+      });
+
+      return {
+        source,
+        neighbors,
+        meta: {
+          ...graph.meta,
+          direction,
+          totalNeighbors: neighbors.length,
+        },
+      };
+    },
+    formatGraphNeighborsResult
+  );
+}
+
+function findShortestPath(
+  graph: GraphResult,
+  from: GraphNode,
+  to: GraphNode,
+  maxDepth: number
+): { nodes: GraphNode[]; edges: GraphLink[] } | null {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const adjacency = new Map<string, Array<{ next: string; edge: GraphLink }>>();
+  for (const edge of graph.links) {
+    const sourceEdges = adjacency.get(edge.source) ?? [];
+    sourceEdges.push({ next: edge.target, edge });
+    adjacency.set(edge.source, sourceEdges);
+
+    const reverseEdges = adjacency.get(edge.target) ?? [];
+    reverseEdges.push({ next: edge.source, edge });
+    adjacency.set(edge.target, reverseEdges);
+  }
+
+  const queue: Array<{ id: string; pathEdges: GraphLink[] }> = [
+    { id: from.id, pathEdges: [] },
+  ];
+  const visited = new Set([from.id]);
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) break;
+    if (current.id === to.id) {
+      const nodeIds = [from.id];
+      let cursor = from.id;
+      for (const edge of current.pathEdges) {
+        cursor = edge.source === cursor ? edge.target : edge.source;
+        nodeIds.push(cursor);
+      }
+      return {
+        nodes: nodeIds
+          .map((id) => nodesById.get(id))
+          .filter((node): node is GraphNode => node !== undefined),
+        edges: current.pathEdges,
+      };
+    }
+    if (current.pathEdges.length >= maxDepth) continue;
+
+    const edges = adjacency.get(current.id) ?? [];
+    edges.sort((a, b) => a.next.localeCompare(b.next));
+    for (const { next, edge } of edges) {
+      if (visited.has(next)) continue;
+      visited.add(next);
+      queue.push({ id: next, pathEdges: [...current.pathEdges, edge] });
+    }
+  }
+
+  return null;
+}
+
+function formatGraphPathResult(data: GraphPathResult): string {
+  if (!data.path) {
+    return `No graph path found from ${data.from.uri} to ${data.to.uri} within ${data.meta.maxDepth} hops`;
+  }
+
+  const route = data.path.nodes.map((node) => node.uri).join(" -> ");
+  return `Graph path (${data.meta.hops} hops):\n${route}`;
+}
+
+export function handleGraphPath(
+  args: GraphPathInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_graph_path",
+    async () => {
+      const graph = await getValidatedGraph(args, ctx);
+      const from = resolveGraphNode(graph, args.from);
+      if (!from) {
+        throw new Error(
+          `${MCP_ERRORS.NOT_FOUND.code}: Graph node not found: ${args.from}`
+        );
+      }
+      const to = resolveGraphNode(graph, args.to);
+      if (!to) {
+        throw new Error(
+          `${MCP_ERRORS.NOT_FOUND.code}: Graph node not found: ${args.to}`
+        );
+      }
+
+      const maxDepth = args.maxDepth ?? 6;
+      const path = findShortestPath(graph, from, to, maxDepth);
+      return {
+        from,
+        to,
+        path,
+        meta: {
+          ...graph.meta,
+          maxDepth,
+          found: path !== null,
+          hops: path ? path.edges.length : 0,
+        },
+      };
+    },
+    formatGraphPathResult
+  );
+}

package/src/mcp/tools/query.ts

@@ -50,6 +50,7 @@ interface QueryInput {
   thorough?: boolean;
   expand?: boolean;
   rerank?: boolean;
+  noGraph?: boolean;
   tagsAll?: string[];
   tagsAny?: string[];
 }
@@ -271,6 +272,7 @@ export function handleQuery(
           author: args.author,
           noExpand,
           noRerank,
+          noGraph: args.noGraph || args.fast,
           queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),
           tagsAny: normalizeTagFilters(args.tagsAny),

package/src/pipeline/explain.ts

@@ -175,6 +175,7 @@ interface StageTimingsInput {
   expansionMs: number;
   bm25Ms: number;
   vectorMs: number;
+  graphMs: number;
   fusionMs: number;
   rerankMs: number;
   assemblyMs: number;
@@ -190,6 +191,7 @@ export function explainTimings(timings: StageTimingsInput): ExplainLine {
       `expansion=${fmt(timings.expansionMs)}`,
       `bm25=${fmt(timings.bm25Ms)}`,
       `vector=${fmt(timings.vectorMs)}`,
+      `graph=${fmt(timings.graphMs)}`,
       `fusion=${fmt(timings.fusionMs)}`,
       `rerank=${fmt(timings.rerankMs)}`,
       `assembly=${fmt(timings.assemblyMs)}`,

package/src/pipeline/fusion.ts

@@ -62,6 +62,7 @@ export function rrfFuse(
       i.source === "vector_variant" ||
       i.source === "hyde"
   );
+  const graphInputs = inputs.filter((i) => i.source === "graph");
 
   // Process BM25 sources
   // Original query gets 2x weight to prevent dilution by expansion variants
@@ -139,6 +140,33 @@ export function rrfFuse(
     }
   }
 
+  // Process graph expansion sources.
+  for (const input of graphInputs) {
+    const weight = config.bm25Weight * 0.8;
+
+    for (const result of input.results) {
+      const key = `${result.mirrorHash}:${result.seq}`;
+      let candidate = candidates.get(key);
+
+      if (!candidate) {
+        candidate = {
+          mirrorHash: result.mirrorHash,
+          seq: result.seq,
+          bm25Rank: null,
+          vecRank: null,
+          fusionScore: 0,
+          sources: [],
+        };
+        candidates.set(key, candidate);
+      }
+
+      candidate.fusionScore += rrfContribution(result.rank, config.k, weight);
+      if (!candidate.sources.includes(input.source)) {
+        candidate.sources.push(input.source);
+      }
+    }
+  }
+
   // Apply tiered top-rank bonus
   // Rewards documents ranking highly in ANY list (not requiring both)
   for (const candidate of candidates.values()) {