@syndicai/stack-mcp 0.2.0 → 0.3.0

package/README.md

@@ -39,11 +39,16 @@ Monorepo / unpublished:
 
 ## Tools
 
-| Tool                   | Purpose                                                                 |
-| ---------------------- | ----------------------------------------------------------------------- |
-| `memory_search`        | Hybrid retrieve                                                         |
-| `memory_ingest`        | Create/resume ingest (`path` or `text`; PDF/image rejected)             |
-| `memory_ingest_status` | Poll job                                                                |
+| Tool                        | Purpose                                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------------ |
+| `memory_list_collections`   | List collections (name, type, visibility, stats, soft-TTL hints)                                 |
+| `memory_search`             | Hybrid retrieve (optional `collectionId`; omit = all)                                            |
+| `memory_ingest`             | Start ingest async; **requires `collectionId`**; returns `jobId` (text/markdown/code only)       |
+| `memory_ingest_status`      | Poll job until `completed` / `failed`                                                            |
+| `memory_delete`             | Delete documents by `sourceId` within a collection                                               |
+| `memory_delete_collection`  | Delete an entire collection (not the default General)                                            |
+
+Soft TTL on collections is hint-only — tools never auto-delete. When ingesting, call `memory_list_collections` and ask the user which collection to use if ambiguous.
 
 ## Dev
 

package/ingest-source.js

@@ -24,11 +24,14 @@ export async function buildIngestBody(args) {
     if (!args.sourceKey?.trim() || !args.contentType?.trim()) {
         throw new Error('sourceKey and contentType are required');
     }
+    if (!args.collectionId?.trim()) {
+        throw new Error('collectionId is required. Call memory_list_collections and ask the user which Memory collection to use.');
+    }
     const base = {
         sourceKey: args.sourceKey.trim(),
         contentType: args.contentType.trim(),
         uri: args.uri,
-        collectionId: args.collectionId,
+        collectionId: args.collectionId.trim(),
         path: args.path,
     };
     if (args.path?.trim()) {

package/memory-client.js

@@ -50,6 +50,15 @@ export function createMemoryClient(config) {
         getIngest(jobId) {
             return request('GET', `/memory/ingest/${encodeURIComponent(jobId)}`);
         },
+        listCollections() {
+            return request('GET', '/memory/collections');
+        },
+        deleteBySource(params) {
+            return request('POST', '/memory/delete', params);
+        },
+        deleteCollection(collectionId) {
+            return request('DELETE', `/memory/collections/${encodeURIComponent(collectionId)}`);
+        },
     };
 }
 function extractErrorMessage(body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syndicai/stack-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local stdio MCP server for SyndicAI Stack (Memory and future tools)",
   "type": "module",
   "bin": {

package/tools.js

@@ -5,6 +5,9 @@ export const MEMORY_MCP_TOOL_NAMES = [
     'memory_search',
     'memory_ingest',
     'memory_ingest_status',
+    'memory_list_collections',
+    'memory_delete',
+    'memory_delete_collection',
 ];
 function textResult(data) {
     return {
@@ -42,8 +45,17 @@ export async function runMemorySearch(client, args) {
 }
 export async function runMemoryIngest(client, args) {
     try {
-        const body = await buildIngestBody(args);
-        const data = await client.ingest(body);
+        if (!args.collectionId?.trim()) {
+            return toolErrorResult(new Error('collectionId is required. Call memory_list_collections and ask the user which Memory collection to use.'));
+        }
+        const body = await buildIngestBody({
+            ...args,
+            collectionId: args.collectionId.trim(),
+        });
+        const data = await client.ingest({
+            ...body,
+            collectionId: args.collectionId.trim(),
+        });
         return textResult(data);
     }
     catch (err) {
@@ -62,12 +74,48 @@ export async function runMemoryIngestStatus(client, args) {
         return toolErrorResult(err);
     }
 }
+export async function runMemoryListCollections(client) {
+    try {
+        const data = await client.listCollections();
+        return textResult(data);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
+export async function runMemoryDelete(client, args) {
+    try {
+        if (!args.collectionId?.trim() || !args.sourceId?.trim()) {
+            return toolErrorResult(new Error('collectionId and sourceId are required'));
+        }
+        const data = await client.deleteBySource({
+            collectionId: args.collectionId.trim(),
+            sourceId: args.sourceId.trim(),
+        });
+        return textResult(data);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
+export async function runMemoryDeleteCollection(client, args) {
+    try {
+        if (!args.collectionId?.trim()) {
+            return toolErrorResult(new Error('collectionId is required'));
+        }
+        const data = await client.deleteCollection(args.collectionId.trim());
+        return textResult(data);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
 /** Register Memory tools. Future Stack tools can be added here. */
 export function registerStackMcpTools(server, client) {
     server.registerTool('memory_search', {
         title: 'Search Memory',
         description: 'Hybrid search over the squad Memory corpus (vector + lexical). Returns ranked chunk hits with content and scores. ' +
-            'Query embedding shares the satellite GPU with coding chat: under load embeddings are throttled (lower concurrency) so search may be slower while users are chatting — wait and retry rather than assuming Memory is down.',
+            'Query embeddings run on the stack-datalayer (CPU Granite). Optional collectionId filters to one collection; omit to search all.',
         inputSchema: {
             query: z.string().describe('Natural-language search query'),
             limit: z
@@ -82,12 +130,22 @@ export function registerStackMcpTools(server, client) {
                 .describe('Optional collection filter; omit to search all'),
         },
     }, async (args) => runMemorySearch(client, args));
+    server.registerTool('memory_list_collections', {
+        title: 'List Memory collections',
+        description: 'List Memory collections with id, name, type (library|scratch), visibility (shared|personal), ' +
+            'document/chunk stats, and soft-TTL hint fields (ttlExpiresAt, ttlExpired, cleanupHint). ' +
+            'Soft TTL never auto-deletes — use memory_delete / memory_delete_collection for cleanup. ' +
+            'Call this before memory_ingest and ask the user which collection to use when ambiguous. ' +
+            'Personal visibility is cooperative segregation only (not a security boundary).',
+        inputSchema: {},
+    }, async () => runMemoryListCollections(client));
     server.registerTool('memory_ingest', {
         title: 'Ingest into Memory',
-        description: 'Start (or resume) a Memory ingest job (chunk → embed → store). Accepts text/markdown/code only. ' +
-            'Convert PDFs/images to markdown on the client before ingest — binary PDF/image paths are rejected. ' +
-            'Prefer local `path` for files so the MCP process reads bytes and the model never sees them; or pass inline `text`. ' +
-            'Embeddings run on the stack-datalayer (CPU Granite). Poll memory_ingest_status until completed/failed. ' +
+        description: 'Start a Memory ingest job asynchronously (chunk → embed → store). Returns immediately with jobId and status ' +
+            '(usually "running"; validation failures may be "cancelled"). **Requires collectionId** — call memory_list_collections ' +
+            'first and ask the user which collection to use when ambiguous. Accepts text/markdown/code only — convert PDFs/images ' +
+            'to markdown on the client first. Prefer local `path` so file bytes never enter the model context; or pass inline `text`. ' +
+            'Embeddings run on the stack-datalayer (CPU Granite). Poll memory_ingest_status with the jobId until completed/failed. ' +
             'Do not open a second ingest for the same sourceKey while a non-terminal job exists.',
         inputSchema: {
             sourceKey: z
@@ -105,15 +163,37 @@ export function registerStackMcpTools(server, client) {
                 .optional()
                 .describe('Plain text / markdown / source content'),
             uri: z.string().optional().describe('Optional source URI metadata'),
-            collectionId: z.string().optional().describe('Optional collection id'),
+            collectionId: z
+                .string()
+                .describe('Required Memory collection id. List with memory_list_collections and ask the user which to use.'),
         },
     }, async (args) => runMemoryIngest(client, args));
     server.registerTool('memory_ingest_status', {
         title: 'Ingest job status',
-        description: 'Fetch status and checkpoint for a Memory ingest job. Typical statuses: pending/running, paused (legacy), completed, failed. ' +
-            'Do not create a new ingest for the same sourceKey while a non-terminal job exists.',
+        description: 'Poll status and checkpoint for a Memory ingest job started via memory_ingest. ' +
+            'Statuses: running (in progress), completed, failed, cancelled. Optional legacy: paused. ' +
+            'Keep polling the same jobId until completed/failed; do not start a second ingest for the same sourceKey while open.',
         inputSchema: {
             jobId: z.string().describe('Ingest job id from memory_ingest'),
         },
     }, async (args) => runMemoryIngestStatus(client, args));
+    server.registerTool('memory_delete', {
+        title: 'Delete Memory by source',
+        description: 'Delete documents (and their chunks) for a sourceId within a Memory collection. ' +
+            'Explicit cleanup only — soft TTL does not auto-delete.',
+        inputSchema: {
+            collectionId: z.string().describe('Memory collection id'),
+            sourceId: z
+                .string()
+                .describe('Source id / sourceKey previously used for ingest'),
+        },
+    }, async (args) => runMemoryDelete(client, args));
+    server.registerTool('memory_delete_collection', {
+        title: 'Delete Memory collection',
+        description: 'Delete an entire Memory collection and all of its documents/chunks. ' +
+            'Cannot delete the default General collection. Explicit cleanup only — soft TTL does not auto-delete.',
+        inputSchema: {
+            collectionId: z.string().describe('Memory collection id to delete'),
+        },
+    }, async (args) => runMemoryDeleteCollection(client, args));
 }