@grec0/memory-bank-mcp 0.1.2 → 0.1.4

package/README.md

@@ -905,7 +905,7 @@ npm test -- --coverage
 1. **Aumenta `minScore`**: Usa 0.8 o 0.9 para resultados más precisos
 2. **Usa filtros**: `filterByFile` o `filterByLanguage`
 3. **Reformula la query**: Sé más específico y descriptivo
-4. **Reindexa**: `memorybank_index_code({ forceReindex: true })`
+4. **Reindexa**: `memorybank_index_code({ path: "..." })` (detecta cambios automáticamente por hash)
 
 ### Error: "projectId is required"
 
@@ -917,15 +917,17 @@ npm test -- --coverage
 memorybank_get_stats({})
 ```
 
-Si `pendingFiles` muestra archivos pendientes:
+Si `pendingFiles` muestra archivos pendientes, reindexa el directorio:
 
 ```json
 {
   "projectId": "my-project",
-  "forceReindex": true
+  "path": "C:/workspaces/mi-proyecto/src"
 }
 ```
 
+El sistema detecta cambios por hash automáticamente. Solo usa `forceReindex: true` si necesitas regenerar embeddings aunque no haya cambios.
+
 ---
 
 ## 📖 Documentación Adicional

package/dist/common/projectKnowledgeService.js

@@ -362,7 +362,7 @@ ${chunk.content}
         return doc;
     }
     /**
-     * Generates all project documents
+     * Generates all project documents (in parallel for speed)
      */
     async generateAllDocuments(chunks, force = false) {
         const result = {
@@ -374,54 +374,65 @@ ${chunk.content}
             totalOutputTokens: 0,
             errors: [],
         };
-        // Get previous progress if exists
+        // Get previous progress if exists (read before parallel generation)
         let previousProgress;
         const progressPath = path.join(this.options.docsPath, "progress.md");
         if (fs.existsSync(progressPath)) {
             previousProgress = fs.readFileSync(progressPath, "utf-8");
         }
-        // Define generation order (some docs may depend on others conceptually)
-        const docOrder = [
-            "techContext", // Foundation - understand the tech stack first
-            "projectBrief", // High-level overview
-            "systemPatterns", // Architecture
-            "productContext", // Business/user perspective
-            "activeContext", // Current state
-            "progress", // Progress tracking (last, uses previous data)
+        // Prepare chunks for activeContext (recent only)
+        const recentChunks = [...chunks]
+            .sort((a, b) => b.timestamp - a.timestamp)
+            .slice(0, Math.min(30, chunks.length));
+        // All document types to generate
+        const docTypes = [
+            "techContext",
+            "projectBrief",
+            "systemPatterns",
+            "productContext",
+            "activeContext",
+            "progress",
         ];
-        for (const docType of docOrder) {
+        console.error(`\n🚀 Generating ${docTypes.length} documents in PARALLEL...`);
+        // Generate all documents in parallel
+        const generationPromises = docTypes.map(async (docType) => {
             try {
-                // For activeContext, use only recent chunks (by timestamp)
-                let docChunks = chunks;
-                if (docType === "activeContext") {
-                    // Sort by timestamp and take most recent
-                    docChunks = [...chunks]
-                        .sort((a, b) => b.timestamp - a.timestamp)
-                        .slice(0, Math.min(30, chunks.length));
-                }
+                // For activeContext, use only recent chunks
+                const docChunks = docType === "activeContext" ? recentChunks : chunks;
                 const existingMetadata = this.metadataCache.get(docType);
                 const isNew = !existingMetadata;
                 const doc = await this.generateDocument(docType, docChunks, force, docType === "progress" ? previousProgress : undefined);
-                if (doc) {
-                    result.totalReasoningTokens += doc.metadata.reasoningTokens;
-                    result.totalOutputTokens += doc.metadata.outputTokens;
-                    if (isNew) {
-                        result.documentsGenerated.push(docType);
-                    }
-                    else {
-                        result.documentsUpdated.push(docType);
-                    }
-                }
-                else {
-                    result.documentsSkipped.push(docType);
-                }
+                return { docType, doc, isNew, error: null };
             }
             catch (error) {
+                return { docType, doc: null, isNew: false, error: error };
+            }
+        });
+        // Wait for all documents to complete
+        const results = await Promise.all(generationPromises);
+        // Process results
+        for (const { docType, doc, isNew, error } of results) {
+            if (error) {
                 console.error(`Error generating ${docType}: ${error.message}`);
                 result.errors.push(`${docType}: ${error.message}`);
                 result.success = false;
+                continue;
+            }
+            if (doc) {
+                result.totalReasoningTokens += doc.metadata.reasoningTokens;
+                result.totalOutputTokens += doc.metadata.outputTokens;
+                if (isNew) {
+                    result.documentsGenerated.push(docType);
+                }
+                else {
+                    result.documentsUpdated.push(docType);
+                }
+            }
+            else {
+                result.documentsSkipped.push(docType);
             }
         }
+        console.error(`\n✅ Parallel generation complete: ${result.documentsGenerated.length + result.documentsUpdated.length} docs, ${result.totalReasoningTokens} reasoning + ${result.totalOutputTokens} output tokens`);
         return result;
     }
     /**
@@ -462,42 +473,53 @@ ${chunk.content}
             totalOutputTokens: 0,
             errors: [],
         };
-        // Get previous progress
+        // Get previous progress (read before parallel generation)
         let previousProgress;
         const progressPath = path.join(this.options.docsPath, "progress.md");
         if (fs.existsSync(progressPath)) {
             previousProgress = fs.readFileSync(progressPath, "utf-8");
         }
-        for (const docType of docsToUpdate) {
+        // Prepare recent chunks for activeContext
+        const recentChunks = [...chunks]
+            .sort((a, b) => b.timestamp - a.timestamp)
+            .slice(0, Math.min(30, chunks.length));
+        console.error(`\n🚀 Updating ${docsToUpdate.length} documents in PARALLEL...`);
+        // Generate docs in parallel
+        const updatePromises = docsToUpdate.map(async (docType) => {
             try {
-                let docChunks = chunks;
-                if (docType === "activeContext") {
-                    docChunks = [...chunks]
-                        .sort((a, b) => b.timestamp - a.timestamp)
-                        .slice(0, Math.min(30, chunks.length));
-                }
+                const docChunks = docType === "activeContext" ? recentChunks : chunks;
                 const existingMetadata = this.metadataCache.get(docType);
                 const isNew = !existingMetadata;
                 const doc = await this.generateDocument(docType, docChunks, true, // Force update for changed docs
                 docType === "progress" ? previousProgress : undefined);
-                if (doc) {
-                    result.totalReasoningTokens += doc.metadata.reasoningTokens;
-                    result.totalOutputTokens += doc.metadata.outputTokens;
-                    if (isNew) {
-                        result.documentsGenerated.push(docType);
-                    }
-                    else {
-                        result.documentsUpdated.push(docType);
-                    }
-                }
-                else {
-                    result.documentsSkipped.push(docType);
-                }
+                return { docType, doc, isNew, error: null };
             }
             catch (error) {
+                return { docType, doc: null, isNew: false, error: error };
+            }
+        });
+        // Wait for all
+        const updateResults = await Promise.all(updatePromises);
+        // Process results
+        for (const { docType, doc, isNew, error } of updateResults) {
+            if (error) {
                 console.error(`Error updating ${docType}: ${error.message}`);
                 result.errors.push(`${docType}: ${error.message}`);
                 result.success = false;
+                continue;
+            }
+            if (doc) {
+                result.totalReasoningTokens += doc.metadata.reasoningTokens;
+                result.totalOutputTokens += doc.metadata.outputTokens;
+                if (isNew) {
+                    result.documentsGenerated.push(docType);
+                }
+                else {
+                    result.documentsUpdated.push(docType);
+                }
+            }
+            else {
+                result.documentsSkipped.push(docType);
             }
         }
         // Mark docs we didn't update as skipped

package/dist/index.js

@@ -38,24 +38,31 @@ const server = new McpServer({
     version: VERSION,
 });
 // Tool: Index Code
-server.tool("memorybank_index_code", "Indexa semánticamente código de un directorio o archivo específico para permitir búsquedas semánticas. El projectId es OBLIGATORIO y debe coincidir con el definido en AGENTS.md", {
+server.tool("memorybank_index_code", `Indexa semánticamente código de un DIRECTORIO para búsquedas semánticas.
+
+⚠️ IMPORTANTE:
+- El path debe ser una RUTA ABSOLUTA a un DIRECTORIO (no archivo)
+- Ejemplo correcto: "C:/workspaces/mi-proyecto/src/components"
+- Ejemplo incorrecto: "src/components" (ruta relativa)
+- Ejemplo incorrecto: "C:/workspaces/mi-proyecto/src/file.ts" (archivo, no directorio)
+
+Si quieres indexar un archivo específico, usa el directorio que lo contiene.`, {
     projectId: z
         .string()
-        .describe("Identificador único del proyecto (OBLIGATORIO). Debe coincidir con el definido en AGENTS.md del proyecto"),
+        .describe("Identificador único del proyecto (OBLIGATORIO). Debe coincidir con el definido en AGENTS.md"),
     path: z
         .string()
-        .optional()
-        .describe("Ruta relativa o absoluta del directorio/archivo a indexar (por defecto: raíz del workspace)"),
+        .describe("RUTA ABSOLUTA al DIRECTORIO a indexar. Ejemplo: 'C:/workspaces/proyecto/src'. NO usar rutas relativas. NO usar rutas a archivos."),
     recursive: z
         .boolean()
         .optional()
         .default(true)
-        .describe("Indexar recursivamente subdirectorios"),
+        .describe("Indexar recursivamente subdirectorios (default: true)"),
     forceReindex: z
         .boolean()
         .optional()
         .default(false)
-        .describe("Forzar reindexación completa aunque no haya cambios"),
+        .describe("RARAMENTE NECESARIO. El sistema detecta cambios por hash automáticamente. Solo usa true si necesitas regenerar embeddings sin cambios en archivos."),
 }, async (args) => {
     const result = await indexCode({
         projectId: args.projectId,
@@ -107,18 +114,21 @@ server.tool("memorybank_search", "Busca código relevante mediante búsqueda sem
     };
 });
 // Tool: Read File
-server.tool("memorybank_read_file", "Lee el contenido de un archivo específico del workspace. Usa esta herramienta para obtener contexto adicional cuando los fragmentos de búsqueda no son suficientes", {
+server.tool("memorybank_read_file", `Lee el contenido de un archivo específico. Usa para obtener contexto adicional.
+
+⚠️ Preferir RUTA ABSOLUTA para evitar errores.
+Ejemplo: "C:/workspaces/proyecto/src/index.ts"`, {
     path: z
         .string()
-        .describe("Ruta relativa o absoluta del archivo a leer"),
+        .describe("Ruta al archivo. Preferir ABSOLUTA: 'C:/workspaces/proyecto/src/file.ts'"),
     startLine: z
         .number()
         .optional()
-        .describe("Línea inicial para leer un rango específico (opcional)"),
+        .describe("Línea inicial (opcional)"),
     endLine: z
         .number()
         .optional()
-        .describe("Línea final para leer un rango específico (opcional)"),
+        .describe("Línea final (opcional)"),
 }, async (args) => {
     const result = await readFile({
         path: args.path,
@@ -130,21 +140,24 @@ server.tool("memorybank_read_file", "Lee el contenido de un archivo específico
     };
 });
 // Tool: Write File
-server.tool("memorybank_write_file", "Escribe o modifica un archivo y automáticamente lo reindexa en el Memory Bank para mantener la consistencia. El projectId es OBLIGATORIO para la reindexación correcta", {
+server.tool("memorybank_write_file", `Escribe un archivo y automáticamente lo reindexa en el Memory Bank.
+
+⚠️ Preferir RUTA ABSOLUTA para evitar errores.
+Ejemplo path: "C:/workspaces/proyecto/src/nuevo.ts"`, {
     projectId: z
         .string()
-        .describe("Identificador del proyecto (OBLIGATORIO). Necesario para la auto-reindexación correcta"),
+        .describe("Identificador del proyecto (OBLIGATORIO)"),
     path: z
         .string()
-        .describe("Ruta relativa o absoluta del archivo a escribir"),
+        .describe("Ruta al archivo. Preferir ABSOLUTA: 'C:/workspaces/proyecto/src/file.ts'"),
     content: z
         .string()
-        .describe("Contenido completo del archivo a escribir"),
+        .describe("Contenido COMPLETO del archivo"),
     autoReindex: z
         .boolean()
         .optional()
         .default(true)
-        .describe("Reindexar automáticamente el archivo después de escribirlo"),
+        .describe("Auto-reindexar después de escribir (default: true)"),
 }, async (args) => {
     const result = await writeFile({
         projectId: args.projectId,
@@ -164,13 +177,18 @@ server.tool("memorybank_get_stats", "Obtiene estadísticas del Memory Bank: arch
     };
 });
 // Tool: Analyze Coverage
-server.tool("memorybank_analyze_coverage", "Analiza la cobertura de indexación del proyecto. Muestra qué carpetas/archivos están indexados, cuáles no, y cuáles tienen cambios pendientes. OBLIGATORIO: projectId y path (ruta absoluta del workspace). NOTA: Puede tardar en workspaces grandes", {
+server.tool("memorybank_analyze_coverage", `Analiza la cobertura de indexación del proyecto.
+
+⚠️ IMPORTANTE:
+- path debe ser RUTA ABSOLUTA al DIRECTORIO raíz del workspace
+- Ejemplo: "C:/workspaces/mi-proyecto" (NO rutas relativas)
+- Puede tardar en workspaces grandes`, {
     projectId: z
         .string()
-        .describe("Identificador del proyecto a analizar (OBLIGATORIO)"),
+        .describe("Identificador del proyecto (OBLIGATORIO)"),
     path: z
         .string()
-        .describe("Ruta absoluta del workspace a analizar (OBLIGATORIO). Ejemplo: 'C:/workspaces/mi-proyecto'"),
+        .describe("RUTA ABSOLUTA al directorio raíz del workspace. Ejemplo: 'C:/workspaces/mi-proyecto'"),
 }, async (args) => {
     try {
         const targetPath = args.path;
@@ -261,13 +279,15 @@ server.tool(getProjectDocsToolDefinition.name, getProjectDocsToolDefinition.desc
 // Context Management Tools (Cline-style)
 // ==========================================
 // Tool: Initialize Memory Bank
-server.tool(initializeMemoryBankToolDefinition.name, initializeMemoryBankToolDefinition.description, {
+server.tool(initializeMemoryBankToolDefinition.name, initializeMemoryBankToolDefinition.description + `
+
+⚠️ projectPath debe ser RUTA ABSOLUTA. Ejemplo: "C:/workspaces/mi-proyecto"`, {
     projectId: z
         .string()
         .describe("Identificador único del proyecto (OBLIGATORIO)"),
     projectPath: z
         .string()
-        .describe("Ruta absoluta del proyecto"),
+        .describe("RUTA ABSOLUTA al proyecto. Ejemplo: 'C:/workspaces/mi-proyecto'"),
     projectName: z
         .string()
         .optional()

package/dist/tools/analyzeCoverage.js

@@ -177,7 +177,7 @@ function generateRecommendations(stats, tree) {
     }
     // Pending reindex
     if (stats.pendingReindexFiles > 0) {
-        recommendations.push(`🔄 Hay ${stats.pendingReindexFiles} archivo(s) con cambios pendientes de reindexación. Ejecuta memorybank_index_code({ forceReindex: true })`);
+        recommendations.push(`🔄 Hay ${stats.pendingReindexFiles} archivo(s) con cambios pendientes. Ejecuta memorybank_index_code con el path del directorio - los cambios se detectan automáticamente por hash.`);
     }
     // Language-specific recommendations
     const unindexedLanguages = Object.entries(stats.languageBreakdown)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grec0/memory-bank-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "MCP server for semantic code indexing with Memory Bank - AI-powered codebase understanding",
   "license": "MIT",
   "author": "@grec0",