rag-memory-epf-mcp 3.3.6 → 3.4.0

package/dist/index.js

@@ -1170,6 +1170,46 @@ class RAGKnowledgeGraphManager {
         throw new Error('Embedding model not initialized. The server may still be loading the model — retry in a few seconds.');
     }
     // === NEW SEPARATE TOOLS ===
+    async syncDocumentFromFile(filePath, documentId, options = {}) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        // 1. Resolve content: raw file verbatim (default) or explicit override.
+        //    Content is read on the server and never routed through the model context.
+        const content = options.content !== undefined
+            ? options.content
+            : fsSync.readFileSync(filePath, 'utf-8');
+        const bytes = Buffer.byteLength(content, 'utf-8');
+        // 2. Metadata: default source=path, updated=today (YYYY-MM-DD); caller can override either.
+        const today = new Date().toISOString().slice(0, 10);
+        const metadata = { source: filePath, updated: today, ...(options.metadata || {}) };
+        console.error(`🔄 syncDocumentFromFile: ${documentId} <- ${filePath} (${bytes} bytes)`);
+        // 3. delete -> store -> chunk -> embed, reusing the existing pipeline methods.
+        await this.deleteDocuments(documentId);
+        await this.storeDocument(documentId, content, metadata);
+        const chunkResult = await this.chunkDocument(documentId, options.chunkParams || {});
+        const embedResult = await this.embedChunks(documentId);
+        // 4. Optional explicit entity links (in addition to auto term-matching in embedChunks).
+        let explicitlyLinked;
+        if (options.entityNames && options.entityNames.length > 0) {
+            const linkResult = await this.linkEntitiesToDocument(documentId, options.entityNames);
+            explicitlyLinked = linkResult.linkedEntities;
+        }
+        const linkedEntities = embedResult.linkedEntities ?? 0;
+        // 5. Terse summary only (no chunk text / content echo) to keep caller context flat.
+        const result = {
+            documentId,
+            bytes,
+            chunks: chunkResult.chunks.length,
+            embeddedChunks: embedResult.embeddedChunks,
+            linkedEntities,
+            ...(explicitlyLinked !== undefined ? { explicitlyLinked } : {}),
+        };
+        if (linkedEntities === 0 && explicitlyLinked === undefined) {
+            result.warning = 'linkedEntities=0: ensure the file content contains entity-name literals (e.g. a wiki anchor line "RAG entity: ...") so term-matching can link entities.';
+        }
+        console.error(`✅ syncDocumentFromFile done: ${documentId} (${result.chunks} chunks, ${result.embeddedChunks} embedded, ${linkedEntities} linked)`);
+        return result;
+    }
     async storeDocument(id, content, metadata = {}) {
         if (!this.db)
             throw new Error('Database not initialized');
@@ -2474,6 +2514,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.deleteDocuments(validatedArgs.documentIds), null, 2) }] };
             case "listDocuments":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.listDocuments(validatedArgs.includeMetadata !== false), null, 2) }] };
+            case "syncDocumentFromFile":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.syncDocumentFromFile(validatedArgs.path, validatedArgs.documentId, {
+                                metadata: validatedArgs.metadata,
+                                content: validatedArgs.content,
+                                entityNames: validatedArgs.entityNames,
+                                chunkParams: validatedArgs.chunkParams,
+                            }), null, 2) }] };
             // NEW: Entity embedding tools
             case "embedAllEntities":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.embedAllEntities(), null, 2) }] };

package/dist/src/tools/rag-tools.d.ts

@@ -7,6 +7,7 @@ export declare const linkEntitiesToDocumentTool: ToolDefinition;
 export declare const getKnowledgeGraphStatsTool: ToolDefinition;
 export declare const deleteDocumentsTool: ToolDefinition;
 export declare const listDocumentsTool: ToolDefinition;
+export declare const syncDocumentFromFileTool: ToolDefinition;
 export declare const ragTools: {
     storeDocument: ToolDefinition;
     chunkDocument: ToolDefinition;
@@ -16,4 +17,5 @@ export declare const ragTools: {
     getKnowledgeGraphStats: ToolDefinition;
     deleteDocuments: ToolDefinition;
     listDocuments: ToolDefinition;
+    syncDocumentFromFile: ToolDefinition;
 };

package/dist/src/tools/rag-tools.js

@@ -516,6 +516,93 @@ export const listDocumentsTool = {
     schema: listDocumentsSchema,
     annotations: { readOnlyHint: true },
 };
+// === SYNC DOCUMENT FROM FILE TOOL ===
+const syncDocumentFromFileCapability = {
+    description: 'Read a file server-side and run the full document sync pipeline (delete, store, chunk, embed, link) in one call, returning only a terse summary',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute path of the file to sync. Content is read server-side and never routed through the model context.'
+            },
+            documentId: {
+                type: 'string',
+                description: 'RAG document ID to (re)create from the file'
+            },
+            metadata: {
+                type: 'object',
+                description: 'Metadata merged into the stored document (source defaults to path, updated defaults to today)',
+                additionalProperties: true,
+                optional: true
+            },
+            content: {
+                type: 'string',
+                description: 'Optional content override; if provided, this is stored instead of reading the file',
+                optional: true
+            },
+            entityNames: {
+                type: 'array',
+                description: 'Optional entities to explicitly link in addition to automatic term-matching',
+                items: { type: 'string' },
+                optional: true
+            },
+            chunkParams: {
+                type: 'object',
+                description: 'Optional chunking parameters { maxTokens, overlap }',
+                additionalProperties: true,
+                optional: true
+            }
+        },
+        required: ['path', 'documentId'],
+    },
+};
+const syncDocumentFromFileDescription = () => `<description>
+Read a file on the server and perform the entire document sync pipeline in a single call:
+deleteDocuments -> storeDocument -> chunkDocument -> embedChunks -> (optional) linkEntitiesToDocument.
+**The file content is read server-side and is NOT routed through the model context**, and only a
+terse summary is returned (no chunk text). This collapses the usual 5 tool calls per document into
+one and keeps the conversation context flat, which is the dominant cost of large /sync runs.
+</description>
+
+<importantNotes>
+- (!important!) **Content is read from \`path\` on the server** - it does not pass through the model context
+- (!important!) **Stores the raw file verbatim** by default (higher search fidelity); pass \`content\` to override
+- (!important!) **Idempotent** - the target documentId is fully re-synced (delete + recreate) each call
+- (!important!) **Returns terse counts only** - { documentId, bytes, chunks, embeddedChunks, linkedEntities }
+- (!important!) **Entity linking** happens automatically via term-matching during embedding; \`entityNames\` adds explicit links
+</importantNotes>
+
+<whenToUseThisTool>
+- During /sync to persist a Markdown/SSOT file into the RAG store without paying the context cost of reading it into the model
+- When re-syncing decision logs, current-focus, wiki pages, or any file-backed document
+- As a one-call replacement for the manual storeDocument + chunkDocument + embedChunks + linkEntitiesToDocument sequence
+</whenToUseThisTool>
+
+<bestPractices>
+- Use the document's canonical ID (e.g. \`current-focus\`, \`wiki-project-context\`)
+- Keep an entity-name literal (e.g. wiki anchor line "RAG entity: ...") in the file so term-matching can link entities; a warning is returned if linkedEntities is 0
+- Pass \`metadata.updated\` (YYYY-MM-DD) for change tracking
+</bestPractices>
+
+<examples>
+- Sync current-focus: {"path": "/abs/decisions/current-focus.md", "documentId": "current-focus", "metadata": {"updated": "2026-05-23"}}
+- With explicit links: {"path": "/abs/wiki/project-context.md", "documentId": "wiki-project-context", "entityNames": ["Ultimate AI Personal Assistant"]}
+</examples>`;
+const syncDocumentFromFileSchema = {
+    path: z.string().describe('Absolute path of the file to sync (read server-side)'),
+    documentId: z.string().describe('RAG document ID to (re)create from the file'),
+    metadata: z.record(z.any()).optional().describe('Metadata merged into the stored document'),
+    content: z.string().optional().describe('Optional content override; stored instead of reading the file'),
+    entityNames: z.array(z.string()).optional().describe('Optional entities to explicitly link'),
+    chunkParams: z.record(z.any()).optional().describe('Optional chunking parameters { maxTokens, overlap }'),
+};
+export const syncDocumentFromFileTool = {
+    capability: syncDocumentFromFileCapability,
+    description: syncDocumentFromFileDescription,
+    schema: syncDocumentFromFileSchema,
+    annotations: { idempotentHint: true },
+};
 // Export all RAG tools
 export const ragTools = {
     storeDocument: storeDocumentTool,
@@ -526,4 +613,5 @@ export const ragTools = {
     getKnowledgeGraphStats: getKnowledgeGraphStatsTool,
     deleteDocuments: deleteDocumentsTool,
     listDocuments: listDocumentsTool,
+    syncDocumentFromFile: syncDocumentFromFileTool,
 };

package/dist/src/tools/tool-registry.d.ts

@@ -20,6 +20,7 @@ export declare const allTools: {
     getKnowledgeGraphStats: ToolDefinition;
     deleteDocuments: ToolDefinition;
     listDocuments: ToolDefinition;
+    syncDocumentFromFile: ToolDefinition;
     createEntities: ToolDefinition;
     createRelations: ToolDefinition;
     addObservations: ToolDefinition;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-memory-epf-mcp",
-  "version": "3.3.6",
+  "version": "3.4.0",
   "description": "Project-local RAG memory MCP server — knowledge graph + multilingual vector + FTS5 in a single SQLite file. Per-project isolation, 30 MCP tools, codepoint-safe chunking (Korean/CJK/emoji).",
   "keywords": [
     "mcp",