codebase_graph_query

Instructions

Implementation Reference

• src/index.ts:190-203 (registration)

  MCP server registration for the 'codebase_graph_query' tool. Defines the tool name, description, and Zod schema for inputs (projectPath optional, filePath required). Delegates execution to handleGraphTool('codebase_graph_query', args).

  server.tool(
    "codebase_graph_query",
    "Query the code dependency graph for a specific file. Returns what the file imports and what files depend on it.",
    {
      projectPath: z
        .string()
        .describe("Absolute path to the project directory.")
        .optional(),
      filePath: z.string().describe("Relative path of the file to query (e.g. 'src/index.ts')."),
    },
    async (args) => ({
      content: [{ type: "text", text: await handleGraphTool("codebase_graph_query", args) }],
    }),
  );

• src/tools/graph-tools.ts:78-105 (handler)

  Handler for codebase_graph_query: extracts filePath from args, gets or builds the graph via getOrBuildGraph, calls getFileDependencies, and formats the output showing imports (upstream) and importedBy (downstream) with arrow indicators.

  case "codebase_graph_query": {
    const filePath = args.filePath as string;
    const graph = await getOrBuildGraph(projectPath);
    const deps = getFileDependencies(graph, filePath);
  
    const lines = [`Dependencies for: ${filePath}\n`];
  
    if (deps.imports.length === 0 && deps.importedBy.length === 0) {
      lines.push("No dependency information found for this file.");
      lines.push("Make sure codebase_graph_build has been run and the file path is relative.");
    } else {
      if (deps.imports.length > 0) {
        lines.push(`Imports (${deps.imports.length}):`);
        for (const imp of deps.imports) {
          lines.push(`  → ${imp}`);
        }
      }
  
      if (deps.importedBy.length > 0) {
        lines.push(`\nImported by (${deps.importedBy.length}):`);
        for (const dep of deps.importedBy) {
          lines.push(`  ← ${dep}`);
        }
      }
    }
  
    return lines.join("\n");
  }

• src/services/graph-analysis.ts:10-22 (helper)

  getFileDependencies helper function: finds the graph node by relativePath and returns its dependencies (imports) and dependents (importedBy) arrays.

  export function getFileDependencies(graph: CodeGraph, relativePath: string): {
    imports: string[];
    importedBy: string[];
  } {
    const node = graph.nodes.find((n) => n.relativePath === relativePath);
    if (!node) {
      return { imports: [], importedBy: [] };
    }
    return {
      imports: node.dependencies,
      importedBy: node.dependents,
    };
  }

• src/services/code-graph.ts:107-131 (helper)

  getOrBuildGraph helper: returns cached graph if available, otherwise loads from Qdrant persistence, or builds a new code graph as a fallback.

  export async function getOrBuildGraph(
    projectPath: string,
    extraExtensions?: Set<string>,
  ): Promise<CodeGraph> {
    const resolved = path.resolve(projectPath);
    const cached = graphCache.get(resolved);
    if (cached) {
      return cached;
    }
  
    // Try loading persisted graph from Qdrant
    const projectId = projectIdFromPath(resolved);
    const graphCollName = graphCollectionName(projectId);
    const persisted = await loadGraphData(graphCollName);
    if (persisted) {
      graphCache.set(resolved, persisted);
      return persisted;
    }
  
    const graph = await buildCodeGraph(resolved, extraExtensions);
    // Strip symbol fields when serving as a plain CodeGraph
    const plain: CodeGraph = { nodes: graph.nodes, edges: graph.edges };
    graphCache.set(resolved, plain);
    return plain;
  }