get_project_structure

Instructions

Implementation Reference

• index.ts:157-199 (registration)

  Tool registration for 'get_project_structure' using server.tool() with name, description, Zod schema for input, and handler function.

  server.tool(
    "get_project_structure",
    "Get all modules, classes, functions, and variables in the analyzed project. Returns entity type, name, file path, and line number.",
    {
      project: z.string().optional().describe("Project name or path (auto-detects if omitted)"),
      type: z.enum(["all", "module", "class", "function", "variable"]).optional().describe("Filter by entity type"),
      limit: z.number().optional().describe("Max results to return (default: 100)"),
    },
    async ({ project, type, limit }) => {
      const loaded = loadAnalysis(project);
      if (!loaded) {
        return { content: [{ type: "text" as const, text: "No analysis data found. Run 'CodeAtlas: Analyze Project' in VS Code first." }] };
      }
  
      let nodes = loaded.analysis.graph.nodes;
      if (type && type !== "all") {
        nodes = nodes.filter((n) => n.type === type);
      }
  
      const maxResults = limit || 100;
      const truncated = nodes.length > maxResults;
      nodes = nodes.slice(0, maxResults);
  
      const stats = getStats(loaded.analysis);
  
      const result = {
        project: loaded.projectName,
        projectDir: loaded.projectDir,
        total: loaded.analysis.graph.nodes.length,
        showing: nodes.length,
        truncated,
        stats,
        entities: nodes.map((n) => ({
          name: n.label,
          type: n.type,
          filePath: n.filePath || null,
          line: n.line || null,
        })),
      };
  
      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
    }
  );

• index.ts:165-198 (handler)

  Handler function that loads analysis data, optionally filters nodes by type, limits results, and returns entities with name, type, filePath, and line number.

  async ({ project, type, limit }) => {
    const loaded = loadAnalysis(project);
    if (!loaded) {
      return { content: [{ type: "text" as const, text: "No analysis data found. Run 'CodeAtlas: Analyze Project' in VS Code first." }] };
    }
  
    let nodes = loaded.analysis.graph.nodes;
    if (type && type !== "all") {
      nodes = nodes.filter((n) => n.type === type);
    }
  
    const maxResults = limit || 100;
    const truncated = nodes.length > maxResults;
    nodes = nodes.slice(0, maxResults);
  
    const stats = getStats(loaded.analysis);
  
    const result = {
      project: loaded.projectName,
      projectDir: loaded.projectDir,
      total: loaded.analysis.graph.nodes.length,
      showing: nodes.length,
      truncated,
      stats,
      entities: nodes.map((n) => ({
        name: n.label,
        type: n.type,
        filePath: n.filePath || null,
        line: n.line || null,
      })),
    };
  
    return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
  }

• index.ts:160-164 (schema)

  Input schema using Zod: optional project (string), optional type (enum: all/module/class/function/variable), optional limit (number, default 100).

  {
    project: z.string().optional().describe("Project name or path (auto-detects if omitted)"),
    type: z.enum(["all", "module", "class", "function", "variable"]).optional().describe("Filter by entity type"),
    limit: z.number().optional().describe("Max results to return (default: 100)"),
  },

• index.ts:36-47 (helper)

  Helper function getStats() used by the handler to unify stats from different analysis format versions (entityCounts vs stats).

  function getStats(analysis: AnalysisResult) {
    const ec = analysis.entityCounts;
    const st = analysis.stats;
    return {
      files: st?.files ?? ec?.modules ?? analysis.totalFilesAnalyzed ?? 0,
      modules: ec?.modules ?? st?.files ?? analysis.totalFilesAnalyzed ?? 0,
      functions: ec?.functions ?? st?.functions ?? 0,
      classes: ec?.classes ?? st?.classes ?? 0,
      dependencies: ec?.dependencies ?? st?.dependencies ?? 0,
      circularDeps: ec?.circularDeps ?? st?.circularDeps ?? 0,
    };
  }

• index.ts:104-124 (helper)

  Helper function loadAnalysis() that discovers projects, finds the matching project, and reads/parses the analysis.json file.

  function loadAnalysis(projectDir?: string): { analysis: AnalysisResult; projectName: string; projectDir: string } | null {
    const projects = discoverProjects();
    if (projects.length === 0) return null;
  
    let target = projects[0]; // default: most recently modified
  
    if (projectDir) {
      const match = projects.find(
        (p) => p.dir === projectDir || p.name.toLowerCase() === projectDir.toLowerCase()
      );
      if (match) target = match;
    }
  
    try {
      const data = fs.readFileSync(target.analysisPath, "utf-8");
      return { analysis: JSON.parse(data), projectName: target.name, projectDir: target.dir };
    } catch (e) {
      console.error(`[CodeAtlas] ERROR: Failed to parse analysis file at ${target.analysisPath}: ${e}`);
      return null;
    }
  }