cf-memory-mcp 3.19.0 → 3.21.0

package/bin/cf-memory-mcp.js

@@ -769,15 +769,25 @@ class CFMemoryMCP {
             // tools) recover prior chat state.
             if (message.method === 'resources/read') {
                 const uri = message.params?.uri;
-                if (uri === 'cfm://resume/current' || uri === 'cfm://resume/recent') {
+                const isCurrent = uri === 'cfm://resume/current';
+                const isRecent = uri === 'cfm://resume/recent';
+                // cfm://resume/session/<id-or-prefix>
+                const sessionMatch = typeof uri === 'string' && uri.startsWith('cfm://resume/session/')
+                    ? uri.slice('cfm://resume/session/'.length)
+                    : null;
+                if (isCurrent || isRecent || sessionMatch) {
                     try {
                         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;
-                        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;
+                        if (sessionMatch) {
+                            args.session_id_hint = sessionMatch;
+                        } else {
+                            if (meta.repo_path) args.repo_path = meta.repo_path;
+                            if (meta.branch) args.branch = meta.branch;
+                            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: `resource-read-${Date.now()}`,
@@ -787,7 +797,7 @@ class CFMemoryMCP {
                         const text = bootstrap?.result?.content?.[0]?.text || '{}';
                         // For cfm://resume/recent, surface only the recent_handoffs summaries.
                         let payload = text;
-                        if (uri === 'cfm://resume/recent') {
+                        if (isRecent) {
                             try {
                                 const parsed = JSON.parse(text);
                                 payload = JSON.stringify({
@@ -818,19 +828,29 @@ class CFMemoryMCP {
                     id: message.id,
                     error: {
                         code: -32602,
-                        message: `Unknown resource URI: ${uri}. Supported: cfm://resume/current, cfm://resume/recent`,
+                        message: `Unknown resource URI: ${uri}. Supported: cfm://resume/current, cfm://resume/recent, cfm://resume/session/<id-or-prefix>`,
                     },
                 };
                 process.stdout.write(JSON.stringify(response) + '\n');
                 return;
             }
 
-            // Handle resources/templates/list locally (we have none)
+            // Handle resources/templates/list — advertise the parameterized
+            // per-session resume URI so clients can discover the template.
             if (message.method === 'resources/templates/list') {
                 const response = {
                     jsonrpc: '2.0',
                     id: message.id,
-                    result: { resourceTemplates: [] }
+                    result: {
+                        resourceTemplates: [
+                            {
+                                uriTemplate: 'cfm://resume/session/{session_id}',
+                                name: 'Specific session handoff',
+                                description: 'Fetch a specific session\'s handoff by full UUID or short prefix (>=8 chars).',
+                                mimeType: 'application/json',
+                            },
+                        ],
+                    },
                 };
                 process.stdout.write(JSON.stringify(response) + '\n');
                 return;
@@ -3560,6 +3580,11 @@ 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 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 --version       Show version
   npx cf-memory-mcp --help          Show this help
   npx cf-memory-mcp --diagnose      Test connectivity and report issues
@@ -3576,6 +3601,194 @@ For more information, visit: https://github.com/johnlam90/cf-memory-mcp
     process.exit(0);
 }
 
+// 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() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    server.logError = (...a) => process.stderr.write(a.join(' ') + '\n');
+    try {
+        const meta = server.getRepoMetadata();
+        const args = { resume: true };
+        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];
+        if (sessionArg) args.session_id_hint = sessionArg;
+        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+        await server.maybeFillProjectId(fake);
+        if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+
+        const response = await server.makeRequest({
+            jsonrpc: '2.0',
+            id: `cli-resume-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'get_context_bootstrap', arguments: args },
+        });
+        const text = response?.result?.content?.[0]?.text;
+        if (!text) {
+            console.error('No response from server.');
+            process.exit(2);
+        }
+        const payload = JSON.parse(text);
+        if (payload.resume_handoff?.handoff) {
+            if (payload.resume_prompt) {
+                process.stdout.write(payload.resume_prompt + '\n');
+            } else {
+                process.stdout.write(JSON.stringify(payload.resume_handoff, null, 2) + '\n');
+            }
+            if (Array.isArray(payload.recent_handoffs) && payload.recent_handoffs.length > 1) {
+                process.stdout.write('\n---\nOther recent handoffs:\n');
+                for (const h of payload.recent_handoffs.slice(0, 4)) {
+                    const shortId = (h.session_id || '').slice(0, 8);
+                    process.stdout.write(`  ${shortId} [${h.status || '?'}] ${h.goal || ''}\n`);
+                }
+                process.stdout.write(`(Pass any short id as: npx cf-memory-mcp resume <id>)\n`);
+            }
+            process.exit(0);
+        } else {
+            process.stdout.write((payload.empty_hint || 'No resume handoff available.') + '\n');
+            process.exit(0);
+        }
+    } catch (err) {
+        console.error('resume command failed:', err.message);
+        process.exit(1);
+    }
+}
+
+async function runListCli() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    server.logError = (...a) => process.stderr.write(a.join(' ') + '\n');
+    try {
+        const meta = server.getRepoMetadata();
+        const args = { resume: true };
+        if (meta.repo_path) args.repo_path = meta.repo_path;
+        if (meta.branch) args.branch = meta.branch;
+        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+        await server.maybeFillProjectId(fake);
+        if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+
+        const response = await server.makeRequest({
+            jsonrpc: '2.0',
+            id: `cli-list-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'get_context_bootstrap', arguments: args },
+        });
+        const text = response?.result?.content?.[0]?.text;
+        const payload = JSON.parse(text || '{}');
+        const list = Array.isArray(payload.recent_handoffs) ? payload.recent_handoffs : [];
+        if (list.length === 0) {
+            process.stdout.write((payload.empty_hint || 'No handoffs for this context.') + '\n');
+            process.exit(0);
+        }
+        // Render a compact table to terminal.
+        process.stdout.write(`Recent handoffs for ${meta.repo_path || 'this cwd'}:\n\n`);
+        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`;
+        };
+        for (const h of list) {
+            const shortId = (h.session_id || '').slice(0, 8);
+            const age = fmtAge(h.ended_at || h.started_at);
+            const status = (h.status || 'unknown').padEnd(11);
+            const branch = h.branch ? `[${h.branch}] ` : '';
+            const goal = (h.goal || '(no goal)').slice(0, 80);
+            process.stdout.write(`  ${shortId}  ${status}  ${age.padStart(4)} ago  ${branch}${goal}\n`);
+            if (h.next_step) process.stdout.write(`              next: ${h.next_step.slice(0, 80)}\n`);
+        }
+        process.stdout.write(`\n(Run "npx cf-memory-mcp resume <id>" to see a specific handoff)\n`);
+        process.exit(0);
+    } catch (err) {
+        console.error('list command failed:', err.message);
+        process.exit(1);
+    }
+}
+
+async function runCheckpointCli() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    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 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).
+        const sessionId = await server.getOrCreateImplicitSession();
+        if (!sessionId) {
+            console.error('Could not create or find an implicit session for this cwd.');
+            process.exit(1);
+        }
+        // Build handoff: if agent provided a goal, use it; otherwise
+        // synthesize from bridge activity (which is likely sparse since
+        // this is a fresh process).
+        const handoff = server.synthesizeMinimalHandoff();
+        if (goalArg) handoff.goal = goalArg;
+        if (meta.repo_path) handoff.repo_path = meta.repo_path;
+        if (meta.branch) handoff.branch = meta.branch;
+        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+        await server.maybeFillProjectId(fake);
+        if (fake.params.arguments.project_id) handoff.project_id = fake.params.arguments.project_id;
+
+        const response = await server.makeRequest({
+            jsonrpc: '2.0',
+            id: `cli-checkpoint-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'end_session', arguments: {
+                session_id: sessionId,
+                keep_open: true,
+                handoff,
+            } },
+        });
+        const text = response?.result?.content?.[0]?.text;
+        const payload = JSON.parse(text || '{}');
+        if (payload.handoff_stored) {
+            const shortId = sessionId.slice(0, 8);
+            process.stdout.write(`Checkpoint saved (session ${shortId}).\n`);
+            process.stdout.write(`Goal: ${handoff.goal}\n`);
+            process.stdout.write(`To resume later: npx cf-memory-mcp resume ${shortId}\n`);
+            process.exit(0);
+        }
+        process.stdout.write('Checkpoint did not store a handoff.\n');
+        if (payload.error) process.stdout.write(`Error: ${payload.error}\n`);
+        process.exit(2);
+    } catch (err) {
+        console.error('checkpoint command failed:', err.message);
+        process.exit(1);
+    }
+}
+
+if (process.argv[2] === 'resume') {
+    runResumeCli();
+    return;
+}
+
+if (process.argv[2] === 'list') {
+    runListCli();
+    return;
+}
+
+if (process.argv[2] === 'checkpoint') {
+    runCheckpointCli();
+    return;
+}
+
 if (process.argv.includes('--diagnose')) {
     (async () => {
         console.log(`CF Memory MCP v${PACKAGE_VERSION} - Diagnostics`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.19.0",
+	"version": "3.21.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": {