@giauphan/codeatlas-mcp 1.2.4 → 1.4.0

package/README.md

@@ -5,7 +5,9 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript)
 ![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen?logo=node.js)
 
-> A standalone [MCP](https://modelcontextprotocol.io/) server that exposes [CodeAtlas](https://github.com/giauphan/CodeAtlas) analysis data to AI assistants — **Gemini, Claude, Cursor, Windsurf**, and more.
+> A standalone [MCP](https://modelcontextprotocol.io/) server that exposes [CodeAtlas](https://github.com/giauphan/CodeAtlas) analysis data to AI assistants — **Gemini, Claude, Cursor, Windsurf, VS Code Copilot**, and more.
+
+**NEW in v1.4.0**: 🧠 **AI System Memory** — AI remembers your system flow between conversations.
 
 ---
 
@@ -23,14 +25,88 @@ This generates `.codeatlas/analysis.json` in your project root.
 
 ### 2. Add MCP config
 
-Copy the JSON block below into **one** of these files depending on your AI assistant:
+Pick your AI assistant and add the config:
+
+<details>
+<summary>🔵 <b>VS Code (Copilot / GitHub Copilot Chat)</b></summary>
+
+Open **Settings** (`Ctrl+,`) → search `mcp` → click **Edit in settings.json**, then add:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "codeatlas": {
+        "command": "npx",
+        "args": ["-y", "@giauphan/codeatlas-mcp"]
+      }
+    }
+  }
+}
+```
+
+Or add via workspace `.vscode/settings.json` for per-project config.
+
+</details>
+
+<details>
+<summary>🟢 <b>Gemini</b></summary>
+
+Add to `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "npx",
+      "args": ["-y", "@giauphan/codeatlas-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>🟣 <b>Claude Desktop</b></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "npx",
+      "args": ["-y", "@giauphan/codeatlas-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>⚫ <b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "npx",
+      "args": ["-y", "@giauphan/codeatlas-mcp"]
+    }
+  }
+}
+```
+
+</details>
 
-| AI Assistant | Config file |
-|---|---|
-| **Gemini** | `.gemini/settings.json` |
-| **Claude Desktop** | `claude_desktop_config.json` |
-| **Cursor** | `.cursor/mcp.json` |
-| **Windsurf** | `.windsurf/mcp.json` |
+<details>
+<summary>🔴 <b>Windsurf</b></summary>
+
+Add to `.windsurf/mcp.json`:
 
 ```json
 {
@@ -43,12 +119,16 @@ Copy the JSON block below into **one** of these files depending on your AI assis
 }
 ```
 
+</details>
+
 > **That's it!** Your AI assistant can now query your codebase structure, dependencies, and insights.
 
 ---
 
 ## 🛠️ Available Tools
 
+### Code Analysis (6 tools)
+
 | Tool | Description |
 |------|-------------|
 | `list_projects` | List all analyzed projects (auto-discovers `~/`) |
@@ -58,6 +138,53 @@ Copy the JSON block below into **one** of these files depending on your AI assis
 | `search_entities` | Search functions, classes by name (fuzzy match) |
 | `get_file_entities` | Get all entities defined in a specific file |
 
+### 🧠 AI System Memory (3 tools — NEW in v1.4.0)
+
+| Tool | Description |
+|------|-------------|
+| `generate_system_flow` | Auto-generate Mermaid architecture diagrams. Scopes: `modules-only`, `full`, `feature` |
+| `sync_system_memory` | Create/update `.agents/memory/` folder — AI's persistent long-term memory |
+| `trace_feature_flow` | Trace a feature's flow through the codebase. Returns files in dependency order |
+
+---
+
+## 🧠 AI System Memory
+
+AI assistants lose context between conversations. CodeAtlas MCP solves this with **persistent memory files**.
+
+### How it works
+
+```
+Conversation 1 → AI writes code → calls sync_system_memory
+                                          │
+                                   .agents/memory/
+                                   ├── system-map.md
+                                   ├── modules.json
+                                   ├── business-rules.json
+                                   ├── conventions.md
+                                   ├── feature-flows.json
+                                   └── change-log.json
+                                          │
+Conversation 2 → AI reads .agents/memory/ → knows full system flow instantly
+```
+
+### Setup AI Memory
+
+1. Copy rule templates to your project:
+
+```bash
+mkdir -p /path/to/your-project/.agents/rules/
+```
+
+2. Create `.agents/rules/auto-memory.md` with the rule that tells AI to:
+   - Read `.agents/memory/` at the start of every conversation
+   - Use `trace_feature_flow` before making changes
+   - Call `sync_system_memory` after completing changes
+
+3. Run `sync_system_memory` once to generate the initial memory snapshot.
+
+> 📖 Full setup guide & rule templates: [CodeAtlas docs](https://github.com/giauphan/CodeAtlas/tree/main/docs)
+
 ---
 
 ## 📦 Alternative: Global Install
@@ -68,17 +195,7 @@ If you prefer installing globally instead of using `npx`:
 npm install -g @giauphan/codeatlas-mcp
 ```
 
-Then update your MCP config to:
-
-```json
-{
-  "mcpServers": {
-    "codeatlas": {
-      "command": "codeatlas-mcp"
-    }
-  }
-}
-```
+Then use `"command": "codeatlas-mcp"` (no `args` needed) in your MCP config.
 
 ---
 
@@ -92,6 +209,17 @@ Then update your MCP config to:
 
 ---
 
+## 🌐 Supported Languages
+
+| Language | Features |
+|----------|----------|
+| TypeScript / JavaScript | Full AST: imports, classes, functions, variables, calls |
+| Python | Classes, functions, variables, imports, calls |
+| PHP | Classes, interfaces, traits, enums, functions, properties, constants |
+| Blade Templates | `@extends`, `@include`, `@component`, `<x-component>` |
+
+---
+
 ## 🧑‍💻 Development
 
 ```bash

package/dist/index.js

@@ -77,7 +77,7 @@ function loadAnalysis(projectDir) {
 // Create MCP server
 const server = new McpServer({
     name: "codeatlas",
-    version: "1.2.2",
+    version: "1.4.0",
 });
 // Tool 0: List all discovered projects
 server.tool("list_projects", "List all projects that have been analyzed by CodeAtlas. Returns project names, paths, and last analysis time.", {}, async () => {
@@ -267,6 +267,471 @@ server.tool("get_file_entities", "Get all entities (classes, functions, variable
     };
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
+// Tool 6: Generate System Flow — Auto-generate Mermaid diagram from code analysis
+server.tool("generate_system_flow", "Auto-generate a Mermaid flowchart diagram showing how modules, classes, and functions connect in the system. Returns a Mermaid diagram string that AI can read to understand the full system flow without reading every file.", {
+    project: z.string().optional().describe("Project name or path"),
+    scope: z.enum(["full", "modules-only", "feature"]).optional().describe("Scope of the diagram: 'full' shows all entities, 'modules-only' shows only module relationships (recommended for large projects), 'feature' requires the 'feature' param"),
+    feature: z.string().optional().describe("Feature keyword to focus the diagram on (e.g. 'auth', 'crawl', 'payment'). Only used when scope='feature'"),
+    maxNodes: z.number().optional().describe("Maximum nodes in diagram (default: 60). Reduce for large projects"),
+}, async ({ project, scope, feature, maxNodes }) => {
+    const loaded = loadAnalysis(project);
+    if (!loaded) {
+        return { content: [{ type: "text", text: "No analysis data found. Run 'CodeAtlas: Analyze Project' first." }] };
+    }
+    const max = maxNodes || 60;
+    const diagramScope = scope || "modules-only";
+    let nodes = loaded.analysis.graph.nodes;
+    let links = loaded.analysis.graph.links;
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    // Filter by scope
+    if (diagramScope === "modules-only") {
+        nodes = nodes.filter((n) => n.type === "module" && n.filePath);
+        const nodeIds = new Set(nodes.map((n) => n.id));
+        links = links.filter((l) => nodeIds.has(l.source) && nodeIds.has(l.target) && l.type === "import");
+    }
+    else if (diagramScope === "feature" && feature) {
+        const q = feature.toLowerCase();
+        // Find nodes matching the feature keyword
+        const matchingNodes = new Set();
+        nodes.forEach((n) => {
+            if (n.label.toLowerCase().includes(q) || (n.filePath && n.filePath.toLowerCase().includes(q))) {
+                matchingNodes.add(n.id);
+            }
+        });
+        // Expand to include connected nodes (1 hop)
+        links.forEach((l) => {
+            if (matchingNodes.has(l.source))
+                matchingNodes.add(l.target);
+            if (matchingNodes.has(l.target))
+                matchingNodes.add(l.source);
+        });
+        nodes = nodes.filter((n) => matchingNodes.has(n.id));
+        const nodeIds = new Set(nodes.map((n) => n.id));
+        links = links.filter((l) => nodeIds.has(l.source) && nodeIds.has(l.target));
+    }
+    // Truncate if too many nodes
+    if (nodes.length > max) {
+        // Prioritize: modules > classes > functions > variables
+        const priorityOrder = ["module", "class", "function", "variable"];
+        nodes.sort((a, b) => {
+            const ia = priorityOrder.indexOf(a.type);
+            const ib = priorityOrder.indexOf(b.type);
+            return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+        });
+        nodes = nodes.slice(0, max);
+    }
+    const truncatedNodeIds = new Set(nodes.map((n) => n.id));
+    links = links.filter((l) => truncatedNodeIds.has(l.source) && truncatedNodeIds.has(l.target));
+    // Remove duplicate links
+    const linkSet = new Set();
+    links = links.filter((l) => {
+        const key = `${l.source}|${l.target}|${l.type}`;
+        if (linkSet.has(key))
+            return false;
+        linkSet.add(key);
+        return true;
+    });
+    // Build Mermaid diagram
+    const sanitize = (s) => s.replace(/[^a-zA-Z0-9_]/g, "_").substring(0, 40);
+    const nodeIdMap = new Map();
+    let counter = 0;
+    const getMermaidId = (nodeId) => {
+        if (!nodeIdMap.has(nodeId)) {
+            nodeIdMap.set(nodeId, `n${counter++}`);
+        }
+        return nodeIdMap.get(nodeId);
+    };
+    const lines = ["graph TD"];
+    // Add node declarations
+    for (const node of nodes) {
+        const mid = getMermaidId(node.id);
+        const label = node.label.replace(/"/g, "'");
+        const typeIcon = node.type === "module" ? "📄" : node.type === "class" ? "🏗️" : node.type === "function" ? "⚡" : "📦";
+        if (node.type === "module") {
+            lines.push(`    ${mid}["${typeIcon} ${label}"]`);
+        }
+        else if (node.type === "class") {
+            lines.push(`    ${mid}[["${typeIcon} ${label}"]]`);
+        }
+        else {
+            lines.push(`    ${mid}("${typeIcon} ${label}")`);
+        }
+    }
+    // Add link declarations
+    const arrowMap = { import: "-->", call: "-.->", contains: "-->" };
+    const labelMap = { import: "imports", call: "calls", contains: "contains" };
+    for (const link of links) {
+        const src = getMermaidId(link.source);
+        const tgt = getMermaidId(link.target);
+        if (src && tgt) {
+            const arrow = arrowMap[link.type] || "-->";
+            if (link.type === "contains") {
+                lines.push(`    ${src} ${arrow} ${tgt}`);
+            }
+            else {
+                lines.push(`    ${src} ${arrow}|${labelMap[link.type] || link.type}| ${tgt}`);
+            }
+        }
+    }
+    const mermaid = lines.join("\n");
+    const result = {
+        project: loaded.projectName,
+        scope: diagramScope,
+        feature: feature || null,
+        nodeCount: nodes.length,
+        linkCount: links.length,
+        truncated: loaded.analysis.graph.nodes.length > max,
+        mermaidDiagram: mermaid,
+        summary: `System flow for ${loaded.projectName}: ${nodes.filter((n) => n.type === "module").length} modules, ${nodes.filter((n) => n.type === "class").length} classes, ${nodes.filter((n) => n.type === "function").length} functions connected by ${links.length} relationships.`,
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// Tool 7: Sync System Memory — Create/update .agents/memory/ persistent files
+server.tool("sync_system_memory", "Create or update the .agents/memory/ folder with auto-generated system documentation. This folder serves as AI's 'long-term memory' — it persists between conversations. After calling this, AI in any future conversation can read these files to understand the full system flow without re-analyzing. Call this after completing any code changes.", {
+    project: z.string().optional().describe("Project name or path"),
+    businessRule: z.string().optional().describe("Optional: A new business rule to add to the memory (e.g. 'VIP users get free shipping')"),
+    changeDescription: z.string().optional().describe("Optional: Description of what was just changed (for the changelog)"),
+}, async ({ project, businessRule, changeDescription }) => {
+    const loaded = loadAnalysis(project);
+    if (!loaded) {
+        return { content: [{ type: "text", text: "No analysis data found. Run 'CodeAtlas: Analyze Project' first." }] };
+    }
+    const memoryDir = path.join(loaded.projectDir, ".agents", "memory");
+    // Create directory structure
+    try {
+        fs.mkdirSync(memoryDir, { recursive: true });
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Failed to create .agents/memory/ directory: ${e}` }] };
+    }
+    const nodes = loaded.analysis.graph.nodes;
+    const links = loaded.analysis.graph.links;
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    const nodeNameMap = new Map(nodes.map((n) => [n.id, n.label]));
+    // === 1. system-map.md — Mermaid diagram of module relationships ===
+    const modules = nodes.filter((n) => n.type === "module" && n.filePath);
+    const moduleLinks = links.filter((l) => {
+        const src = nodeMap.get(l.source);
+        const tgt = nodeMap.get(l.target);
+        return src?.type === "module" && tgt?.type === "module" && src.filePath && tgt.filePath && l.type === "import";
+    });
+    // Deduplicate module links
+    const mlSet = new Set();
+    const dedupModuleLinks = moduleLinks.filter((l) => {
+        const key = `${l.source}|${l.target}`;
+        if (mlSet.has(key))
+            return false;
+        mlSet.add(key);
+        return true;
+    });
+    // Build compact mermaid (max 50 modules for readability)
+    const topModules = modules.slice(0, 50);
+    const topModuleIds = new Set(topModules.map((m) => m.id));
+    const topModuleLinks = dedupModuleLinks.filter((l) => topModuleIds.has(l.source) && topModuleIds.has(l.target));
+    let mermaidLines = ["```mermaid", "graph TD"];
+    let nodeCounter = 0;
+    const mermaidIdMap = new Map();
+    for (const mod of topModules) {
+        const mid = `m${nodeCounter++}`;
+        mermaidIdMap.set(mod.id, mid);
+        mermaidLines.push(`    ${mid}["📄 ${mod.label}"]`);
+    }
+    for (const link of topModuleLinks) {
+        const s = mermaidIdMap.get(link.source);
+        const t = mermaidIdMap.get(link.target);
+        if (s && t)
+            mermaidLines.push(`    ${s} -->|imports| ${t}`);
+    }
+    mermaidLines.push("```");
+    const systemMapContent = [
+        `# System Map — ${loaded.projectName}`,
+        `> Auto-generated by CodeAtlas MCP on ${new Date().toISOString()}`,
+        `> **DO NOT EDIT MANUALLY** — This file is regenerated by \`sync_system_memory\``,
+        "",
+        `## Overview`,
+        `- **Modules**: ${loaded.analysis.stats.files}`,
+        `- **Functions**: ${loaded.analysis.stats.functions}`,
+        `- **Classes**: ${loaded.analysis.stats.classes}`,
+        `- **Dependencies**: ${loaded.analysis.stats.dependencies}`,
+        `- **Circular Deps**: ${loaded.analysis.stats.circularDeps}`,
+        "",
+        `## Module Dependency Graph`,
+        ...mermaidLines,
+        "",
+        `## Key Modules (by connection count)`,
+    ].join("\n");
+    // Count connections per module
+    const moduleConnections = new Map();
+    for (const link of links) {
+        if (link.type === "import") {
+            moduleConnections.set(link.source, (moduleConnections.get(link.source) || 0) + 1);
+            moduleConnections.set(link.target, (moduleConnections.get(link.target) || 0) + 1);
+        }
+    }
+    const keyModules = modules
+        .map((m) => ({ name: m.label, path: m.filePath, connections: moduleConnections.get(m.id) || 0 }))
+        .sort((a, b) => b.connections - a.connections)
+        .slice(0, 20);
+    const keyModulesSection = keyModules
+        .map((m, i) => `${i + 1}. **${m.name}** (${m.connections} connections) — \`${path.relative(loaded.projectDir, m.path || "")}\``)
+        .join("\n");
+    fs.writeFileSync(path.join(memoryDir, "system-map.md"), systemMapContent + "\n" + keyModulesSection + "\n");
+    // === 2. modules.json — Module registry ===
+    const modulesJson = modules.map((m) => {
+        const contained = links
+            .filter((l) => l.source === m.id && l.type === "contains")
+            .map((l) => {
+            const target = nodeMap.get(l.target);
+            return target ? { name: target.label, type: target.type } : null;
+        })
+            .filter(Boolean);
+        const imports = links
+            .filter((l) => l.source === m.id && l.type === "import")
+            .map((l) => nodeNameMap.get(l.target) || l.target);
+        return {
+            name: m.label,
+            path: m.filePath ? path.relative(loaded.projectDir, m.filePath) : null,
+            contains: contained,
+            imports: imports,
+            connectionCount: moduleConnections.get(m.id) || 0,
+        };
+    });
+    fs.writeFileSync(path.join(memoryDir, "modules.json"), JSON.stringify(modulesJson, null, 2));
+    // === 3. feature-flows.json — Auto-detect feature groups ===
+    // Group files by directory as "features"
+    const featureMap = new Map();
+    for (const mod of modules) {
+        if (!mod.filePath)
+            continue;
+        const rel = path.relative(loaded.projectDir, mod.filePath);
+        const dir = path.dirname(rel).split(path.sep)[0] || ".";
+        if (!featureMap.has(dir))
+            featureMap.set(dir, []);
+        featureMap.get(dir).push(rel);
+    }
+    const featureFlows = {};
+    for (const [dir, files] of featureMap) {
+        // Entry points: files with most outgoing imports
+        const entryPoints = files
+            .map((f) => {
+            const moduleId = `module:${f.replace(/\\/g, "/")}`;
+            const outgoing = links.filter((l) => l.source === moduleId && l.type === "import").length;
+            return { file: f, outgoing };
+        })
+            .sort((a, b) => b.outgoing - a.outgoing)
+            .slice(0, 3)
+            .map((e) => e.file);
+        featureFlows[dir] = { files, entryPoints };
+    }
+    fs.writeFileSync(path.join(memoryDir, "feature-flows.json"), JSON.stringify(featureFlows, null, 2));
+    // === 4. business-rules.json — Persist business rules ===
+    const businessRulesPath = path.join(memoryDir, "business-rules.json");
+    let businessRules = [];
+    if (fs.existsSync(businessRulesPath)) {
+        try {
+            businessRules = JSON.parse(fs.readFileSync(businessRulesPath, "utf-8"));
+        }
+        catch { /* start fresh */ }
+    }
+    if (businessRule) {
+        businessRules.push({ rule: businessRule, addedAt: new Date().toISOString() });
+    }
+    fs.writeFileSync(businessRulesPath, JSON.stringify(businessRules, null, 2));
+    // === 5. change-log.json — Track recent changes ===
+    const changeLogPath = path.join(memoryDir, "change-log.json");
+    let changeLog = [];
+    if (fs.existsSync(changeLogPath)) {
+        try {
+            changeLog = JSON.parse(fs.readFileSync(changeLogPath, "utf-8"));
+        }
+        catch { /* start fresh */ }
+    }
+    if (changeDescription) {
+        changeLog.unshift({ description: changeDescription, timestamp: new Date().toISOString() });
+        // Keep only last 50 entries
+        changeLog = changeLog.slice(0, 50);
+    }
+    fs.writeFileSync(changeLogPath, JSON.stringify(changeLog, null, 2));
+    // === 6. conventions.md — Auto-detect conventions ===
+    const langs = new Map();
+    modules.forEach((m) => {
+        if (!m.filePath)
+            return;
+        const ext = path.extname(m.filePath);
+        langs.set(ext, (langs.get(ext) || 0) + 1);
+    });
+    const topLangs = Array.from(langs.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5);
+    const dirs = Array.from(featureMap.keys()).sort();
+    const conventionsContent = [
+        `# Conventions — ${loaded.projectName}`,
+        `> Auto-generated by CodeAtlas MCP on ${new Date().toISOString()}`,
+        `> **DO NOT EDIT MANUALLY**`,
+        "",
+        `## Languages`,
+        ...topLangs.map(([ext, count]) => `- \`${ext}\`: ${count} files`),
+        "",
+        `## Project Structure`,
+        ...dirs.map((d) => `- \`${d}/\` — ${featureMap.get(d)?.length || 0} files`),
+        "",
+        `## Architecture Patterns Detected`,
+        modules.some((m) => m.filePath?.includes("controller") || m.filePath?.includes("Controller"))
+            ? "- ✅ MVC Pattern (Controllers detected)"
+            : "",
+        modules.some((m) => m.filePath?.includes("service") || m.filePath?.includes("Service"))
+            ? "- ✅ Service Layer (Services detected)"
+            : "",
+        modules.some((m) => m.filePath?.includes("model") || m.filePath?.includes("Model"))
+            ? "- ✅ Model Layer (Models detected)"
+            : "",
+        modules.some((m) => m.filePath?.includes("middleware") || m.filePath?.includes("Middleware"))
+            ? "- ✅ Middleware Pattern"
+            : "",
+        modules.some((m) => m.filePath?.includes("test") || m.filePath?.includes("spec"))
+            ? "- ✅ Test Suite Present"
+            : "",
+    ].filter(Boolean).join("\n");
+    fs.writeFileSync(path.join(memoryDir, "conventions.md"), conventionsContent);
+    const result = {
+        success: true,
+        project: loaded.projectName,
+        memoryDir,
+        filesCreated: [
+            "system-map.md",
+            "modules.json",
+            "feature-flows.json",
+            "business-rules.json",
+            "change-log.json",
+            "conventions.md",
+        ],
+        stats: {
+            modules: modules.length,
+            totalEntities: nodes.length,
+            totalLinks: links.length,
+            businessRulesCount: businessRules.length,
+            changeLogEntries: changeLog.length,
+        },
+        message: `System memory synced for ${loaded.projectName}. AI can read .agents/memory/ at the start of any new conversation to restore full context.`,
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// Tool 8: Trace Feature Flow — Trace how a feature flows through the codebase
+server.tool("trace_feature_flow", "Trace the complete flow of a feature through the codebase. Given a keyword (e.g. 'login', 'payment', 'crawl'), finds all related files, classes, and functions, then orders them by dependency chain to show the execution flow. This helps AI understand which files to read when working on a feature.", {
+    project: z.string().optional().describe("Project name or path"),
+    keyword: z.string().describe("Feature keyword to trace (e.g. 'auth', 'crawl', 'payment', 'upload')"),
+    depth: z.number().optional().describe("How many hops to follow from matching nodes (default: 2)"),
+}, async ({ project, keyword, depth }) => {
+    const loaded = loadAnalysis(project);
+    if (!loaded) {
+        return { content: [{ type: "text", text: "No analysis data found. Run 'CodeAtlas: Analyze Project' first." }] };
+    }
+    const maxDepth = depth || 2;
+    const q = keyword.toLowerCase();
+    const nodes = loaded.analysis.graph.nodes;
+    const links = loaded.analysis.graph.links;
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    // Step 1: Find seed nodes matching the keyword
+    const seedNodes = new Set();
+    for (const node of nodes) {
+        if (node.label.toLowerCase().includes(q) ||
+            (node.filePath && node.filePath.toLowerCase().includes(q)) ||
+            node.id.toLowerCase().includes(q)) {
+            seedNodes.add(node.id);
+        }
+    }
+    if (seedNodes.size === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        keyword,
+                        matchCount: 0,
+                        message: `No entities found matching '${keyword}'. Try a broader keyword.`,
+                        suggestions: nodes
+                            .filter((n) => n.type === "module" && n.filePath)
+                            .map((n) => n.label)
+                            .slice(0, 10),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    // Step 2: BFS expansion to find connected nodes
+    const visited = new Set(seedNodes);
+    let frontier = new Set(seedNodes);
+    for (let d = 0; d < maxDepth; d++) {
+        const nextFrontier = new Set();
+        for (const link of links) {
+            if (frontier.has(link.source) && !visited.has(link.target)) {
+                nextFrontier.add(link.target);
+                visited.add(link.target);
+            }
+            if (frontier.has(link.target) && !visited.has(link.source)) {
+                nextFrontier.add(link.source);
+                visited.add(link.source);
+            }
+        }
+        frontier = nextFrontier;
+    }
+    // Step 3: Build the trace result
+    const traceNodes = nodes.filter((n) => visited.has(n.id));
+    const traceLinks = links.filter((l) => visited.has(l.source) && visited.has(l.target));
+    // Group by file for readability
+    const byFile = new Map();
+    for (const node of traceNodes) {
+        const filePath = node.filePath || "external";
+        if (!byFile.has(filePath))
+            byFile.set(filePath, []);
+        byFile.get(filePath).push({
+            name: node.label,
+            type: node.type,
+            isSeed: seedNodes.has(node.id),
+            line: node.line || null,
+        });
+    }
+    // Sort files: seed files first, then by entity count
+    const filesArray = Array.from(byFile.entries())
+        .map(([filePath, entities]) => ({
+        filePath: filePath === "external" ? "external" : path.relative(loaded.projectDir, filePath),
+        absolutePath: filePath,
+        entities,
+        hasSeedMatch: entities.some((e) => e.isSeed),
+        entityCount: entities.length,
+    }))
+        .sort((a, b) => {
+        if (a.hasSeedMatch && !b.hasSeedMatch)
+            return -1;
+        if (!a.hasSeedMatch && b.hasSeedMatch)
+            return 1;
+        return b.entityCount - a.entityCount;
+    });
+    // Build a reading order (dependency-sorted)
+    const fileModuleIds = new Map();
+    for (const node of traceNodes) {
+        if (node.type === "module" && node.filePath) {
+            fileModuleIds.set(node.filePath, node.id);
+        }
+    }
+    const result = {
+        keyword,
+        project: loaded.projectName,
+        seedMatches: seedNodes.size,
+        totalConnected: visited.size,
+        depth: maxDepth,
+        files: filesArray.filter((f) => f.filePath !== "external").slice(0, 30),
+        externalDeps: filesArray.find((f) => f.filePath === "external")?.entities.map((e) => e.name) || [],
+        relationships: traceLinks.slice(0, 50).map((l) => ({
+            from: nodeMap.get(l.source)?.label || l.source,
+            to: nodeMap.get(l.target)?.label || l.target,
+            type: l.type,
+        })),
+        readingOrder: filesArray
+            .filter((f) => f.hasSeedMatch && f.filePath !== "external")
+            .map((f) => f.filePath),
+        message: `Found ${seedNodes.size} direct matches and ${visited.size - seedNodes.size} connected entities for '${keyword}'. Start reading from the files in 'readingOrder'.`,
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
 // Start server
 async function main() {
     const transport = new StdioServerTransport();

package/index.ts

@@ -107,7 +107,7 @@ function loadAnalysis(projectDir?: string): { analysis: AnalysisResult; projectN
 // Create MCP server
 const server = new McpServer({
   name: "codeatlas",
-  version: "1.2.2",
+  version: "1.4.0",
 });
 
 // Tool 0: List all discovered projects
@@ -357,6 +357,524 @@ server.tool(
   }
 );
 
+// Tool 6: Generate System Flow — Auto-generate Mermaid diagram from code analysis
+server.tool(
+  "generate_system_flow",
+  "Auto-generate a Mermaid flowchart diagram showing how modules, classes, and functions connect in the system. Returns a Mermaid diagram string that AI can read to understand the full system flow without reading every file.",
+  {
+    project: z.string().optional().describe("Project name or path"),
+    scope: z.enum(["full", "modules-only", "feature"]).optional().describe("Scope of the diagram: 'full' shows all entities, 'modules-only' shows only module relationships (recommended for large projects), 'feature' requires the 'feature' param"),
+    feature: z.string().optional().describe("Feature keyword to focus the diagram on (e.g. 'auth', 'crawl', 'payment'). Only used when scope='feature'"),
+    maxNodes: z.number().optional().describe("Maximum nodes in diagram (default: 60). Reduce for large projects"),
+  },
+  async ({ project, scope, feature, maxNodes }) => {
+    const loaded = loadAnalysis(project);
+    if (!loaded) {
+      return { content: [{ type: "text" as const, text: "No analysis data found. Run 'CodeAtlas: Analyze Project' first." }] };
+    }
+
+    const max = maxNodes || 60;
+    const diagramScope = scope || "modules-only";
+    let nodes = loaded.analysis.graph.nodes;
+    let links = loaded.analysis.graph.links;
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+
+    // Filter by scope
+    if (diagramScope === "modules-only") {
+      nodes = nodes.filter((n) => n.type === "module" && n.filePath);
+      const nodeIds = new Set(nodes.map((n) => n.id));
+      links = links.filter((l) => nodeIds.has(l.source) && nodeIds.has(l.target) && l.type === "import");
+    } else if (diagramScope === "feature" && feature) {
+      const q = feature.toLowerCase();
+      // Find nodes matching the feature keyword
+      const matchingNodes = new Set<string>();
+      nodes.forEach((n) => {
+        if (n.label.toLowerCase().includes(q) || (n.filePath && n.filePath.toLowerCase().includes(q))) {
+          matchingNodes.add(n.id);
+        }
+      });
+      // Expand to include connected nodes (1 hop)
+      links.forEach((l) => {
+        if (matchingNodes.has(l.source)) matchingNodes.add(l.target);
+        if (matchingNodes.has(l.target)) matchingNodes.add(l.source);
+      });
+      nodes = nodes.filter((n) => matchingNodes.has(n.id));
+      const nodeIds = new Set(nodes.map((n) => n.id));
+      links = links.filter((l) => nodeIds.has(l.source) && nodeIds.has(l.target));
+    }
+
+    // Truncate if too many nodes
+    if (nodes.length > max) {
+      // Prioritize: modules > classes > functions > variables
+      const priorityOrder = ["module", "class", "function", "variable"];
+      nodes.sort((a, b) => {
+        const ia = priorityOrder.indexOf(a.type);
+        const ib = priorityOrder.indexOf(b.type);
+        return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+      });
+      nodes = nodes.slice(0, max);
+    }
+
+    const truncatedNodeIds = new Set(nodes.map((n) => n.id));
+    links = links.filter((l) => truncatedNodeIds.has(l.source) && truncatedNodeIds.has(l.target));
+
+    // Remove duplicate links
+    const linkSet = new Set<string>();
+    links = links.filter((l) => {
+      const key = `${l.source}|${l.target}|${l.type}`;
+      if (linkSet.has(key)) return false;
+      linkSet.add(key);
+      return true;
+    });
+
+    // Build Mermaid diagram
+    const sanitize = (s: string) => s.replace(/[^a-zA-Z0-9_]/g, "_").substring(0, 40);
+    const nodeIdMap = new Map<string, string>();
+    let counter = 0;
+
+    const getMermaidId = (nodeId: string) => {
+      if (!nodeIdMap.has(nodeId)) {
+        nodeIdMap.set(nodeId, `n${counter++}`);
+      }
+      return nodeIdMap.get(nodeId)!;
+    };
+
+    const lines: string[] = ["graph TD"];
+
+    // Add node declarations
+    for (const node of nodes) {
+      const mid = getMermaidId(node.id);
+      const label = node.label.replace(/"/g, "'");
+      const typeIcon = node.type === "module" ? "📄" : node.type === "class" ? "🏗️" : node.type === "function" ? "⚡" : "📦";
+      if (node.type === "module") {
+        lines.push(`    ${mid}["${typeIcon} ${label}"]`);
+      } else if (node.type === "class") {
+        lines.push(`    ${mid}[["${typeIcon} ${label}"]]`);
+      } else {
+        lines.push(`    ${mid}("${typeIcon} ${label}")`);
+      }
+    }
+
+    // Add link declarations
+    const arrowMap: Record<string, string> = { import: "-->", call: "-.->", contains: "-->" };
+    const labelMap: Record<string, string> = { import: "imports", call: "calls", contains: "contains" };
+    for (const link of links) {
+      const src = getMermaidId(link.source);
+      const tgt = getMermaidId(link.target);
+      if (src && tgt) {
+        const arrow = arrowMap[link.type] || "-->";
+        if (link.type === "contains") {
+          lines.push(`    ${src} ${arrow} ${tgt}`);
+        } else {
+          lines.push(`    ${src} ${arrow}|${labelMap[link.type] || link.type}| ${tgt}`);
+        }
+      }
+    }
+
+    const mermaid = lines.join("\n");
+
+    const result = {
+      project: loaded.projectName,
+      scope: diagramScope,
+      feature: feature || null,
+      nodeCount: nodes.length,
+      linkCount: links.length,
+      truncated: loaded.analysis.graph.nodes.length > max,
+      mermaidDiagram: mermaid,
+      summary: `System flow for ${loaded.projectName}: ${nodes.filter((n) => n.type === "module").length} modules, ${nodes.filter((n) => n.type === "class").length} classes, ${nodes.filter((n) => n.type === "function").length} functions connected by ${links.length} relationships.`,
+    };
+
+    return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Tool 7: Sync System Memory — Create/update .agents/memory/ persistent files
+server.tool(
+  "sync_system_memory",
+  "Create or update the .agents/memory/ folder with auto-generated system documentation. This folder serves as AI's 'long-term memory' — it persists between conversations. After calling this, AI in any future conversation can read these files to understand the full system flow without re-analyzing. Call this after completing any code changes.",
+  {
+    project: z.string().optional().describe("Project name or path"),
+    businessRule: z.string().optional().describe("Optional: A new business rule to add to the memory (e.g. 'VIP users get free shipping')"),
+    changeDescription: z.string().optional().describe("Optional: Description of what was just changed (for the changelog)"),
+  },
+  async ({ project, businessRule, changeDescription }) => {
+    const loaded = loadAnalysis(project);
+    if (!loaded) {
+      return { content: [{ type: "text" as const, text: "No analysis data found. Run 'CodeAtlas: Analyze Project' first." }] };
+    }
+
+    const memoryDir = path.join(loaded.projectDir, ".agents", "memory");
+    
+    // Create directory structure
+    try {
+      fs.mkdirSync(memoryDir, { recursive: true });
+    } catch (e) {
+      return { content: [{ type: "text" as const, text: `Failed to create .agents/memory/ directory: ${e}` }] };
+    }
+
+    const nodes = loaded.analysis.graph.nodes;
+    const links = loaded.analysis.graph.links;
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    const nodeNameMap = new Map(nodes.map((n) => [n.id, n.label]));
+
+    // === 1. system-map.md — Mermaid diagram of module relationships ===
+    const modules = nodes.filter((n) => n.type === "module" && n.filePath);
+    const moduleLinks = links.filter((l) => {
+      const src = nodeMap.get(l.source);
+      const tgt = nodeMap.get(l.target);
+      return src?.type === "module" && tgt?.type === "module" && src.filePath && tgt.filePath && l.type === "import";
+    });
+
+    // Deduplicate module links
+    const mlSet = new Set<string>();
+    const dedupModuleLinks = moduleLinks.filter((l) => {
+      const key = `${l.source}|${l.target}`;
+      if (mlSet.has(key)) return false;
+      mlSet.add(key);
+      return true;
+    });
+
+    // Build compact mermaid (max 50 modules for readability)
+    const topModules = modules.slice(0, 50);
+    const topModuleIds = new Set(topModules.map((m) => m.id));
+    const topModuleLinks = dedupModuleLinks.filter((l) => topModuleIds.has(l.source) && topModuleIds.has(l.target));
+
+    let mermaidLines = ["```mermaid", "graph TD"];
+    let nodeCounter = 0;
+    const mermaidIdMap = new Map<string, string>();
+    for (const mod of topModules) {
+      const mid = `m${nodeCounter++}`;
+      mermaidIdMap.set(mod.id, mid);
+      mermaidLines.push(`    ${mid}["📄 ${mod.label}"]`);
+    }
+    for (const link of topModuleLinks) {
+      const s = mermaidIdMap.get(link.source);
+      const t = mermaidIdMap.get(link.target);
+      if (s && t) mermaidLines.push(`    ${s} -->|imports| ${t}`);
+    }
+    mermaidLines.push("```");
+
+    const systemMapContent = [
+      `# System Map — ${loaded.projectName}`,
+      `> Auto-generated by CodeAtlas MCP on ${new Date().toISOString()}`,
+      `> **DO NOT EDIT MANUALLY** — This file is regenerated by \`sync_system_memory\``,
+      "",
+      `## Overview`,
+      `- **Modules**: ${loaded.analysis.stats.files}`,
+      `- **Functions**: ${loaded.analysis.stats.functions}`,
+      `- **Classes**: ${loaded.analysis.stats.classes}`,
+      `- **Dependencies**: ${loaded.analysis.stats.dependencies}`,
+      `- **Circular Deps**: ${loaded.analysis.stats.circularDeps}`,
+      "",
+      `## Module Dependency Graph`,
+      ...mermaidLines,
+      "",
+      `## Key Modules (by connection count)`,
+    ].join("\n");
+
+    // Count connections per module
+    const moduleConnections = new Map<string, number>();
+    for (const link of links) {
+      if (link.type === "import") {
+        moduleConnections.set(link.source, (moduleConnections.get(link.source) || 0) + 1);
+        moduleConnections.set(link.target, (moduleConnections.get(link.target) || 0) + 1);
+      }
+    }
+    const keyModules = modules
+      .map((m) => ({ name: m.label, path: m.filePath, connections: moduleConnections.get(m.id) || 0 }))
+      .sort((a, b) => b.connections - a.connections)
+      .slice(0, 20);
+
+    const keyModulesSection = keyModules
+      .map((m, i) => `${i + 1}. **${m.name}** (${m.connections} connections) — \`${path.relative(loaded.projectDir, m.path || "")}\``)
+      .join("\n");
+
+    fs.writeFileSync(path.join(memoryDir, "system-map.md"), systemMapContent + "\n" + keyModulesSection + "\n");
+
+    // === 2. modules.json — Module registry ===
+    const modulesJson = modules.map((m) => {
+      const contained = links
+        .filter((l) => l.source === m.id && l.type === "contains")
+        .map((l) => {
+          const target = nodeMap.get(l.target);
+          return target ? { name: target.label, type: target.type } : null;
+        })
+        .filter(Boolean);
+
+      const imports = links
+        .filter((l) => l.source === m.id && l.type === "import")
+        .map((l) => nodeNameMap.get(l.target) || l.target);
+
+      return {
+        name: m.label,
+        path: m.filePath ? path.relative(loaded.projectDir, m.filePath) : null,
+        contains: contained,
+        imports: imports,
+        connectionCount: moduleConnections.get(m.id) || 0,
+      };
+    });
+
+    fs.writeFileSync(path.join(memoryDir, "modules.json"), JSON.stringify(modulesJson, null, 2));
+
+    // === 3. feature-flows.json — Auto-detect feature groups ===
+    // Group files by directory as "features"
+    const featureMap = new Map<string, string[]>();
+    for (const mod of modules) {
+      if (!mod.filePath) continue;
+      const rel = path.relative(loaded.projectDir, mod.filePath);
+      const dir = path.dirname(rel).split(path.sep)[0] || ".";
+      if (!featureMap.has(dir)) featureMap.set(dir, []);
+      featureMap.get(dir)!.push(rel);
+    }
+
+    const featureFlows: Record<string, { files: string[]; entryPoints: string[] }> = {};
+    for (const [dir, files] of featureMap) {
+      // Entry points: files with most outgoing imports
+      const entryPoints = files
+        .map((f) => {
+          const moduleId = `module:${f.replace(/\\/g, "/")}`;
+          const outgoing = links.filter((l) => l.source === moduleId && l.type === "import").length;
+          return { file: f, outgoing };
+        })
+        .sort((a, b) => b.outgoing - a.outgoing)
+        .slice(0, 3)
+        .map((e) => e.file);
+
+      featureFlows[dir] = { files, entryPoints };
+    }
+
+    fs.writeFileSync(path.join(memoryDir, "feature-flows.json"), JSON.stringify(featureFlows, null, 2));
+
+    // === 4. business-rules.json — Persist business rules ===
+    const businessRulesPath = path.join(memoryDir, "business-rules.json");
+    let businessRules: Array<{ rule: string; addedAt: string }> = [];
+    if (fs.existsSync(businessRulesPath)) {
+      try {
+        businessRules = JSON.parse(fs.readFileSync(businessRulesPath, "utf-8"));
+      } catch { /* start fresh */ }
+    }
+    if (businessRule) {
+      businessRules.push({ rule: businessRule, addedAt: new Date().toISOString() });
+    }
+    fs.writeFileSync(businessRulesPath, JSON.stringify(businessRules, null, 2));
+
+    // === 5. change-log.json — Track recent changes ===
+    const changeLogPath = path.join(memoryDir, "change-log.json");
+    let changeLog: Array<{ description: string; timestamp: string }> = [];
+    if (fs.existsSync(changeLogPath)) {
+      try {
+        changeLog = JSON.parse(fs.readFileSync(changeLogPath, "utf-8"));
+      } catch { /* start fresh */ }
+    }
+    if (changeDescription) {
+      changeLog.unshift({ description: changeDescription, timestamp: new Date().toISOString() });
+      // Keep only last 50 entries
+      changeLog = changeLog.slice(0, 50);
+    }
+    fs.writeFileSync(changeLogPath, JSON.stringify(changeLog, null, 2));
+
+    // === 6. conventions.md — Auto-detect conventions ===
+    const langs = new Map<string, number>();
+    modules.forEach((m) => {
+      if (!m.filePath) return;
+      const ext = path.extname(m.filePath);
+      langs.set(ext, (langs.get(ext) || 0) + 1);
+    });
+
+    const topLangs = Array.from(langs.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5);
+    const dirs = Array.from(featureMap.keys()).sort();
+
+    const conventionsContent = [
+      `# Conventions — ${loaded.projectName}`,
+      `> Auto-generated by CodeAtlas MCP on ${new Date().toISOString()}`,
+      `> **DO NOT EDIT MANUALLY**`,
+      "",
+      `## Languages`,
+      ...topLangs.map(([ext, count]) => `- \`${ext}\`: ${count} files`),
+      "",
+      `## Project Structure`,
+      ...dirs.map((d) => `- \`${d}/\` — ${featureMap.get(d)?.length || 0} files`),
+      "",
+      `## Architecture Patterns Detected`,
+      modules.some((m) => m.filePath?.includes("controller") || m.filePath?.includes("Controller"))
+        ? "- ✅ MVC Pattern (Controllers detected)"
+        : "",
+      modules.some((m) => m.filePath?.includes("service") || m.filePath?.includes("Service"))
+        ? "- ✅ Service Layer (Services detected)"
+        : "",
+      modules.some((m) => m.filePath?.includes("model") || m.filePath?.includes("Model"))
+        ? "- ✅ Model Layer (Models detected)"
+        : "",
+      modules.some((m) => m.filePath?.includes("middleware") || m.filePath?.includes("Middleware"))
+        ? "- ✅ Middleware Pattern"
+        : "",
+      modules.some((m) => m.filePath?.includes("test") || m.filePath?.includes("spec"))
+        ? "- ✅ Test Suite Present"
+        : "",
+    ].filter(Boolean).join("\n");
+
+    fs.writeFileSync(path.join(memoryDir, "conventions.md"), conventionsContent);
+
+    const result = {
+      success: true,
+      project: loaded.projectName,
+      memoryDir,
+      filesCreated: [
+        "system-map.md",
+        "modules.json",
+        "feature-flows.json",
+        "business-rules.json",
+        "change-log.json",
+        "conventions.md",
+      ],
+      stats: {
+        modules: modules.length,
+        totalEntities: nodes.length,
+        totalLinks: links.length,
+        businessRulesCount: businessRules.length,
+        changeLogEntries: changeLog.length,
+      },
+      message: `System memory synced for ${loaded.projectName}. AI can read .agents/memory/ at the start of any new conversation to restore full context.`,
+    };
+
+    return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Tool 8: Trace Feature Flow — Trace how a feature flows through the codebase
+server.tool(
+  "trace_feature_flow",
+  "Trace the complete flow of a feature through the codebase. Given a keyword (e.g. 'login', 'payment', 'crawl'), finds all related files, classes, and functions, then orders them by dependency chain to show the execution flow. This helps AI understand which files to read when working on a feature.",
+  {
+    project: z.string().optional().describe("Project name or path"),
+    keyword: z.string().describe("Feature keyword to trace (e.g. 'auth', 'crawl', 'payment', 'upload')"),
+    depth: z.number().optional().describe("How many hops to follow from matching nodes (default: 2)"),
+  },
+  async ({ project, keyword, depth }) => {
+    const loaded = loadAnalysis(project);
+    if (!loaded) {
+      return { content: [{ type: "text" as const, text: "No analysis data found. Run 'CodeAtlas: Analyze Project' first." }] };
+    }
+
+    const maxDepth = depth || 2;
+    const q = keyword.toLowerCase();
+    const nodes = loaded.analysis.graph.nodes;
+    const links = loaded.analysis.graph.links;
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+
+    // Step 1: Find seed nodes matching the keyword
+    const seedNodes = new Set<string>();
+    for (const node of nodes) {
+      if (
+        node.label.toLowerCase().includes(q) ||
+        (node.filePath && node.filePath.toLowerCase().includes(q)) ||
+        node.id.toLowerCase().includes(q)
+      ) {
+        seedNodes.add(node.id);
+      }
+    }
+
+    if (seedNodes.size === 0) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              keyword,
+              matchCount: 0,
+              message: `No entities found matching '${keyword}'. Try a broader keyword.`,
+              suggestions: nodes
+                .filter((n) => n.type === "module" && n.filePath)
+                .map((n) => n.label)
+                .slice(0, 10),
+            }, null, 2),
+          },
+        ],
+      };
+    }
+
+    // Step 2: BFS expansion to find connected nodes
+    const visited = new Set<string>(seedNodes);
+    let frontier = new Set<string>(seedNodes);
+
+    for (let d = 0; d < maxDepth; d++) {
+      const nextFrontier = new Set<string>();
+      for (const link of links) {
+        if (frontier.has(link.source) && !visited.has(link.target)) {
+          nextFrontier.add(link.target);
+          visited.add(link.target);
+        }
+        if (frontier.has(link.target) && !visited.has(link.source)) {
+          nextFrontier.add(link.source);
+          visited.add(link.source);
+        }
+      }
+      frontier = nextFrontier;
+    }
+
+    // Step 3: Build the trace result
+    const traceNodes = nodes.filter((n) => visited.has(n.id));
+    const traceLinks = links.filter((l) => visited.has(l.source) && visited.has(l.target));
+
+    // Group by file for readability
+    const byFile = new Map<string, Array<{ name: string; type: string; isSeed: boolean; line: number | null }>>();
+    for (const node of traceNodes) {
+      const filePath = node.filePath || "external";
+      if (!byFile.has(filePath)) byFile.set(filePath, []);
+      byFile.get(filePath)!.push({
+        name: node.label,
+        type: node.type,
+        isSeed: seedNodes.has(node.id),
+        line: node.line || null,
+      });
+    }
+
+    // Sort files: seed files first, then by entity count
+    const filesArray = Array.from(byFile.entries())
+      .map(([filePath, entities]) => ({
+        filePath: filePath === "external" ? "external" : path.relative(loaded.projectDir, filePath),
+        absolutePath: filePath,
+        entities,
+        hasSeedMatch: entities.some((e) => e.isSeed),
+        entityCount: entities.length,
+      }))
+      .sort((a, b) => {
+        if (a.hasSeedMatch && !b.hasSeedMatch) return -1;
+        if (!a.hasSeedMatch && b.hasSeedMatch) return 1;
+        return b.entityCount - a.entityCount;
+      });
+
+    // Build a reading order (dependency-sorted)
+    const fileModuleIds = new Map<string, string>();
+    for (const node of traceNodes) {
+      if (node.type === "module" && node.filePath) {
+        fileModuleIds.set(node.filePath, node.id);
+      }
+    }
+
+    const result = {
+      keyword,
+      project: loaded.projectName,
+      seedMatches: seedNodes.size,
+      totalConnected: visited.size,
+      depth: maxDepth,
+      files: filesArray.filter((f) => f.filePath !== "external").slice(0, 30),
+      externalDeps: filesArray.find((f) => f.filePath === "external")?.entities.map((e) => e.name) || [],
+      relationships: traceLinks.slice(0, 50).map((l) => ({
+        from: nodeMap.get(l.source)?.label || l.source,
+        to: nodeMap.get(l.target)?.label || l.target,
+        type: l.type,
+      })),
+      readingOrder: filesArray
+        .filter((f) => f.hasSeedMatch && f.filePath !== "external")
+        .map((f) => f.filePath),
+      message: `Found ${seedNodes.size} direct matches and ${visited.size - seedNodes.size} connected entities for '${keyword}'. Start reading from the files in 'readingOrder'.`,
+    };
+
+    return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
 // Start server
 async function main() {
   const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giauphan/codeatlas-mcp",
-  "version": "1.2.4",
+  "version": "1.4.0",
   "description": "MCP server for CodeAtlas — exposes code analysis data to AI assistants via Model Context Protocol",
   "type": "module",
   "main": "dist/index.js",