@giauphan/codeatlas-mcp 1.2.3 → 1.4.0

package/README.md

@@ -1,48 +1,76 @@
 # 🗺️ CodeAtlas MCP Server
 
-**MCP server for [CodeAtlas](https://github.com/giauphan/CodeAtlas) — Expose code analysis data to AI assistants**
-
 [![npm version](https://img.shields.io/npm/v/@giauphan/codeatlas-mcp.svg)](https://www.npmjs.com/package/@giauphan/codeatlas-mcp)
 ![License](https://img.shields.io/badge/License-MIT-green.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript)
+![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen?logo=node.js)
 
-## What is this?
+> 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.
 
-A standalone [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that reads CodeAtlas analysis data and exposes it to AI assistants like **Gemini, Claude, Cursor**, etc.
+**NEW in v1.4.0**: 🧠 **AI System Memory** — AI remembers your system flow between conversations.
 
-## Tools
+---
 
-| Tool | Description |
-|------|-------------|
-| `list_projects` | List all projects analyzed by CodeAtlas |
-| `get_project_structure` | Get modules, classes, functions, variables |
-| `get_dependencies` | Get import/call/containment relationships |
-| `get_insights` | Get AI-generated code insights |
-| `search_entities` | Search for functions, classes by name |
-| `get_file_entities` | Get all entities in a specific file |
+## ⚡ Quick Start
+
+### 1. Analyze your project
 
-## Prerequisites
+Install the [CodeAtlas VS Code extension](https://github.com/giauphan/CodeAtlas), then run:
 
-1. Install the [CodeAtlas VS Code extension](https://github.com/giauphan/CodeAtlas)
-2. Run **CodeAtlas: Analyze Project** in VS Code to generate `.codeatlas/analysis.json`
+```
+Ctrl+Shift+P → CodeAtlas: Analyze Project
+```
 
-## Installation
+This generates `.codeatlas/analysis.json` in your project root.
 
-```bash
-npm install -g @giauphan/codeatlas-mcp
+### 2. Add MCP config
+
+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 use directly with `npx` (no install needed):
+Or add via workspace `.vscode/settings.json` for per-project config.
 
-```bash
-npx @giauphan/codeatlas-mcp
+</details>
+
+<details>
+<summary>🟢 <b>Gemini</b></summary>
+
+Add to `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "codeatlas": {
+      "command": "npx",
+      "args": ["-y", "@giauphan/codeatlas-mcp"]
+    }
+  }
+}
 ```
 
-## Configuration
+</details>
 
-Add to your AI assistant's MCP config:
+<details>
+<summary>🟣 <b>Claude Desktop</b></summary>
 
-### Gemini (`.gemini/settings.json`)
+Add to `claude_desktop_config.json`:
 
 ```json
 {
@@ -55,7 +83,12 @@ Add to your AI assistant's MCP config:
 }
 ```
 
-### Claude (`claude_desktop_config.json`)
+</details>
+
+<details>
+<summary>⚫ <b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json`:
 
 ```json
 {
@@ -68,7 +101,12 @@ Add to your AI assistant's MCP config:
 }
 ```
 
-### Cursor (`.cursor/mcp.json`)
+</details>
+
+<details>
+<summary>🔴 <b>Windsurf</b></summary>
+
+Add to `.windsurf/mcp.json`:
 
 ```json
 {
@@ -81,15 +119,108 @@ Add to your AI assistant's MCP config:
 }
 ```
 
-## Environment Variables
+</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 `~/`) |
+| `get_project_structure` | Get modules, classes, functions, variables |
+| `get_dependencies` | Get import / call / containment relationships |
+| `get_insights` | Get AI-generated code quality insights |
+| `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
+
+If you prefer installing globally instead of using `npx`:
+
+```bash
+npm install -g @giauphan/codeatlas-mcp
+```
+
+Then use `"command": "codeatlas-mcp"` (no `args` needed) in your MCP config.
+
+---
+
+## 🔧 Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `CODEATLAS_PROJECT_DIR` | Optional: specify a project directory to analyze |
+| `CODEATLAS_PROJECT_DIR` | Force a specific project directory |
+
+> By default, the server **auto-discovers** all projects with `.codeatlas/analysis.json` under your home directory.
+
+---
+
+## 🌐 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>` |
 
-The server auto-discovers projects by scanning `~/` for `.codeatlas/analysis.json` files.
+---
 
-## Development
+## 🧑‍💻 Development
 
 ```bash
 git clone https://github.com/giauphan/codeatlas-mcp.git

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.3",
+  "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",