handler() — mcp Function Reference

Source Code

src/tools/symbol-context.ts lines 78–157

export const handler: HandlerFunction = async (client, args, defaultWorkdir) => {
  // Extract symbol list: prefer `symbols` array, fall back to single `symbol`
  let symbolList: string[];
  const symbolsArg = args?.symbols;
  const symbolArg = typeof args?.symbol === 'string' ? args.symbol.trim() : '';

  if (Array.isArray(symbolsArg) && symbolsArg.length > 0) {
    symbolList = symbolsArg
      .filter((s): s is string => typeof s === 'string')
      .map(s => s.trim())
      .filter(s => s.length > 0)
      .slice(0, MAX_BATCH_SYMBOLS);
  } else if (symbolArg) {
    symbolList = [symbolArg];
  } else {
    return asErrorResult({
      type: 'validation_error',
      message: 'Missing required "symbol" or "symbols" parameter.',
      code: 'MISSING_SYMBOL',
      recoverable: false,
      suggestion: 'Provide the name of a function, class, or method to look up.',
    });
  }

  const brief = !!args?.brief;
  const rawDir = args?.directory as string | undefined;
  const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();

  if (!directory || typeof directory !== 'string') {
    return asErrorResult({
      type: 'validation_error',
      message: 'No directory provided and no default workdir configured.',
      code: 'MISSING_DIRECTORY',
      recoverable: false,
      suggestion: 'Provide a directory parameter or start the MCP server with a workdir argument.',
    });
  }

  let graph: IndexedGraph;
  try {
    graph = await resolveOrFetchGraph(client, directory);
  } catch (error: any) {
    return asErrorResult(classifyApiError(error));
  }

  const isBatch = symbolList.length > 1;
  const useBrief = brief || isBatch;

  const allRendered: string[] = [];
  for (const sym of symbolList) {
    const matches = findSymbol(graph, sym);

    if (matches.length === 0) {
      allRendered.push(
        `## ${sym}\n\nNo symbol matching "${sym}" found in the code graph.`
      );
      continue;
    }

    if (useBrief) {
      // Brief mode: compact output for each top match
      const parts = matches.slice(0, 3).map(node => renderBriefSymbolContext(graph, node));
      allRendered.push(parts.join('\n---\n\n'));
      if (matches.length > 3) {
        allRendered.push(`*... and ${matches.length - 3} more matches for "${sym}".*`);
      }
    } else {
      // Full mode: detailed output (single symbol, not brief)
      const parts = await Promise.all(
        matches.slice(0, 3).map(node => renderSymbolContext(graph, node, directory))
      );
      allRendered.push(parts.join('\n---\n\n'));
      if (matches.length > 3) {
        allRendered.push(`*... and ${matches.length - 3} more matches. Use a more specific name to narrow results.*`);
      }
    }
  }

  return asTextContentResult(allRendered.join('\n\n---\n\n'));
};