@latentforce/shift 1.0.16 → 1.0.17

package/README.md

@@ -302,9 +302,11 @@ When left as-is (single entry with `language: null` and `path: ""`), the server
 
 | Tool | Description |
 |------|-------------|
-| `blast_radius` | Analyze what files would be affected if a file is modified or deleted |
-| `dependencies` | Get all dependencies for a file with relationship summaries |
+| `project_overview` | Get the highest-level context for the project: architecture, tech stack, entry points, and top-level modules |
 | `file_summary` | Get a summary of a file with optional parent directory context |
+| `module_summary` | Get full documentation for the module that owns a given file, including DRG cluster metadata and parent/child module relationships |
+| `dependencies` | Get all dependencies for a file with relationship summaries |
+| `blast_radius` | Analyze what files would be affected if a file is modified or deleted |
 
 Each tool accepts an optional `project_id` parameter. If not provided, it falls back to the `SHIFT_PROJECT_ID` environment variable.
 

package/build/mcp-server.js

@@ -31,53 +31,118 @@ function normalizePath(filePath) {
     p = p.replace(/^\//, '');
     return p;
 }
-// helper
+function getAuthHeaders() {
+    const apiKey = getApiKeyFromEnv();
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    return headers;
+}
+function handleApiError(response, text) {
+    if (response.status === 404) {
+        if (text.includes('Knowledge graph not found') || text.includes('knowledge graph')) {
+            throw new Error("No knowledge graph exists for this project. Run 'shift-cli update-drg' to build it.");
+        }
+        if (text.includes('File not found') || text.includes('not found in')) {
+            const pathMatch = text.match(/['"]([^'"]+)['"]/);
+            const filePath = pathMatch ? pathMatch[1] : 'the requested file';
+            throw new Error(`File '${filePath}' not found in knowledge graph. Possible causes:\n` +
+                `  1. The path may be incorrect (check casing and slashes)\n` +
+                `  2. The file was added after the last 'shift-cli update-drg'\n` +
+                `  3. The file type is not supported (only JS/TS files are indexed)`);
+        }
+    }
+    throw new Error(`API call failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`);
+}
+/** POST to backend API */
 async function callBackendAPI(endpoint, data) {
-    try {
-        const apiKey = getApiKeyFromEnv();
-        const headers = {
-            'Content-Type': 'application/json',
-        };
-        if (apiKey) {
-            headers['Authorization'] = `Bearer ${apiKey}`;
-        }
-        const response = await fetch(`${BASE_URL}${endpoint}`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(data),
-        });
-        if (!response.ok) {
-            const text = await response.text();
-            // Provide actionable error messages
-            if (response.status === 404) {
-                if (text.includes('Knowledge graph not found') || text.includes('knowledge graph')) {
-                    throw new Error("No knowledge graph exists for this project. Run 'shift-cli update-drg' to build it.");
-                }
-                if (text.includes('File not found') || text.includes('not found in')) {
-                    // Extract path from error if possible
-                    const pathMatch = text.match(/['"]([^'"]+)['"]/);
-                    const filePath = pathMatch ? pathMatch[1] : 'the requested file';
-                    throw new Error(`File '${filePath}' not found in knowledge graph. Possible causes:\n` +
-                        `  1. The path may be incorrect (check casing and slashes)\n` +
-                        `  2. The file was added after the last 'shift-cli update-drg'\n` +
-                        `  3. The file type is not supported (only JS/TS files are indexed)`);
-                }
-            }
-            throw new Error(`API call failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`);
-        }
-        return await response.json();
-    }
-    catch (error) {
-        throw error;
+    const response = await fetch(`${BASE_URL}${endpoint}`, {
+        method: 'POST',
+        headers: getAuthHeaders(),
+        body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        handleApiError(response, text);
     }
+    return await response.json();
 }
+/** GET from backend API with query params */
+async function callBackendAPIGet(endpoint, params) {
+    const qs = new URLSearchParams(params).toString();
+    const url = `${BASE_URL}${endpoint}${qs ? `?${qs}` : ''}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: getAuthHeaders(),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        handleApiError(response, text);
+    }
+    return await response.json();
+}
+// ============= FORMATTERS =============
 /** Format file_summary response as readable markdown */
 function formatFileSummary(data) {
     const lines = [];
     lines.push(`## File: ${data.path}`);
+    if (data.module_name) {
+        lines.push(`**Module:** ${data.module_name}`);
+    }
     lines.push('');
     lines.push('### Summary');
     lines.push(data.summary || 'No summary available.');
+    if (data.exports && Object.keys(data.exports).length > 0) {
+        lines.push('');
+        lines.push('### Exports');
+        for (const [category, items] of Object.entries(data.exports)) {
+            if (items?.length > 0) {
+                lines.push(`**${category}:** ${items.join(', ')}`);
+            }
+        }
+    }
+    if (data.key_components?.length > 0) {
+        lines.push('');
+        lines.push('### Key Components');
+        for (const comp of data.key_components) {
+            if (typeof comp === 'object' && comp !== null) {
+                const name = comp.name || comp.component || Object.keys(comp)[0] || '';
+                const desc = comp.description || comp.purpose || Object.values(comp)[0] || '';
+                lines.push(`- **${name}**: ${desc}`);
+            }
+            else {
+                lines.push(`- ${comp}`);
+            }
+        }
+    }
+    if (data.internal_state) {
+        lines.push('');
+        lines.push(`**Internal State:** ${data.internal_state}`);
+    }
+    if (data.error_handling) {
+        lines.push(`**Error Handling:** ${data.error_handling}`);
+    }
+    if (data.constraints?.length > 0) {
+        lines.push('');
+        lines.push('### Constraints');
+        for (const c of data.constraints) {
+            lines.push(`- ${c}`);
+        }
+    }
+    if (data.dependencies?.length > 0) {
+        lines.push('');
+        lines.push(`### Dependencies (${data.dependency_count ?? data.dependencies.length} imports)`);
+        for (const dep of data.dependencies) {
+            lines.push(`- ${dep}`);
+        }
+    }
+    if (data.dependents?.length > 0) {
+        lines.push('');
+        lines.push(`### Dependents (${data.dependent_count ?? data.dependents.length} files import this)`);
+        for (const dep of data.dependents) {
+            lines.push(`- ${dep}`);
+        }
+    }
     if (data.parent_summaries?.length > 0) {
         lines.push('');
         lines.push('### Directory Context');
@@ -91,41 +156,73 @@ function formatFileSummary(data) {
 function formatDependencies(data) {
     const lines = [];
     const deps = data.dependencies || [];
-    const edges = data.edge_summaries || {};
+    // edge_details is now a dict of {imports, usage_pattern, data_flow, dependency_summary}
+    const edgeDetails = data.edge_details || {};
     lines.push(`## Dependencies: ${data.path}`);
+    if (data.module_name) {
+        lines.push(`**Module:** ${data.module_name}`);
+    }
     lines.push('');
+    // --- Forward dependencies ---
     if (deps.length === 0) {
         lines.push('This file has no dependencies.');
     }
     else {
-        lines.push(`This file depends on **${deps.length}** file(s):`);
+        lines.push(`### Imports (${deps.length} file(s) this file depends on)`);
         lines.push('');
         for (const dep of deps) {
-            const summary = edges[dep];
-            if (summary) {
-                lines.push(`- **${dep}**: ${summary}`);
+            const edge = edgeDetails[dep];
+            if (edge) {
+                lines.push(`- **${dep}**`);
+                if (edge.usage_pattern)
+                    lines.push(`  - Usage: ${edge.usage_pattern}`);
+                if (edge.data_flow)
+                    lines.push(`  - Data flow: ${edge.data_flow}`);
+                if (edge.imports?.length > 0)
+                    lines.push(`  - Imports: ${edge.imports.join(', ')}`);
+                if (edge.dependency_summary)
+                    lines.push(`  - Summary: ${edge.dependency_summary}`);
             }
             else {
                 lines.push(`- **${dep}**`);
             }
         }
     }
+    // --- Reverse dependencies ---
+    const dependents = data.dependents || [];
+    const dependentEdges = data.dependent_edge_details || {};
+    if (dependents.length > 0) {
+        lines.push('');
+        lines.push(`### Dependents (${dependents.length} file(s) that import this file)`);
+        lines.push('');
+        for (const dep of dependents) {
+            const edge = dependentEdges[dep];
+            if (edge) {
+                lines.push(`- **${dep}**`);
+                if (edge.usage_pattern)
+                    lines.push(`  - Usage: ${edge.usage_pattern}`);
+                if (edge.data_flow)
+                    lines.push(`  - Data flow: ${edge.data_flow}`);
+                if (edge.imports?.length > 0)
+                    lines.push(`  - Imports: ${edge.imports.join(', ')}`);
+                if (edge.dependency_summary)
+                    lines.push(`  - Summary: ${edge.dependency_summary}`);
+            }
+            else {
+                lines.push(`- **${dep}**`);
+            }
+        }
+    }
+    // --- Implicit dependencies ---
     const implicitDeps = data.implicit_dependencies || [];
     if (implicitDeps.length > 0) {
         lines.push('');
-        lines.push('## Implicit / external dependencies');
-        lines.push('');
-        lines.push(`Implicit dependencies (**${implicitDeps.length}**):`);
+        lines.push(`### Implicit / External Dependencies (${implicitDeps.length})`);
         lines.push('');
         const implicitEdges = data.implicit_edge_summaries || {};
         for (const dep of implicitDeps) {
             const summary = implicitEdges[dep];
-            if (summary) {
-                lines.push(`- **${dep}**: ${summary}`);
-            }
-            else {
-                lines.push(`- **${dep}**`);
-            }
+            lines.push(summary ? `- **${dep}**: ${summary}` : `- **${dep}**`);
         }
     }
     return lines.join('\n');
@@ -135,6 +232,9 @@ function formatBlastRadius(data) {
     const lines = [];
     const affected = data.affected_files || [];
     lines.push(`## Blast Radius: ${data.path}`);
+    if (data.module_name) {
+        lines.push(`**Module:** ${data.module_name}`);
+    }
     lines.push('');
     if (affected.length === 0) {
         lines.push('No other files are affected by changes to this file.');
@@ -152,26 +252,155 @@ function formatBlastRadius(data) {
         }
         const levels = Object.keys(byLevel).map(Number).sort((a, b) => a - b);
         for (const level of levels) {
-            const label = level === 1 ? 'Level 1 (direct)' : `Level ${level}`;
-            lines.push(`### ${label}`);
+            lines.push(`### ${level === 1 ? 'Level 1 (direct)' : `Level ${level}`}`);
             for (const file of byLevel[level]) {
                 lines.push(`- **${file.path}**: ${file.summary || 'No summary'}`);
             }
             lines.push('');
         }
     }
+    // --- Affected clusters ---
+    const clusters = data.cluster_blast_radius || [];
+    if (clusters.length > 0) {
+        lines.push('### Affected Modules/Folders');
+        for (const cluster of clusters) {
+            lines.push(`- **${cluster.path}**: ${cluster.summary}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Format module_summary response as readable markdown */
+function formatModuleSummary(data) {
+    const lines = [];
+    lines.push(`## Module: ${data.module_name}`);
+    if (data.parent_module) {
+        lines.push(`**Parent module:** ${data.parent_module}`);
+    }
+    if (data.child_modules?.length > 0) {
+        lines.push(`**Sub-modules:** ${data.child_modules.join(', ')}`);
+    }
+    if (data.drg_cluster_summary) {
+        lines.push('');
+        lines.push('### Architecture Summary');
+        lines.push(data.drg_cluster_summary);
+    }
+    if (data.drg_cluster_metadata && Object.keys(data.drg_cluster_metadata).length > 0) {
+        const meta = data.drg_cluster_metadata;
+        if (meta.architecture_layers?.length > 0) {
+            lines.push('');
+            lines.push('**Architecture Layers:**');
+            for (const layer of meta.architecture_layers) {
+                lines.push(`- ${layer}`);
+            }
+        }
+        if (meta.technology_stack?.length > 0) {
+            lines.push('');
+            lines.push('**Technology Stack:**');
+            for (const tech of meta.technology_stack) {
+                lines.push(`- ${tech}`);
+            }
+        }
+    }
+    if (data.components?.length > 0) {
+        lines.push('');
+        lines.push(`### Files in this module (${data.components.length})`);
+        for (const comp of data.components) {
+            lines.push(`- ${comp}`);
+        }
+    }
+    if (data.content) {
+        lines.push('');
+        lines.push('### Full Documentation');
+        lines.push(data.content);
+    }
     return lines.join('\n');
 }
+/** Format project_overview response as readable markdown */
+function formatProjectOverview(data) {
+    const lines = [];
+    lines.push('## Project Overview');
+    lines.push('');
+    if (data.architecture_summary) {
+        lines.push('### Architecture Summary');
+        lines.push(data.architecture_summary);
+        lines.push('');
+    }
+    if (data.architecture_layers?.length > 0) {
+        lines.push('### Architecture Layers');
+        for (const layer of data.architecture_layers) {
+            if (typeof layer === 'string') {
+                lines.push(`- ${layer}`);
+            }
+            else if (layer && typeof layer === 'object') {
+                const name = layer.name || layer.layer || layer.title || Object.values(layer)[0];
+                const desc = layer.description || layer.desc || (Object.values(layer).length > 1 ? Object.values(layer)[1] : '');
+                lines.push(desc ? `- **${name}**: ${desc}` : `- ${name}`);
+            }
+        }
+        lines.push('');
+    }
+    if (data.technology_stack?.length > 0) {
+        lines.push('### Technology Stack');
+        for (const tech of data.technology_stack) {
+            if (typeof tech === 'string') {
+                lines.push(`- ${tech}`);
+            }
+            else if (tech && typeof tech === 'object') {
+                const name = tech.name || tech.technology || tech.title || Object.values(tech)[0];
+                const desc = tech.description || tech.desc || (Object.values(tech).length > 1 ? Object.values(tech)[1] : '');
+                lines.push(desc ? `- **${name}**: ${desc}` : `- ${name}`);
+            }
+        }
+        lines.push('');
+    }
+    if (data.entry_points?.length > 0) {
+        lines.push('### Entry Points');
+        for (const ep of data.entry_points) {
+            if (typeof ep === 'string') {
+                lines.push(`- ${ep}`);
+            }
+            else if (ep && typeof ep === 'object') {
+                const name = ep.name || ep.file || ep.path || Object.values(ep)[0];
+                const desc = ep.description || ep.desc || (Object.values(ep).length > 1 ? Object.values(ep)[1] : '');
+                lines.push(desc ? `- **${name}**: ${desc}` : `- ${name}`);
+            }
+        }
+        lines.push('');
+    }
+    if (data.constraints?.length > 0) {
+        lines.push('### Constraints');
+        for (const c of data.constraints) {
+            lines.push(`- ${c}`);
+        }
+        lines.push('');
+    }
+    if (data.top_level_modules?.length > 0) {
+        lines.push('### Top-level Modules');
+        lines.push('');
+        for (const mod of data.top_level_modules) {
+            lines.push(`#### ${mod.path}`);
+            lines.push(mod.summary || '');
+            if (mod.files?.length > 0) {
+                lines.push(`Files: ${mod.files.join(', ')}`);
+            }
+            lines.push('');
+        }
+    }
+    if (data.codewiki_overview) {
+        lines.push('### Project Documentation');
+        lines.push(data.codewiki_overview);
+    }
+    return lines.join('\n');
+}
+// ============= MCP SERVER =============
 export async function startMcpServer() {
-    // Create server instance
     const server = new McpServer({
         name: "shift",
         version,
     });
-    // Tools:
-    // Blast radius
+    // ---- blast_radius ----
     server.registerTool("blast_radius", {
-        description: "Use this BEFORE editing or refactoring any source file. Returns every file in the project that imports or depends on the given file, grouped by dependency depth (level 1 = direct importers, level 2 = their importers, etc.). Use this to understand the full impact of a change before making it. Only works on indexed source files: .js .jsx .ts .tsx .py .java .cpp .cs .go .c .h .css .scss .html — do not call for .json, .yaml, .md or other non-source files.",
+        description: "Use this BEFORE editing or refactoring any source file. Returns every file in the project that imports or depends on the given file, grouped by dependency depth (level 1 = direct importers, level 2 = their importers, etc.). Also returns the affected modules/folders. Use this to understand the full impact of a change before making it. Only works on indexed source files: .js .jsx .ts .tsx .py .java .cpp .cs .go .c .h .css .scss .html — do not call for .json, .yaml, .md or other non-source files.",
         inputSchema: z.object({
             file_path: z.string().describe("Path to the file (relative to project root)"),
             project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
@@ -184,18 +413,11 @@ export async function startMcpServer() {
             project_id: projectId,
             ...(args.level != null && { level: args.level }),
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: formatBlastRadius(data)
-                },
-            ],
-        };
+        return { content: [{ type: "text", text: formatBlastRadius(data) }] };
     });
-    // Dependencies
+    // ---- dependencies ----
     server.registerTool("dependencies", {
-        description: "Returns every file that the given source file imports or depends on, along with a short summary of why each dependency is used. Use this to trace data flow, understand module relationships, follow a bug through the call chain, or map out what a file relies on before modifying it. Only works on indexed source files: .js .jsx .ts .tsx .py .java .cpp .cs .go .c .h .css .scss .html — do not call for .json, .yaml, .md or other non-source files.",
+        description: "Returns bidirectional dependencies of a source file: what it imports (with usage pattern, data flow, and summary per dependency) AND what imports it (reverse dependencies). Use this to trace data flow, understand module relationships, follow a bug through the call chain, or map out what a file relies on before modifying it. Only works on indexed source files: .js .jsx .ts .tsx .py .java .cpp .cs .go .c .h .css .scss .html — do not call for .json, .yaml, .md or other non-source files.",
         inputSchema: z.object({
             file_path: z.string().describe("Path to the file"),
             project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
@@ -206,18 +428,11 @@ export async function startMcpServer() {
             path: normalizePath(args.file_path),
             project_id: projectId,
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: formatDependencies(data)
-                },
-            ],
-        };
+        return { content: [{ type: "text", text: formatDependencies(data) }] };
     });
-    // File summary (maps to what-is-this-file)
+    // ---- file_summary ----
     server.registerTool("file_summary", {
-        description: "Returns an AI-generated summary of a source file: what it does, its key exports and functions, its role in the project, and how it fits into the surrounding architecture. Always call this before reading a raw file — it gives you the essential context without having to parse the full source. Use the 'level' parameter to include summaries of parent directories for broader context. Only works on indexed source files: .js .jsx .ts .tsx .py .java .cpp .cs .go .c .h .css .scss .html — for .json, .yaml, .md, or other non-source files, read them directly instead.",
+        description: "Returns an AI-generated summary of a source file: what it does, its key exports and functions, internal state, error handling, constraints, what it imports, who imports it, and which module it belongs to. Always call this before reading a raw file — it gives you the essential context without having to parse the full source. Use the 'level' parameter to include summaries of parent directories for broader context. Only works on indexed source files: .js .jsx .ts .tsx .py .java .cpp .cs .go .c .h .css .scss .html — for .json, .yaml, .md, or other non-source files, read them directly instead.",
         inputSchema: z.object({
             file_path: z.string().describe("Path to the file to summarize"),
             project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
@@ -230,14 +445,35 @@ export async function startMcpServer() {
             project_id: projectId,
             level: args.level ?? 0,
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: formatFileSummary(data)
-                },
-            ],
-        };
+        return { content: [{ type: "text", text: formatFileSummary(data) }] };
+    });
+    // ---- module_summary ----
+    server.registerTool("module_summary", {
+        description: "Given any file path, returns the full documentation for the module that owns it, the list of files in that module, the corresponding DRG cluster summary and metadata, and parent/child module relationships. Use this after file_summary to get broader module-level context before editing — especially useful when a change may affect an entire module rather than just one file.",
+        inputSchema: z.object({
+            file_path: z.string().describe("Path to any file in the module (relative to project root)"),
+            project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
+        })
+    }, async (args) => {
+        const projectId = resolveProjectId(args);
+        const data = await callBackendAPI('/api/v1/mcp/module-summary', {
+            path: normalizePath(args.file_path),
+            project_id: projectId,
+        });
+        return { content: [{ type: "text", text: formatModuleSummary(data) }] };
+    });
+    // ---- project_overview ----
+    server.registerTool("project_overview", {
+        description: "Returns the highest-level context for the project: architecture summary, layers, tech stack, entry points, constraints, top-level modules with their files, and the project documentation overview. Call this first at the start of a session — before exploring any specific file — to understand the overall structure and where things live.",
+        inputSchema: z.object({
+            project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
+        })
+    }, async (args) => {
+        const projectId = resolveProjectId(args);
+        const data = await callBackendAPIGet('/api/v1/mcp/project-overview', {
+            project_id: projectId,
+        });
+        return { content: [{ type: "text", text: formatProjectOverview(data) }] };
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@latentforce/shift",
-    "version": "1.0.16",
+    "version": "1.0.17",
     "description": "Shift CLI - AI-powered code intelligence with MCP support",
     "type": "module",
     "main": "./build/index.js",