@abarcenas/ai-workflow-template 1.25.0 → 1.28.0

package/scripts/mcp-memory-server.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+/**
+ * mcp-memory-server.js — MCP server exposing memory-bank tools to OpenCode.
+ *
+ * Provides: memory_search, memory_rebuild, memory_get
+ * Uses stdio transport — OpenCode spawns this as a child process.
+ *
+ * Configuration (opencode.json):
+ *   "memory-bank": {
+ *     "type": "local",
+ *     "command": ["node", "scripts/mcp-memory-server.js"],
+ *     "enabled": true
+ *   }
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { search, rebuildIndex, incrementalUpdate, getFile, getStats } from './memory-index.js';
+
+const VALID_FILES = [
+  'activeContext', 'systemPatterns', 'techContext',
+  'productContext', 'progress', 'projectbrief',
+  'tracker-log', 'architecture-context', 'orchestrator-log',
+  'spike-vector-db-memory', 'playwright-mcp-configuration',
+];
+
+const server = new Server(
+  {
+    name: 'memory-bank',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// ── List tools ───────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'memory_search',
+      description:
+        'Semantic search across the project memory bank (activeContext, systemPatterns, progress, decisions, tasks). ' +
+        'Returns ranked chunks with source file and similarity score. ' +
+        'Use this instead of reading all memory files to save tokens.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Natural language query about project context, decisions, or status',
+          },
+          topK: {
+            type: 'number',
+            default: 5,
+            description: 'Number of results to return (1-20)',
+          },
+          sourceFile: {
+            type: 'string',
+            description: 'Optional: filter to a specific memory file (e.g., "activeContext", "systemPatterns")',
+          },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'memory_rebuild',
+      description:
+        'Full rebuild of the memory vector index from memory-bank/*.md and docs/*.md files. ' +
+        'Re-indexes every file regardless of change. ' +
+        'Use memory_update instead for faster incremental sync (only changed files). ' +
+        'The index is disposable — rebuilding is safe.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+    {
+      name: 'memory_update',
+      description:
+        'Incremental update — only re-indexes files whose content changed (SHA-256 content hash). ' +
+        'Much faster than memory_rebuild for daily use (~2 seconds vs minutes). ' +
+        'Run this after completing tasks, writing to memory-bank, or after git pull.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+    {
+      name: 'memory_get',
+      description:
+        'Read the full content of a specific memory file by name. ' +
+        'Use when you need the complete file, not just search snippets.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description: 'File ID without extension. One of: ' + VALID_FILES.join(', '),
+            enum: VALID_FILES,
+          },
+        },
+        required: ['file'],
+      },
+    },
+    {
+      name: 'memory_stats',
+      description: 'Get statistics about the memory index (vector count, file count, database size).',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+  ],
+}));
+
+// ── Handle tool calls ────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'memory_search': {
+        const results = await search(args.query, {
+          topK: args.topK || 5,
+          sourceFile: args.sourceFile || undefined,
+        });
+
+        if (results.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: 'No results found. The index may be empty. Try running memory_rebuild first.',
+            }],
+          };
+        }
+
+        const formatted = results
+          .map((r, i) =>
+            `### Result ${i + 1} (score: ${r.score})\n` +
+            `**File:** \`${r.source_file}\`\n\n${r.content}`
+          )
+          .join('\n\n---\n\n');
+
+        return {
+          content: [{ type: 'text', text: formatted }],
+        };
+      }
+
+      case 'memory_rebuild': {
+        const result = await rebuildIndex();
+        return {
+          content: [{
+            type: 'text',
+            text: `Index rebuilt successfully.\n` +
+              `- Chunks indexed: ${result.indexed}\n` +
+              `- Chunks skipped (unchanged): ${result.skipped}\n` +
+              `- Total vectors: ${result.stats.totalVectors}\n` +
+              `- Total files: ${result.stats.totalFiles}\n` +
+              `- DB size: ${result.stats.dbSize}`,
+          }],
+        };
+      }
+
+      case 'memory_update': {
+        const result = await incrementalUpdate();
+        return {
+          content: [{
+            type: 'text',
+            text: `Index updated incrementally.\n` +
+              `- Chunks re-indexed: ${result.indexed}\n` +
+              `- Chunks cached (unchanged): ${result.skipped}\n` +
+              (result.changed.length > 0
+                ? `- Changed files: ${result.changed.join(', ')}\n`
+                : '- No files changed.\n') +
+              `- Total vectors: ${(await getStats()).totalVectors}`,
+          }],
+        };
+      }
+
+      case 'memory_get': {
+        const content = getFile(args.file);
+        if (!content) {
+          return {
+            content: [{
+              type: 'text',
+              text: `File not found: ${args.file}.md. Available files: ${VALID_FILES.join(', ')}`,
+            }],
+          };
+        }
+        return {
+          content: [{ type: 'text', text: content }],
+        };
+      }
+
+      case 'memory_stats': {
+        const stats = getStats();
+        return {
+          content: [{
+            type: 'text',
+            text: `**Memory Index Stats**\n` +
+              `- Total vectors: ${stats.totalVectors}\n` +
+              `- Total files indexed: ${stats.totalFiles}\n` +
+              `- Database size: ${stats.dbSize}`,
+          }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: ${err.message}`,
+      }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start server ─────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[memory-bank-mcp] Server started via stdio transport');
+}
+
+main().catch((err) => {
+  console.error('[memory-bank-mcp] Fatal error:', err);
+  process.exit(1);
+});

package/scripts/memory-cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+/**
+ * memory-cli.js — CLI for manual memory index operations.
+ *
+ * Usage:
+ *   node scripts/memory-cli.js search "<query>" [--topK 5] [--file activeContext]
+ *   node scripts/memory-cli.js rebuild
+ *   node scripts/memory-cli.js update          (incremental)
+ *   node scripts/memory-cli.js get <fileId>
+ *   node scripts/memory-cli.js stats
+ */
+
+import { search, rebuildIndex, incrementalUpdate, getFile, getStats, closeDB } from './memory-index.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--topK' && i + 1 < argv.length) {
+      flags.topK = parseInt(argv[++i], 10);
+    } else if (argv[i] === '--file' && i + 1 < argv.length) {
+      flags.sourceFile = argv[++i];
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  return { flags, positional };
+}
+
+async function main() {
+  try {
+    switch (command) {
+      case 'search': {
+        const { flags, positional } = parseFlags(args.slice(1));
+        const query = positional.join(' ');
+        if (!query) {
+          console.error('Usage: node scripts/memory-cli.js search "<query>" [--topK 5] [--file name]');
+          process.exit(1);
+        }
+
+        const results = await search(query, {
+          topK: flags.topK || 5,
+          sourceFile: flags.sourceFile,
+        });
+
+        if (results.length === 0) {
+          console.log(JSON.stringify({ results: [], hint: 'No results. Try running "rebuild" first.' }));
+        } else {
+          console.log(JSON.stringify({ results }, null, 2));
+        }
+        break;
+      }
+
+      case 'rebuild': {
+        const result = await rebuildIndex();
+        console.log(JSON.stringify({ status: 'ok', ...result }, null, 2));
+        break;
+      }
+
+      case 'update': {
+        const result = await incrementalUpdate();
+        console.log(JSON.stringify({ status: 'ok', ...result }, null, 2));
+        break;
+      }
+
+      case 'get': {
+        const fileId = args[1];
+        if (!fileId) {
+          console.error('Usage: node scripts/memory-cli.js get <fileId>');
+          process.exit(1);
+        }
+        const content = getFile(fileId);
+        if (content) {
+          console.log(content);
+        } else {
+          console.error(`File not found: ${fileId}`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'stats': {
+        console.log(JSON.stringify(getStats(), null, 2));
+        break;
+      }
+
+      default:
+        console.error(`Usage: node scripts/memory-cli.js <search|rebuild|update|get|stats> [args...]`);
+        console.error('');
+        console.error('Commands:');
+        console.error('  search "<query>" [--topK N] [--file name]  Semantic search');
+        console.error('  rebuild                                      Full index rebuild');
+        console.error('  update                                       Incremental update');
+        console.error('  get <fileId>                                 Read a memory file');
+        console.error('  stats                                        Index statistics');
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  } finally {
+    closeDB();
+  }
+}
+
+main();