symbol-context.ts — mcp Source File

Source Code

/**
 * `symbol_context` tool -- deep dive on a specific symbol.
 *
 * Given a function, class, or method name, returns (<10KB markdown):
 *  - Definition location (file, line)
 *  - Source code (up to MAX_SOURCE_LINES)
 *  - Callers (who calls this)
 *  - Callees (what this calls)
 *  - Domain membership
 *  - Related symbols in the same file
 *
 * Backed by pre-computed graphs (sub-second) with on-demand API fallback.
 */

import { promises as fs } from 'fs';
import * as path from 'path';
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import {
  Endpoint,
  HandlerFunction,
  asTextContentResult,
  asErrorResult,
} from '../types';
import {
  IndexedGraph,
  resolveOrFetchGraph,
  normalizePath,
} from '../cache/graph-cache';
import { CodeGraphNode } from '../cache/graph-types';
import { classifyApiError } from '../utils/api-helpers';
import {
  MAX_SYMBOL_CALLERS,
  MAX_SYMBOL_CALLEES,
  MAX_SYMBOL_RELATED,
  MAX_SOURCE_LINES,
} from '../constants';

export const tool: Tool = {
  name: 'symbol_context',
  description:
    `Strictly better than grep for understanding a function, class, or method. Given a symbol name, instantly returns its source code, definition location, all callers, all callees, architectural domain, and related symbols in the same file -- structural context that grep cannot reconstruct. Sub-second, zero cost. Supports partial matching ("filter" finds "QuerySet.filter", "filter_queryset", etc.) and "ClassName.method" syntax. Use this whenever you have a symbol name from a stack trace, issue, or search result and need to understand how it connects to the rest of the codebase.`,
  inputSchema: {
    type: 'object',
    properties: {
      symbol: {
        type: 'string',
        description:
          'Name of the function, class, or method to look up. Supports "ClassName.method" syntax.',
      },
      directory: {
        type: 'string',
        description:
          'Path to the repository directory. Omit if the MCP server was started with a default workdir.',
      },
    },
    required: ['symbol'],
  },
};

export const handler: HandlerFunction = async (client, args, defaultWorkdir) => {
// ... (374 more lines)