MCP Tools

Instructions

Implementation Reference

• src/tools/readSymbol.ts:40-79 (handler)

  The main handler function for the read_symbol tool. It processes input arguments, scans files using scanForSymbol generator, collects and scores matching symbol blocks, optimizes output if requested, sorts by score, limits results, and formats the output with file/line info.

  handler: async (args) => {
    const { symbols, file_paths: filePaths = [], limit = DEFAULT_MAX_RESULTS, optimize = true } = args
    if (!filePaths.length) {
      filePaths.push('.')
    }
    const patterns = filePaths.map(mapPattern)
    const results: Block[] = []
    let totalFound = 0
    const maxMatches = MAX_MATCHES * symbols.length
    try {
      for await (const result of scanForSymbol(symbols, patterns)) {
        totalFound++
        results.push(result)
        if (results.length >= maxMatches) {
          break
        }
      }
    } catch (err) {
      if (!results.length) {
        throw err
      }
    }
  
    if (!results.length) {
      if (env.COLLECT_MISMATCHES) {
        collectMismatch({ symbols, file_paths: filePaths, limit })
      }
      throw new Error(`Failed to find the \`${symbols.join(', ') }\` symbol(s) in any files`)
    }
  
    let output = results
      .sort((a, b) => b.score - a.score)
      .slice(0, limit * symbols.length)
      .map(block => formatResult(block, optimize))
      .join('\n\n')
    if (totalFound > results.length) {
      output += `\n\n--- Showing ${results.length} matches out of ${totalFound} ---`
    }
    return output
  },

• src/tools/readSymbol.ts:31-36 (schema)

  Zod schema defining the input parameters for the read_symbol tool: symbols (required array of strings), optional file_paths, limit, and optimize.

  schema: z.object({
    symbols: z.array(z.string().min(1)).describe('Symbol name(s) to find (functions, classes, types, etc.), case-sensitive, supports * for wildcard'),
    file_paths: z.array(z.string().min(1)).optional().describe('File paths to search (supports relative and glob). Defaults to "." (current directory). IMPORTANT: Be specific with paths when possible, minimize broad patterns like "node_modules/**" to avoid mismatches'),
    limit: z.number().optional().describe(`Maximum number of results to return. Defaults to ${DEFAULT_MAX_RESULTS}`),
    optimize: z.boolean().optional().describe('Unless explicitly false, this tool will strip comments and spacing to preserve AI\'s context window, omit unless you REALLY it unchanged (default: true)'),
  }),

• src/tools.ts:22-29 (registration)

  Registers the read_symbol tool (imported as readSymbol) into the central tools object that is exported for use.

  const tools = {
    read_symbol: readSymbol,
    import_symbol: importSymbol,
    search_replace: searchReplace,
    insert_text: insertText,
    os_notification: osNotification,
    utils_debug: utilsDebug,
  } as const satisfies Record<string, Tool<any>>

• src/tools/readSymbol.ts:138-178 (helper)

  Core helper generator that concurrently scans files matching patterns (with ignores), reads contents, finds symbol blocks, and yields matches with concurrency limits and early stopping.

  async function* scanForSymbol(symbols: string[], patterns: string[]): AsyncGenerator<Block> {
    const limit = pLimit(MAX_CONCURRENCY)
    let shouldStop = false
    const ignorePatterns = generateIgnorePatterns(patterns)
    const allPatterns = [...patterns, ...ignorePatterns]
    const entries = fg.stream(allPatterns, {
      cwd: util.CWD, onlyFiles: true, absolute: false, stats: true, suppressErrors: true, deep: 4,
    }) as AsyncIterable<fg.Entry>
    const pendingTasks = new Set<Promise<Block[]>>()
    let filesProcessed = 0
  
    try {
      for await (const entry of entries) {
        if (++filesProcessed === MAX_FILE_COUNT) break
        if (shouldStop) break
        if (entry.stats && entry.stats.size > MAX_FILE_SIZE) continue
  
        const fileIndex = filesProcessed
        const task = limit(async () => {
          if (shouldStop) return []
          try {
            const content = await fs.promises.readFile(util.resolve(entry.path), 'utf8')
            if (shouldStop) return []
            return findBlocks(content, symbols, entry.path, fileIndex)
          } catch {
            return []
          }
        })
  
        pendingTasks.add(task)
        const taskResults = await task
        pendingTasks.delete(task)
        for (const result of taskResults) {
          yield result
        }
      }
    } finally {
      shouldStop = true
      await Promise.allSettled([...pendingTasks])
    }
  }