cf-memory-mcp 3.21.0 → 3.23.0

package/bin/cf-memory-mcp.js

@@ -216,7 +216,8 @@ const TOOLS_LIST = [
                 session_id_hint: { type: 'string', description: 'Resume a specific session by id (overrides repo/branch matching). Full UUID or short prefix (>=8 chars). Useful after seeing recent_handoffs.' },
                 max_age_minutes: { type: 'number', description: 'Hard cutoff: hide handoffs older than this many minutes. Without it, older handoffs surface with reduced confidence.' },
                 goal_contains: { type: 'string', description: 'Substring filter on handoff content (goal/notes/decisions). Case-insensitive. Lets agents find a specific thread by what it was about.' },
-                since: { type: 'string', description: 'Lower bound on handoff timestamp (ISO 8601). Scope resume to a time window.' }
+                since: { type: 'string', description: 'Lower bound on handoff timestamp (ISO 8601). Scope resume to a time window.' },
+                status_filter: { description: 'Restrict matches to handoffs with this status. Single string or array of strings (e.g., ["in_progress","blocked"]).' }
             }
         }
     },
@@ -695,7 +696,11 @@ class CFMemoryMCP {
                             // cfm://resume/current and recent handoffs at
                             // cfm://resume/recent for clients that prefer the
                             // resources protocol over tool calls.
-                            resources: {}
+                            resources: {},
+                            // Prompts capability exposes /resume and /list_threads
+                            // for clients (Claude Desktop, etc.) that surface
+                            // prompts as slash-commands in their UI.
+                            prompts: {}
                         },
                         serverInfo: {
                             name: 'cf-memory-mcp-simplified',
@@ -856,17 +861,147 @@ class CFMemoryMCP {
                 return;
             }
 
-            // Handle prompts/list locally (we have none)
+            // Handle prompts/list — advertise the resume + threads prompts.
+            // These let MCP clients (Claude Desktop, etc.) show a slash-
+            // command UI like /resume that injects the prior handoff into
+            // the next message without an explicit tool call.
             if (message.method === 'prompts/list') {
                 const response = {
                     jsonrpc: '2.0',
                     id: message.id,
-                    result: { prompts: [] }
+                    result: {
+                        prompts: [
+                            {
+                                name: 'resume',
+                                description: 'Insert the prior resume handoff for this repo into the chat so the agent can pick up where the last session left off.',
+                                arguments: [
+                                    { name: 'session_id', description: 'Optional: resume a specific session (full UUID or short prefix >=8 chars).', required: false },
+                                ],
+                            },
+                            {
+                                name: 'list_threads',
+                                description: 'Insert a list of recent handoffs for this repo so the user can pick a specific thread to resume.',
+                                arguments: [
+                                    { name: 'status', description: 'Optional: filter by status (in_progress, blocked, completed, abandoned).', required: false },
+                                ],
+                            },
+                        ],
+                    },
                 };
                 process.stdout.write(JSON.stringify(response) + '\n');
                 return;
             }
 
+            // Handle prompts/get — render the requested prompt with current
+            // resume state baked in.
+            if (message.method === 'prompts/get') {
+                const promptName = message.params?.name;
+                const promptArgs = message.params?.arguments || {};
+                try {
+                    if (promptName === 'resume') {
+                        const meta = this.getRepoMetadata();
+                        const args = { resume: true };
+                        if (meta.repo_path) args.repo_path = meta.repo_path;
+                        if (meta.branch) args.branch = meta.branch;
+                        if (promptArgs.session_id) args.session_id_hint = promptArgs.session_id;
+                        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+                        await this.maybeFillProjectId(fake);
+                        if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+                        const bootstrap = await this.makeRequest({
+                            jsonrpc: '2.0',
+                            id: `prompt-resume-${Date.now()}`,
+                            method: 'tools/call',
+                            params: { name: 'get_context_bootstrap', arguments: args },
+                        });
+                        const text = bootstrap?.result?.content?.[0]?.text || '{}';
+                        const payload = JSON.parse(text);
+                        const body = payload.resume_prompt
+                            || (payload.empty_hint || 'No prior resume handoff for this context.');
+                        const response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            result: {
+                                description: `Resume context for ${meta.repo_path || 'this cwd'}`,
+                                messages: [
+                                    { role: 'user', content: { type: 'text', text: body } },
+                                ],
+                            },
+                        };
+                        process.stdout.write(JSON.stringify(response) + '\n');
+                        return;
+                    }
+                    if (promptName === 'list_threads') {
+                        const meta = this.getRepoMetadata();
+                        const args = { resume: true };
+                        if (meta.repo_path) args.repo_path = meta.repo_path;
+                        if (meta.branch) args.branch = meta.branch;
+                        if (promptArgs.status) args.status_filter = promptArgs.status;
+                        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+                        await this.maybeFillProjectId(fake);
+                        if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+                        const bootstrap = await this.makeRequest({
+                            jsonrpc: '2.0',
+                            id: `prompt-list-${Date.now()}`,
+                            method: 'tools/call',
+                            params: { name: 'get_context_bootstrap', arguments: args },
+                        });
+                        const text = bootstrap?.result?.content?.[0]?.text || '{}';
+                        const payload = JSON.parse(text);
+                        const list = Array.isArray(payload.recent_handoffs) ? payload.recent_handoffs : [];
+                        const fmtAge = (iso) => {
+                            if (!iso) return '?';
+                            const min = Math.round((Date.now() - new Date(iso).getTime()) / 60000);
+                            if (min < 60) return `${min}m`;
+                            if (min < 1440) return `${Math.round(min/60)}h`;
+                            return `${Math.round(min/1440)}d`;
+                        };
+                        const lines = ['## Recent handoffs for this repo', ''];
+                        if (list.length === 0) {
+                            lines.push(payload.empty_hint || '(no handoffs)');
+                        } else {
+                            for (const h of list) {
+                                const shortId = (h.session_id || '').slice(0, 8);
+                                const age = fmtAge(h.ended_at || h.started_at);
+                                lines.push(`- \`${shortId}\` [${h.status || '?'}] ${age} ago — ${h.goal || '(no goal)'}`);
+                                if (h.next_step) lines.push(`  next: ${h.next_step}`);
+                            }
+                            lines.push('', 'Pick one via `/resume <id>` or call `get_context_bootstrap({resume:true, session_id_hint:"<id>"})`.');
+                        }
+                        const response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            result: {
+                                description: `Recent handoffs for ${meta.repo_path || 'this cwd'}`,
+                                messages: [
+                                    { role: 'user', content: { type: 'text', text: lines.join('\n') } },
+                                ],
+                            },
+                        };
+                        process.stdout.write(JSON.stringify(response) + '\n');
+                        return;
+                    }
+                    // Unknown prompt name
+                    const response = {
+                        jsonrpc: '2.0',
+                        id: message.id,
+                        error: {
+                            code: -32602,
+                            message: `Unknown prompt: ${promptName}. Supported: resume, list_threads`,
+                        },
+                    };
+                    process.stdout.write(JSON.stringify(response) + '\n');
+                    return;
+                } catch (err) {
+                    const response = {
+                        jsonrpc: '2.0',
+                        id: message.id,
+                        error: { code: -32603, message: `Failed to render prompt: ${err && err.message}` },
+                    };
+                    process.stdout.write(JSON.stringify(response) + '\n');
+                    return;
+                }
+            }
+
             // Handle ping locally
             if (message.method === 'ping') {
                 const response = {
@@ -3580,15 +3715,17 @@ A portable MCP (Model Context Protocol) server for AI memory storage using Cloud
 
 Usage:
   npx cf-memory-mcp                 Start the MCP server
-  npx cf-memory-mcp resume          Print the prior resume handoff for cwd (markdown)
-  npx cf-memory-mcp resume <id>     Print a specific handoff by session_id prefix
+  npx cf-memory-mcp resume [id]     Print the prior resume handoff (markdown)
   npx cf-memory-mcp list            List recent handoffs for cwd
-  npx cf-memory-mcp checkpoint      Snapshot current state to a fresh handoff (keep session open)
-  npx cf-memory-mcp checkpoint "<goal>"  Same, with an explicit goal string
+  npx cf-memory-mcp checkpoint ["<goal>"]  Snapshot current state (keep_open)
   npx cf-memory-mcp --version       Show version
   npx cf-memory-mcp --help          Show this help
   npx cf-memory-mcp --diagnose      Test connectivity and report issues
 
+Subcommand flags:
+  --json, -j                        Emit JSON instead of formatted text (resume/list/checkpoint)
+  --limit N, -n N                   For 'list': max number of handoffs (default 5, max 50)
+
 Environment Variables:
   CF_MEMORY_API_KEY=<key>           Your CF Memory API key (required)
   CF_MEMORY_BASE_URL=<url>          Override the default deployed worker
@@ -3601,6 +3738,25 @@ For more information, visit: https://github.com/johnlam90/cf-memory-mcp
     process.exit(0);
 }
 
+// Parse positional + flag args for CLI subcommands. Returns
+// { positional: string[], flags: { json: boolean, limit?: number } }.
+function parseCliArgs(rest) {
+    const positional = [];
+    const flags = { json: false };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === '--json' || a === '-j') flags.json = true;
+        else if (a === '--limit' || a === '-n') {
+            const n = parseInt(rest[++i], 10);
+            if (Number.isFinite(n) && n > 0) flags.limit = Math.min(n, 50);
+        } else if (a.startsWith('--limit=')) {
+            const n = parseInt(a.slice('--limit='.length), 10);
+            if (Number.isFinite(n) && n > 0) flags.limit = Math.min(n, 50);
+        } else positional.push(a);
+    }
+    return { positional, flags };
+}
+
 // Read-only inspection command: print the prior resume handoff to stdout.
 // Lets a human see what state is captured without involving an MCP client.
 async function runResumeCli() {
@@ -3608,6 +3764,7 @@ async function runResumeCli() {
         console.error('Error: CF_MEMORY_API_KEY environment variable is required');
         process.exit(1);
     }
+    const { positional, flags } = parseCliArgs(process.argv.slice(3));
     const server = new CFMemoryMCP();
     server.logDebug = () => {};
     server.logError = (...a) => process.stderr.write(a.join(' ') + '\n');
@@ -3617,7 +3774,7 @@ async function runResumeCli() {
         if (meta.repo_path) args.repo_path = meta.repo_path;
         if (meta.branch) args.branch = meta.branch;
         // Optional positional session_id argument.
-        const sessionArg = process.argv[3];
+        const sessionArg = positional[0];
         if (sessionArg) args.session_id_hint = sessionArg;
         const fake = { params: { name: 'retrieve_context', arguments: {} } };
         await server.maybeFillProjectId(fake);
@@ -3635,7 +3792,15 @@ async function runResumeCli() {
             process.exit(2);
         }
         const payload = JSON.parse(text);
-        if (payload.resume_handoff?.handoff) {
+        // Exit codes:
+        //   0 — handoff found and printed
+        //   3 — no handoff found (lets scripts branch: `if ! cf-memory-mcp resume; then ...`)
+        const found = !!payload.resume_handoff?.handoff;
+        if (flags.json) {
+            process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+            process.exit(found ? 0 : 3);
+        }
+        if (found) {
             if (payload.resume_prompt) {
                 process.stdout.write(payload.resume_prompt + '\n');
             } else {
@@ -3651,8 +3816,10 @@ async function runResumeCli() {
             }
             process.exit(0);
         } else {
-            process.stdout.write((payload.empty_hint || 'No resume handoff available.') + '\n');
-            process.exit(0);
+            // No handoff: print empty_hint to stderr so it doesn't pollute
+            // stdout for scripts that pipe the output.
+            process.stderr.write((payload.empty_hint || 'No resume handoff available.') + '\n');
+            process.exit(3);
         }
     } catch (err) {
         console.error('resume command failed:', err.message);
@@ -3665,6 +3832,7 @@ async function runListCli() {
         console.error('Error: CF_MEMORY_API_KEY environment variable is required');
         process.exit(1);
     }
+    const { flags } = parseCliArgs(process.argv.slice(3));
     const server = new CFMemoryMCP();
     server.logDebug = () => {};
     server.logError = (...a) => process.stderr.write(a.join(' ') + '\n');
@@ -3685,10 +3853,22 @@ async function runListCli() {
         });
         const text = response?.result?.content?.[0]?.text;
         const payload = JSON.parse(text || '{}');
-        const list = Array.isArray(payload.recent_handoffs) ? payload.recent_handoffs : [];
+        const allList = Array.isArray(payload.recent_handoffs) ? payload.recent_handoffs : [];
+        const list = flags.limit ? allList.slice(0, flags.limit) : allList;
+
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({
+                repo_path: meta.repo_path,
+                branch: meta.branch,
+                count: list.length,
+                handoffs: list,
+                empty_hint: list.length === 0 ? payload.empty_hint : undefined,
+            }, null, 2) + '\n');
+            process.exit(list.length === 0 ? 3 : 0);
+        }
         if (list.length === 0) {
-            process.stdout.write((payload.empty_hint || 'No handoffs for this context.') + '\n');
-            process.exit(0);
+            process.stderr.write((payload.empty_hint || 'No handoffs for this context.') + '\n');
+            process.exit(3);
         }
         // Render a compact table to terminal.
         process.stdout.write(`Recent handoffs for ${meta.repo_path || 'this cwd'}:\n\n`);
@@ -3721,12 +3901,13 @@ async function runCheckpointCli() {
         console.error('Error: CF_MEMORY_API_KEY environment variable is required');
         process.exit(1);
     }
+    const { positional, flags } = parseCliArgs(process.argv.slice(3));
     const server = new CFMemoryMCP();
     server.logDebug = () => {};
     server.logError = (...a) => process.stderr.write(a.join(' ') + '\n');
     try {
         // Optional positional goal argument: `cf-memory-mcp checkpoint "<goal text>"`
-        const goalArg = process.argv.slice(3).join(' ').trim();
+        const goalArg = positional.join(' ').trim();
         const meta = server.getRepoMetadata();
         // Need a session to attach the handoff to. Use or create the
         // implicit session for this cwd (creates a new one if no implicit).
@@ -3758,6 +3939,19 @@ async function runCheckpointCli() {
         });
         const text = response?.result?.content?.[0]?.text;
         const payload = JSON.parse(text || '{}');
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({
+                session_id: sessionId,
+                short_id: sessionId.slice(0, 8),
+                handoff_stored: !!payload.handoff_stored,
+                kept_open: !!payload.kept_open,
+                goal: handoff.goal,
+                repo_path: handoff.repo_path,
+                branch: handoff.branch,
+                resume_command: `npx cf-memory-mcp resume ${sessionId.slice(0, 8)}`,
+            }, null, 2) + '\n');
+            process.exit(payload.handoff_stored ? 0 : 2);
+        }
         if (payload.handoff_stored) {
             const shortId = sessionId.slice(0, 8);
             process.stdout.write(`Checkpoint saved (session ${shortId}).\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.21.0",
+	"version": "3.23.0",
 	"description": "Cloudflare-hosted MCP server for code indexing, retrieval, and assistant memory with a direct remote MCP endpoint and local stdio bridge.",
 	"main": "bin/cf-memory-mcp.js",
 	"bin": {