findSymbol() — mcp Function Reference

Architecture documentation for the findSymbol() function in symbol-context.ts from the mcp codebase.

Function typescript AnalysisTools SymbolSearch calls 5 called by 1

Entity Profile

AnalysisTools→ SymbolSearch→ findSymbol() — mcp Function Reference

Dependency Diagram

graph TD
  acad5452_c49c_a5b9_12f1_5263dd556260["findSymbol()"]
  ca77ccf4_30df_6b5c_22dc_f7ba42fd0765["symbol-context.ts"]
  acad5452_c49c_a5b9_12f1_5263dd556260 -->|defined in| ca77ccf4_30df_6b5c_22dc_f7ba42fd0765
  f6b4d8d8_12fd_640f_c545_748d0e260bf0["handler()"]
  f6b4d8d8_12fd_640f_c545_748d0e260bf0 -->|calls| acad5452_c49c_a5b9_12f1_5263dd556260
  2ef71e67_fa6d_b33f_d005_85a400698718["get()"]
  acad5452_c49c_a5b9_12f1_5263dd556260 -->|calls| 2ef71e67_fa6d_b33f_d005_85a400698718
  8893aa60_de59_f01d_9916_ac1f57b0d392["isCodeSymbol()"]
  acad5452_c49c_a5b9_12f1_5263dd556260 -->|calls| 8893aa60_de59_f01d_9916_ac1f57b0d392
  eb291dfa_2490_34b0_4e00_f48c5ed83b89["symbolPriority()"]
  acad5452_c49c_a5b9_12f1_5263dd556260 -->|calls| eb291dfa_2490_34b0_4e00_f48c5ed83b89
  a9cd7456_df1d_b55f_8024_f80fd71f8be4["callerCount()"]
  acad5452_c49c_a5b9_12f1_5263dd556260 -->|calls| a9cd7456_df1d_b55f_8024_f80fd71f8be4
  5b58088c_d9af_5bc6_19ab_1fff095079b9["has()"]
  acad5452_c49c_a5b9_12f1_5263dd556260 -->|calls| 5b58088c_d9af_5bc6_19ab_1fff095079b9
  style acad5452_c49c_a5b9_12f1_5263dd556260 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

src/tools/symbol-context.ts lines 122–202

export function findSymbol(graph: IndexedGraph, query: string): CodeGraphNode[] {
  const lowerQuery = query.toLowerCase();

  // Handle "ClassName.method" syntax
  let className: string | null = null;
  let methodName: string | null = null;
  if (query.includes('.')) {
    const parts = query.split('.');
    className = parts[0];
    methodName = parts.slice(1).join('.');
  }

  // Strategy 1: Exact name match
  const exactIds = graph.nameIndex.get(lowerQuery) || [];
  if (exactIds.length > 0) {
    return exactIds
      .map(id => graph.nodeById.get(id)!)
      .filter(n => n && isCodeSymbol(n))
      .sort((a, b) => {
        const pDiff = symbolPriority(a) - symbolPriority(b);
        if (pDiff !== 0) return pDiff;
        return callerCount(graph, b) - callerCount(graph, a);
      });
  }

  // Strategy 2: ClassName.method match
  if (className && methodName) {
    const methodIds = graph.nameIndex.get(methodName.toLowerCase()) || [];
    const classIds = graph.nameIndex.get(className.toLowerCase()) || [];
    const classFilePaths = new Set(
      classIds.map(id => graph.nodeById.get(id)?.properties?.filePath as string).filter(Boolean)
    );

    const matched = methodIds
      .map(id => graph.nodeById.get(id)!)
      .filter(n => {
        if (!n || !isCodeSymbol(n)) return false;
        const fp = n.properties?.filePath as string;
        return fp && classFilePaths.has(fp);
      });

    if (matched.length > 0) {
      return matched.sort((a, b) => {
        const pDiff = symbolPriority(a) - symbolPriority(b);
        if (pDiff !== 0) return pDiff;
        return callerCount(graph, b) - callerCount(graph, a);
      });
    }
  }

  // Strategy 3: Substring match (for partial names)
  if (lowerQuery.length < 2) {
    return [];
  }

  const substringMatches: CodeGraphNode[] = [];
  for (const [name, ids] of graph.nameIndex) {
    if (name.includes(lowerQuery)) {
      for (const id of ids) {
        const node = graph.nodeById.get(id);
        if (node && isCodeSymbol(node)) {
          substringMatches.push(node);
        }
      }
    }
  }

  // Sort by relevance: exact prefix > contains, then symbol priority, then caller count
  substringMatches.sort((a, b) => {
    const aName = (a.properties?.name as string || '').toLowerCase();
    const bName = (b.properties?.name as string || '').toLowerCase();
    const aPrefix = aName.startsWith(lowerQuery) ? 0 : 1;
    const bPrefix = bName.startsWith(lowerQuery) ? 0 : 1;
    if (aPrefix !== bPrefix) return aPrefix - bPrefix;
    const pDiff = symbolPriority(a) - symbolPriority(b);
    if (pDiff !== 0) return pDiff;
    return callerCount(graph, b) - callerCount(graph, a);
  });

  return substringMatches.slice(0, 10);
}