overview.ts — mcp Source File

Source Code

/**
 * `overview` tool -- instant architectural map of a codebase.
 *
 * Returns a concise (<3KB) markdown summary with:
 *  - Top domains and their key files
 *  - Hub functions (highest in-degree in call graph)
 *  - File/function/class counts
 *
 * Backed by pre-computed graphs (sub-second) with on-demand API fallback.
 */

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import {
  Endpoint,
  HandlerFunction,
  asTextContentResult,
  asErrorResult,
} from '../types';
import {
  IndexedGraph,
  resolveOrFetchGraph,
  normalizePath,
} from '../cache/graph-cache';
import { classifyApiError } from '../utils/api-helpers';
import {
  MAX_OVERVIEW_DOMAINS,
  MAX_OVERVIEW_HUB_FUNCTIONS,
} from '../constants';

export const tool: Tool = {
  name: 'overview',
  description:
    `Returns a pre-computed architectural map of the entire codebase: which domains own which files, the most-called hub functions (call graph centrality), file/function/class counts. Sub-second, zero cost. Useful when you need to understand the overall structure before diving in. Skip this if you already know what file or symbol to investigate — use symbol_context or file reading instead.`,
  inputSchema: {
    type: 'object',
    properties: {
      directory: {
        type: 'string',
        description:
          'Path to the repository directory. Omit if the MCP server was started with a default workdir.',
      },
    },
    required: [],
  },
};

export const handler: HandlerFunction = async (client, args, defaultWorkdir) => {
  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.',
    });
  }

// ... (118 more lines)