@gmickel/gno 0.3.0

package/src/mcp/tools/get.ts

@@ -0,0 +1,220 @@
+/**
+ * MCP gno_get tool - Retrieve single document.
+ *
+ * @module src/mcp/tools/get
+ */
+
+import { join as pathJoin } from 'node:path';
+import { parseUri } from '../../app/constants';
+import { parseRef } from '../../cli/commands/ref-parser';
+import type { DocumentRow, StorePort } from '../../store/types';
+import type { ToolContext } from '../server';
+import { runTool, type ToolResult } from './index';
+
+interface GetInput {
+  ref: string;
+  fromLine?: number;
+  lineCount?: number;
+  lineNumbers?: boolean;
+}
+
+interface GetResponse {
+  docid: string;
+  uri: string;
+  title?: string;
+  content: string;
+  totalLines: number;
+  returnedLines?: { start: number; end: number };
+  language?: string;
+  source: {
+    absPath?: string;
+    relPath: string;
+    mime: string;
+    ext: string;
+    modifiedAt?: string;
+    sizeBytes?: number;
+    sourceHash?: string;
+  };
+  conversion?: {
+    converterId?: string;
+    converterVersion?: string;
+    mirrorHash?: string;
+  };
+}
+
+/**
+ * Lookup document by parsed reference.
+ */
+async function lookupDocument(
+  store: StorePort,
+  parsed: ReturnType<typeof parseRef>
+): Promise<DocumentRow | null> {
+  if ('error' in parsed) {
+    return null;
+  }
+
+  switch (parsed.type) {
+    case 'docid': {
+      const result = await store.getDocumentByDocid(parsed.value);
+      return result.ok ? result.value : null;
+    }
+    case 'uri': {
+      const result = await store.getDocumentByUri(parsed.value);
+      return result.ok ? result.value : null;
+    }
+    case 'collPath': {
+      if (!(parsed.collection && parsed.relPath)) {
+        return null;
+      }
+      const result = await store.getDocument(parsed.collection, parsed.relPath);
+      return result.ok ? result.value : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Format get response as text.
+ */
+function formatGetResponse(data: GetResponse): string {
+  const lines: string[] = [];
+
+  lines.push(`Document: ${data.uri}`);
+  if (data.title) {
+    lines.push(`Title: ${data.title}`);
+  }
+  lines.push(`Lines: ${data.totalLines}`);
+  if (data.source.absPath) {
+    lines.push(`Path: ${data.source.absPath}`);
+  }
+  lines.push('');
+
+  if (data.returnedLines) {
+    lines.push(
+      `--- Content (lines ${data.returnedLines.start}-${data.returnedLines.end}) ---`
+    );
+  } else {
+    lines.push('--- Content ---');
+  }
+
+  lines.push(data.content);
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle gno_get tool call.
+ */
+export function handleGet(
+  args: GetInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    'gno_get',
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: document retrieval with multiple ref formats and chunk handling
+    async () => {
+      // Parse reference
+      const parsed = parseRef(args.ref);
+      if ('error' in parsed) {
+        throw new Error(parsed.error);
+      }
+
+      // Lookup document
+      const doc = await lookupDocument(ctx.store, parsed);
+      if (!doc) {
+        throw new Error(`Document not found: ${args.ref}`);
+      }
+
+      // Get content
+      if (!doc.mirrorHash) {
+        throw new Error('Document has no indexed content');
+      }
+
+      const contentResult = await ctx.store.getContent(doc.mirrorHash);
+      if (!contentResult.ok) {
+        throw new Error(contentResult.error.message);
+      }
+
+      const fullContent = contentResult.value ?? '';
+      const contentLines = fullContent.split('\n');
+      const totalLines = contentLines.length;
+
+      // Apply line range if specified
+      let content = fullContent;
+      let returnedLines: { start: number; end: number } | undefined;
+
+      // lineNumbers defaults to true per spec
+      const showLineNumbers = args.lineNumbers !== false;
+
+      if (args.fromLine || args.lineCount) {
+        const startLine = args.fromLine ?? 1;
+        // Clamp startLine to valid range
+        if (startLine > totalLines) {
+          // Return empty content for out-of-range request
+          content = '';
+          returnedLines = undefined;
+        } else {
+          const count = args.lineCount ?? totalLines - startLine + 1;
+          const endLine = Math.min(startLine + count - 1, totalLines);
+
+          const slicedLines = contentLines.slice(startLine - 1, endLine);
+
+          if (showLineNumbers) {
+            content = slicedLines
+              .map((line, i) => `${startLine + i}: ${line}`)
+              .join('\n');
+          } else {
+            content = slicedLines.join('\n');
+          }
+
+          returnedLines = { start: startLine, end: endLine };
+        }
+      } else if (showLineNumbers) {
+        content = contentLines.map((line, i) => `${i + 1}: ${line}`).join('\n');
+      }
+
+      // Build absPath
+      const uriParsed = parseUri(doc.uri);
+      let absPath: string | undefined;
+      if (uriParsed) {
+        const collection = ctx.collections.find(
+          (c) => c.name === uriParsed.collection
+        );
+        if (collection) {
+          absPath = pathJoin(collection.path, doc.relPath);
+        }
+      }
+
+      const response: GetResponse = {
+        docid: doc.docid,
+        uri: doc.uri,
+        title: doc.title ?? undefined,
+        content,
+        totalLines,
+        returnedLines,
+        language: doc.languageHint ?? undefined,
+        source: {
+          absPath,
+          relPath: doc.relPath,
+          mime: doc.sourceMime,
+          ext: doc.sourceExt,
+          modifiedAt: doc.sourceMtime,
+          sizeBytes: doc.sourceSize,
+          sourceHash: doc.sourceHash,
+        },
+        conversion: doc.mirrorHash
+          ? {
+              converterId: doc.converterId ?? undefined,
+              converterVersion: doc.converterVersion ?? undefined,
+              mirrorHash: doc.mirrorHash,
+            }
+          : undefined,
+      };
+
+      return response;
+    },
+    formatGetResponse
+  );
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,160 @@
+/**
+ * MCP tool registration and shared utilities.
+ *
+ * @module src/mcp/tools
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { ToolContext } from '../server';
+import { handleGet } from './get';
+import { handleMultiGet } from './multi-get';
+import { handleQuery } from './query';
+import { handleSearch } from './search';
+import { handleStatus } from './status';
+import { handleVsearch } from './vsearch';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared Input Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+
+const searchInputSchema = z.object({
+  query: z.string().min(1, 'Query cannot be empty'),
+  collection: z.string().optional(),
+  limit: z.number().int().min(1).max(100).default(5),
+  minScore: z.number().min(0).max(1).optional(),
+  lang: z.string().optional(),
+});
+
+const vsearchInputSchema = z.object({
+  query: z.string().min(1, 'Query cannot be empty'),
+  collection: z.string().optional(),
+  limit: z.number().int().min(1).max(100).default(5),
+  minScore: z.number().min(0).max(1).optional(),
+  lang: z.string().optional(),
+});
+
+const queryInputSchema = z.object({
+  query: z.string().min(1, 'Query cannot be empty'),
+  collection: z.string().optional(),
+  limit: z.number().int().min(1).max(100).default(5),
+  minScore: z.number().min(0).max(1).optional(),
+  lang: z.string().optional(),
+  expand: z.boolean().default(true),
+  rerank: z.boolean().default(true),
+});
+
+const getInputSchema = z.object({
+  ref: z.string().min(1, 'Reference cannot be empty'),
+  fromLine: z.number().int().min(1).optional(),
+  lineCount: z.number().int().min(1).optional(),
+  lineNumbers: z.boolean().default(true),
+});
+
+const multiGetInputSchema = z.object({
+  refs: z.array(z.string()).min(1).optional(),
+  pattern: z.string().optional(),
+  maxBytes: z.number().int().min(1).default(10_240),
+  lineNumbers: z.boolean().default(true),
+});
+
+const statusInputSchema = z.object({});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Result Type
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ToolResult {
+  [x: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  structuredContent?: { [x: string]: unknown };
+  isError?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DRY Helper: Exception Firewall + Mutex + Response Shaping
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function runTool<T>(
+  ctx: ToolContext,
+  name: string,
+  fn: () => Promise<T>,
+  formatText: (data: T) => string
+): Promise<ToolResult> {
+  // Check shutdown
+  if (ctx.isShuttingDown()) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'Error: Server is shutting down' }],
+    };
+  }
+
+  // Sequential execution via mutex
+  const release = await ctx.toolMutex.acquire();
+  try {
+    const data = await fn();
+    return {
+      content: [{ type: 'text', text: formatText(data) }],
+      structuredContent: data as { [x: string]: unknown },
+    };
+  } catch (e) {
+    // Exception firewall: never throw, always return isError
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`[MCP] ${name} error:`, message);
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Error: ${message}` }],
+    };
+  } finally {
+    release();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function registerTools(server: McpServer, ctx: ToolContext): void {
+  // Tool IDs use underscores (MCP pattern: ^[a-zA-Z0-9_-]{1,64}$)
+  server.tool(
+    'gno_search',
+    'BM25 full-text search across indexed documents',
+    searchInputSchema.shape,
+    (args) => handleSearch(args, ctx)
+  );
+
+  server.tool(
+    'gno_vsearch',
+    'Vector/semantic similarity search',
+    vsearchInputSchema.shape,
+    (args) => handleVsearch(args, ctx)
+  );
+
+  server.tool(
+    'gno_query',
+    'Hybrid search with optional expansion and reranking',
+    queryInputSchema.shape,
+    (args) => handleQuery(args, ctx)
+  );
+
+  server.tool(
+    'gno_get',
+    'Retrieve a single document by URI, docid, or collection/path',
+    getInputSchema.shape,
+    (args) => handleGet(args, ctx)
+  );
+
+  server.tool(
+    'gno_multi_get',
+    'Retrieve multiple documents by refs or glob pattern',
+    multiGetInputSchema.shape,
+    (args) => handleMultiGet(args, ctx)
+  );
+
+  server.tool(
+    'gno_status',
+    'Get index status and health information',
+    statusInputSchema.shape,
+    (args) => handleStatus(args, ctx)
+  );
+}

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

@@ -0,0 +1,263 @@
+/**
+ * MCP gno_multi_get tool - Retrieve multiple documents.
+ *
+ * @module src/mcp/tools/multi-get
+ */
+
+import { join as pathJoin } from 'node:path';
+import { parseUri } from '../../app/constants';
+import { parseRef } from '../../cli/commands/ref-parser';
+import type { DocumentRow, StorePort } from '../../store/types';
+import type { ToolContext } from '../server';
+import { runTool, type ToolResult } from './index';
+
+interface MultiGetInput {
+  refs?: string[];
+  pattern?: string;
+  maxBytes?: number;
+  lineNumbers?: boolean; // defaults to true per spec
+}
+
+interface DocumentResult {
+  docid: string;
+  uri: string;
+  title?: string;
+  content: string;
+  totalLines: number;
+  truncated: boolean;
+  source: {
+    absPath?: string;
+    relPath: string;
+    mime: string;
+    ext: string;
+    modifiedAt?: string;
+    sizeBytes?: number;
+  };
+}
+
+interface MultiGetResponse {
+  documents: DocumentResult[];
+  skipped: Array<{ ref: string; reason: string }>;
+  meta: {
+    requested: number;
+    returned: number;
+    skipped: number;
+  };
+}
+
+// Default per spec is 10240
+const DEFAULT_MAX_BYTES = 10_240;
+
+/**
+ * Lookup document by parsed reference.
+ */
+async function lookupDocument(
+  store: StorePort,
+  parsed: ReturnType<typeof parseRef>
+): Promise<DocumentRow | null> {
+  if ('error' in parsed) {
+    return null;
+  }
+
+  switch (parsed.type) {
+    case 'docid': {
+      const result = await store.getDocumentByDocid(parsed.value);
+      return result.ok ? result.value : null;
+    }
+    case 'uri': {
+      const result = await store.getDocumentByUri(parsed.value);
+      return result.ok ? result.value : null;
+    }
+    case 'collPath': {
+      if (!(parsed.collection && parsed.relPath)) {
+        return null;
+      }
+      const result = await store.getDocument(parsed.collection, parsed.relPath);
+      return result.ok ? result.value : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Format multi-get response as text.
+ */
+function formatMultiGetResponse(data: MultiGetResponse): string {
+  const lines: string[] = [];
+
+  lines.push(
+    `Retrieved ${data.meta.returned}/${data.meta.requested} documents`
+  );
+  if (data.meta.skipped > 0) {
+    lines.push(`Skipped: ${data.meta.skipped}`);
+  }
+  lines.push('');
+
+  for (const doc of data.documents) {
+    lines.push(`=== ${doc.uri} ===`);
+    if (doc.title) {
+      lines.push(`Title: ${doc.title}`);
+    }
+    lines.push(
+      `Lines: ${doc.totalLines}${doc.truncated ? ' (truncated)' : ''}`
+    );
+    lines.push('');
+    lines.push(doc.content);
+    lines.push('');
+  }
+
+  if (data.skipped.length > 0) {
+    lines.push('--- Skipped ---');
+    for (const s of data.skipped) {
+      lines.push(`${s.ref}: ${s.reason}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle gno_multi_get tool call.
+ */
+export function handleMultiGet(
+  args: MultiGetInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    'gno_multi_get',
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: multi-get with pattern expansion and batch retrieval
+    async () => {
+      // Validate input
+      if (!(args.refs || args.pattern)) {
+        throw new Error('Either refs or pattern must be provided');
+      }
+      if (args.refs && args.pattern) {
+        throw new Error('Cannot specify both refs and pattern');
+      }
+
+      const maxBytes = args.maxBytes ?? DEFAULT_MAX_BYTES;
+      const documents: DocumentResult[] = [];
+      const skipped: Array<{ ref: string; reason: string }> = [];
+
+      let refs: string[] = args.refs ?? [];
+
+      // Pattern-based lookup
+      if (args.pattern) {
+        // For pattern matching, list all documents and filter
+        const listResult = await ctx.store.listDocuments();
+        if (!listResult.ok) {
+          throw new Error(listResult.error.message);
+        }
+
+        // Safe glob-like pattern matching: escape regex metacharacters first
+        const pattern = args.pattern;
+        // Escape all regex metacharacters except * and ?
+        const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        // Then convert glob wildcards to regex
+        const regexPattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+        const regex = new RegExp(`^${regexPattern}$`);
+
+        refs = listResult.value
+          .filter((d) => regex.test(d.uri) || regex.test(d.relPath))
+          .map((d) => d.uri);
+      }
+
+      // Process each reference
+      for (const ref of refs) {
+        const parsed = parseRef(ref);
+        if ('error' in parsed) {
+          skipped.push({ ref, reason: parsed.error });
+          continue;
+        }
+
+        const doc = await lookupDocument(ctx.store, parsed);
+        if (!doc) {
+          skipped.push({ ref, reason: 'Not found' });
+          continue;
+        }
+
+        if (!doc.mirrorHash) {
+          skipped.push({ ref, reason: 'No indexed content' });
+          continue;
+        }
+
+        // Get content
+        const contentResult = await ctx.store.getContent(doc.mirrorHash);
+        if (!contentResult.ok) {
+          skipped.push({ ref, reason: contentResult.error.message });
+          continue;
+        }
+
+        let content = contentResult.value ?? '';
+        let truncated = false;
+
+        // Apply maxBytes truncation (actual UTF-8 bytes, not characters)
+        const contentBuffer = Buffer.from(content, 'utf8');
+        if (contentBuffer.length > maxBytes) {
+          // Truncate by bytes, then decode safely (may cut mid-codepoint)
+          const truncatedBuffer = contentBuffer.subarray(0, maxBytes);
+          // Decode with replacement char for incomplete sequences
+          content = truncatedBuffer.toString('utf8');
+          // Remove potential trailing replacement char from cut codepoint
+          if (content.endsWith('\uFFFD')) {
+            content = content.slice(0, -1);
+          }
+          truncated = true;
+        }
+
+        const contentLines = content.split('\n');
+
+        // Apply line numbers (defaults to true per spec)
+        if (args.lineNumbers !== false) {
+          content = contentLines
+            .map((line, i) => `${i + 1}: ${line}`)
+            .join('\n');
+        }
+
+        // Build absPath
+        const uriParsed = parseUri(doc.uri);
+        let absPath: string | undefined;
+        if (uriParsed) {
+          const collection = ctx.collections.find(
+            (c) => c.name === uriParsed.collection
+          );
+          if (collection) {
+            absPath = pathJoin(collection.path, doc.relPath);
+          }
+        }
+
+        documents.push({
+          docid: doc.docid,
+          uri: doc.uri,
+          title: doc.title ?? undefined,
+          content,
+          totalLines: (contentResult.value ?? '').split('\n').length,
+          truncated,
+          source: {
+            absPath,
+            relPath: doc.relPath,
+            mime: doc.sourceMime,
+            ext: doc.sourceExt,
+            modifiedAt: doc.sourceMtime,
+            sizeBytes: doc.sourceSize,
+          },
+        });
+      }
+
+      const response: MultiGetResponse = {
+        documents,
+        skipped,
+        meta: {
+          requested: refs.length,
+          returned: documents.length,
+          skipped: skipped.length,
+        },
+      };
+
+      return response;
+    },
+    formatMultiGetResponse
+  );
+}