@jungjaehoon/mama-server 1.0.0

package/src/server.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+/**
+ * MAMA MCP Server
+ *
+ * Memory-Augmented MCP Assistant - Standalone MCP Server
+ *
+ * This server provides MCP tools for decision tracking, semantic search,
+ * and decision graph navigation across Claude Code and Claude Desktop.
+ *
+ * Architecture:
+ * - Stdio transport (standard MCP pattern)
+ * - SQLite + sqlite-vec for decision storage
+ * - Transformers.js for local embeddings
+ * - No network dependencies (100% local)
+ *
+ * Usage:
+ *   node src/server.js                 # Direct execution
+ *   mama-server                        # Via bin (npm install -g)
+ *   npx @jungjaehoon/mama-server           # Via npx
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+
+// Import MAMA tools
+const { saveDecisionTool } = require('./tools/save-decision.js');
+const { recallDecisionTool } = require('./tools/recall-decision.js');
+const { suggestDecisionTool } = require('./tools/suggest-decision.js');
+const { listDecisionsTool } = require('./tools/list-decisions.js');
+const { updateOutcomeTool } = require('./tools/update-outcome.js');
+const { saveCheckpointTool, loadCheckpointTool } = require('./tools/checkpoint-tools.js');
+
+// Import core modules
+const { initDB } = require('./mama/db-manager.js');
+
+/**
+ * MAMA MCP Server Class
+ */
+class MAMAServer {
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'mama-server',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  setupHandlers() {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'save_decision',
+          description: 'Save a decision or insight to MAMA\'s memory for future reference.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              topic: {
+                type: 'string',
+                description: 'Decision topic identifier (e.g., \'auth_strategy\'). Use lowercase with underscores.',
+              },
+              decision: {
+                type: 'string',
+                description: 'The decision made (e.g., \'Use JWT with refresh tokens\').',
+              },
+              reasoning: {
+                type: 'string',
+                description: 'Why this decision was made. REQUIRED - explain the context and rationale.',
+              },
+              confidence: {
+                type: 'number',
+                description: 'Confidence score 0.0-1.0. Default: 0.5',
+                minimum: 0,
+                maximum: 1,
+              },
+              type: {
+                type: 'string',
+                enum: ['user_decision', 'assistant_insight'],
+                description: 'Decision type. Default: \'user_decision\'',
+              },
+              outcome: {
+                type: 'string',
+                enum: ['pending', 'success', 'failure', 'partial', 'superseded'],
+                description: 'Outcome status. Default: \'pending\'',
+              },
+            },
+            required: ['topic', 'decision', 'reasoning'],
+          },
+        },
+        {
+          name: 'recall_decision',
+          description: 'Recall full decision history for a specific topic.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              topic: {
+                type: 'string',
+                description: 'Decision topic to recall',
+              },
+            },
+            required: ['topic'],
+          },
+        },
+        {
+          name: 'suggest_decision',
+          description: 'Auto-suggest relevant past decisions based on user question.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              userQuestion: {
+                type: 'string',
+                description: 'User\'s question or intent',
+              },
+              recencyWeight: {
+                type: 'number',
+                description: 'Weight for recency (0-1). Default: 0.3',
+                minimum: 0,
+                maximum: 1,
+              },
+            },
+            required: ['userQuestion'],
+          },
+        },
+        {
+          name: 'list_decisions',
+          description: 'List recent decisions with optional limit',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              limit: {
+                type: 'number',
+                description: 'Maximum number of decisions (default: 10)',
+              },
+            },
+          },
+        },
+        {
+          name: 'update_outcome',
+          description: 'Update the outcome status of an existing decision',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              topic: {
+                type: 'string',
+                description: 'Decision topic to update',
+              },
+              outcome: {
+                type: 'string',
+                enum: ['pending', 'success', 'failure', 'partial', 'superseded'],
+                description: 'New outcome status',
+              },
+            },
+            required: ['topic', 'outcome'],
+          },
+        },
+        {
+          name: 'save_checkpoint',
+          description: 'Save the current session state (checkpoint) to MAMA memory. Use this when ending a session or reaching a major milestone so work can be resumed later.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              summary: {
+                type: 'string',
+                description: 'Summary of the current session state, what was accomplished, and what is pending.',
+              },
+              open_files: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of currently relevant or open files.',
+              },
+              next_steps: {
+                type: 'string',
+                description: 'Clear instructions for the next session on what to do next.',
+              },
+            },
+            required: ['summary'],
+          },
+        },
+        {
+          name: 'load_checkpoint',
+          description: 'Load the latest active session checkpoint. Use this at the start of a new session to resume work seamlessly.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+      ],
+    }));
+
+    // Handle tool execution
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        let result;
+
+        switch (name) {
+          case 'save_decision':
+            result = await saveDecisionTool.handler(args);
+            break;
+          case 'recall_decision':
+            result = await recallDecisionTool.handler(args);
+            break;
+          case 'suggest_decision':
+            result = await suggestDecisionTool.handler(args);
+            break;
+          case 'list_decisions':
+            result = await listDecisionsTool.handler(args);
+            break;
+          case 'update_outcome':
+            result = await updateOutcomeTool.handler(args);
+            break;
+          case 'save_checkpoint':
+            result = await saveCheckpointTool.handler(args);
+            break;
+          case 'load_checkpoint':
+            result = await loadCheckpointTool.handler(args);
+            break;
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        console.error('[MAMA MCP] Tool execution error:', error);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  async start() {
+    try {
+      // Initialize database
+      console.error('[MAMA MCP] Initializing database...');
+      await initDB();
+      console.error('[MAMA MCP] Database initialized');
+
+      // Start server with stdio transport
+      const transport = new StdioServerTransport();
+      await this.server.connect(transport);
+
+      // Log to stderr (stdout is for MCP JSON-RPC)
+      console.error('[MAMA MCP] Server started successfully');
+      console.error('[MAMA MCP] Listening on stdio transport');
+      console.error('[MAMA MCP] Ready to accept connections');
+    } catch (error) {
+      console.error('[MAMA MCP] Failed to start server:', error);
+      process.exit(1);
+    }
+  }
+}
+
+// Start server if run directly
+if (require.main === module) {
+  const server = new MAMAServer();
+  server.start().catch((error) => {
+    console.error('[MAMA MCP] Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { MAMAServer };

package/src/tools/checkpoint-tools.js

@@ -0,0 +1,76 @@
+const { saveCheckpoint, loadCheckpoint } = require('../mama/mama-api');
+
+const saveCheckpointTool = {
+  name: 'save_checkpoint',
+  description: 'Save the current session state (checkpoint) to MAMA memory. Use this when ending a session or reaching a major milestone so work can be resumed later.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      summary: {
+        type: 'string',
+        description: 'Summary of the current session state, what was accomplished, and what is pending.',
+      },
+      open_files: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'List of currently relevant or open files.',
+      },
+      next_steps: {
+        type: 'string',
+        description: 'Clear instructions for the next session on what to do next.',
+      },
+    },
+    required: ['summary'],
+  },
+  handler: async (args) => {
+    const { summary, open_files, next_steps } = args;
+    const id = await saveCheckpoint(summary, open_files, next_steps);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `✅ Checkpoint saved (ID: ${id})\nSummary: ${summary}`,
+        },
+      ],
+    };
+  },
+};
+
+const loadCheckpointTool = {
+  name: 'load_checkpoint',
+  description: 'Load the latest active session checkpoint. Use this at the start of a new session to resume work seamlessly.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+  handler: async () => {
+    const checkpoint = await loadCheckpoint();
+    if (!checkpoint) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'ℹ️ No active checkpoint found.',
+          },
+        ],
+      };
+    }
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `🔄 Resuming Session (from ${new Date(checkpoint.timestamp).toLocaleString()})\n\n` +
+                `📝 Summary: ${checkpoint.summary}\n` +
+                `📂 Files: ${JSON.stringify(checkpoint.open_files)}\n` +
+                `👉 Next Steps: ${checkpoint.next_steps || 'None'}`,
+        },
+      ],
+    };
+  },
+};
+
+module.exports = {
+  saveCheckpointTool,
+  loadCheckpointTool,
+};

package/src/tools/index.js

@@ -0,0 +1,54 @@
+/**
+ * MAMA Memory Tools
+ *
+ * Story M1.3: MCP Tool Surface Port
+ * Story M1.5: update_outcome tool added
+ * MCP tool wrappers for MAMA's memory system
+ *
+ * Tools:
+ * - save_decision: Save decisions/insights to memory ✅
+ * - recall_decision: Retrieve decision history by topic ✅
+ * - suggest_decision: Semantic search for relevant decisions ✅
+ * - list_decisions: List recent decisions chronologically ✅
+ * - update_outcome: Update decision outcome ✅
+ *
+ * @module tools
+ */
+
+const { saveDecisionTool } = require('./save-decision.js');
+const { recallDecisionTool } = require('./recall-decision.js');
+const { suggestDecisionTool } = require('./suggest-decision.js');
+const { listDecisionsTool } = require('./list-decisions.js');
+const { updateOutcomeTool } = require('./update-outcome.js');
+const { saveCheckpointTool, loadCheckpointTool } = require('./checkpoint-tools.js');
+
+/**
+ * Create all MAMA memory tools
+ *
+ * Database location: ~/.claude/mama-memory.db (or MAMA_DB_PATH env var)
+ *
+ * @returns Object with tool definitions
+ */
+function createMemoryTools() {
+  return {
+    save_decision: saveDecisionTool,
+    recall_decision: recallDecisionTool,
+    suggest_decision: suggestDecisionTool,
+    list_decisions: listDecisionsTool,
+    update_outcome: updateOutcomeTool,
+    save_checkpoint: saveCheckpointTool,
+    load_checkpoint: loadCheckpointTool,
+  };
+}
+
+// Export individual tool creators for testing
+module.exports = {
+  createMemoryTools,
+  saveDecisionTool,
+  recallDecisionTool,
+  suggestDecisionTool,
+  listDecisionsTool,
+  updateOutcomeTool,
+  saveCheckpointTool,
+  loadCheckpointTool,
+};

package/src/tools/list-decisions.js

@@ -0,0 +1,76 @@
+/**
+ * MCP Tool: list_decisions
+ *
+ * Lists recent decisions in chronological order.
+ * Returns formatted list with time, type, topic, preview, confidence, and status.
+ *
+ * Flow:
+ * 1. User (via Claude Desktop): "Show me recent decisions"
+ * 2. Claude: Calls list_decisions MCP tool
+ * 3. Tool: Validates input, calls mama.list()
+ * 4. mama.list(): Queries recent decisions + formats as markdown
+ * 5. Tool: Returns formatted markdown response
+ *
+ * @module list-decisions
+ */
+
+const path = require('path');
+
+// Import MAMA API from core directory
+const mama = require('../mama/mama-api.js');
+
+/**
+ * List decisions tool definition
+ */
+const listDecisionsTool = {
+  name: 'list_decisions',
+  description:
+    'List recent decisions in chronological order. Returns formatted list showing time, type (user/assistant), topic, preview, confidence, and status. Use this to see recent activity or find decisions by browsing.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Maximum number of decisions to return (default: 20, max: 100)',
+        minimum: 1,
+        maximum: 100,
+      },
+    },
+    required: [],
+  },
+
+  async handler(params, context) {
+    const { limit = 20 } = params || {};
+
+    try {
+      // Validation: Limit range check
+      if (limit < 1 || limit > 100) {
+        return {
+          success: false,
+          message: '❌ Validation error: Limit must be between 1 and 100',
+        };
+      }
+
+      // Call MAMA API with markdown format for human display
+      // mama.list() defaults to JSON (LLM-first), but we need markdown for user display
+      const list = await mama.list({ limit, format: 'markdown' });
+
+      // Return success response with formatted list
+      return {
+        success: true,
+        list,
+        message: list, // For backward compatibility with MCP response format
+      };
+    } catch (error) {
+      // Error handling: Return user-friendly message
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+
+      return {
+        success: false,
+        message: `❌ Failed to list decisions: ${errorMessage}`,
+      };
+    }
+  },
+};
+
+module.exports = { listDecisionsTool };

package/src/tools/recall-decision.js

@@ -0,0 +1,75 @@
+/**
+ * MCP Tool: recall_decision
+ *
+ * Story M1.3: MCP Tool - recall_decision (ported from mcp-server)
+ * Priority: P1 (Core Feature)
+ *
+ * Recalls full decision history for a specific topic.
+ * This is a wrapper around the existing mama.recall() API.
+ *
+ * Flow:
+ * 1. User (via Claude Desktop): "Recall my decision about auth strategy"
+ * 2. Claude: Calls recall_decision MCP tool
+ * 3. Tool: Validates input, calls mama.recall()
+ * 4. mama.recall(): Queries decision history + formats as markdown
+ * 5. Tool: Returns formatted markdown response
+ *
+ * @module recall-decision
+ */
+
+const mama = require('../mama/mama-api.js');
+
+/**
+ * Recall decision tool definition
+ */
+const recallDecisionTool = {
+  name: 'recall_decision',
+  description:
+    'Recall full decision history for a specific topic. Returns all past decisions on this topic in chronological order with reasoning, confidence, and outcomes. Use this when you need to review previous decisions, understand decision evolution, or check current position on a topic.\n\n⚡ GRAPH TRAVERSAL: When the same topic is reused across multiple decisions, this tool automatically shows the decision evolution chain (supersedes graph), enabling Learn/Unlearn/Relearn workflows.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: {
+        type: 'string',
+        description:
+          "Decision topic to recall (e.g., 'auth_strategy', 'mesh_detail_choice'). Use the EXACT SAME topic name used in save_decision to see full decision evolution graph. Different topic names will show separate, disconnected decisions.",
+      },
+    },
+    required: ['topic'],
+  },
+
+  async handler(params, context) {
+    const { topic } = params || {};
+
+    try {
+      // Validation: Non-empty string check
+      if (!topic || typeof topic !== 'string' || topic.trim() === '') {
+        return {
+          success: false,
+          message: '❌ Validation error: Topic must be a non-empty string',
+        };
+      }
+
+      // Call MAMA API with markdown format for human display
+      // mama.recall() defaults to JSON (LLM-first), but we need markdown for user display
+      const history = await mama.recall(topic, { format: 'markdown' });
+
+      // Return success response with formatted history
+      return {
+        success: true,
+        history,
+        message: history, // For backward compatibility with MCP response format
+      };
+    } catch (error) {
+      // Error handling: Return user-friendly message
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+
+      return {
+        success: false,
+        message: `❌ Failed to recall decisions: ${errorMessage}`,
+      };
+    }
+  },
+};
+
+module.exports = { recallDecisionTool };

package/src/tools/save-decision.js

@@ -0,0 +1,113 @@
+/**
+ * MCP Tool: save_decision
+ *
+ * Story M1.3: MCP Tool - save_decision (ported from mcp-server)
+ * Priority: P1 (Core Feature)
+ *
+ * Saves decisions and insights to MAMA's memory for future reference.
+ *
+ * @module save-decision
+ */
+
+const mama = require('../mama/mama-api.js');
+
+/**
+ * Save decision tool definition
+ */
+const saveDecisionTool = {
+  name: 'save_decision',
+  description:
+    "Save a decision or insight to MAMA's memory for future reference. Use this when the user explicitly wants to remember something important (e.g., architectural decisions, parameter choices, lessons learned). The decision will be stored with semantic embeddings for later retrieval.\n\n⚡ IMPORTANT - Graph Connectivity: Reuse the SAME topic name for related decisions to create decision graphs (supersedes/refines/contradicts edges). Example: Use 'auth_strategy' for all authentication decisions, not 'auth_strategy_v1', 'auth_strategy_v2'. This enables Learn/Unlearn/Relearn workflows.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: {
+        type: 'string',
+        description:
+          "Decision topic identifier (e.g., 'auth_strategy', 'mesh_detail_choice'). Use lowercase with underscores. Max 200 characters.\n\n⚡ REUSE SAME TOPIC for related decisions to create supersedes edges.",
+      },
+      decision: {
+        type: 'string',
+        description: "The decision made (e.g., 'Use JWT with refresh tokens'). Max 2000 characters.",
+      },
+      reasoning: {
+        type: 'string',
+        description:
+          'Why this decision was made. This is REQUIRED - never leave empty. Explain the context, alternatives considered, and rationale. IMPORTANT: Use English for better semantic search and relationship detection (e.g., use "instead of", "contrary to", "replaces" for conflicting decisions). Max 5000 characters.',
+      },
+      confidence: {
+        type: 'number',
+        description:
+          'Confidence score 0.0-1.0. Use 0.9 for high confidence, 0.8 for medium, 0.5 for experimental. Default: 0.5',
+        minimum: 0,
+        maximum: 1,
+      },
+      type: {
+        type: 'string',
+        enum: ['user_decision', 'assistant_insight'],
+        description: "'user_decision' if user explicitly decided, 'assistant_insight' if this is Claude's suggestion. Default: 'user_decision'",
+      },
+      outcome: {
+        type: 'string',
+        enum: ['pending', 'success', 'failure', 'partial', 'superseded'],
+        description:
+          "Decision outcome status. Use 'pending' for new decisions (default), 'success' when confirmed working, 'failure' when approach failed.",
+      },
+    },
+    required: ['topic', 'decision', 'reasoning'],
+  },
+
+  async handler(params, context) {
+    const {
+      topic,
+      decision,
+      reasoning,
+      confidence = 0.5,
+      type = 'user_decision',
+      outcome = 'pending',
+    } = params || {};
+
+    try {
+      // Validation
+      if (!topic || !decision || !reasoning) {
+        return {
+          success: false,
+          message: '❌ Validation error: topic, decision, and reasoning are required',
+        };
+      }
+
+      if (topic.length > 200 || decision.length > 2000 || reasoning.length > 5000) {
+        return {
+          success: false,
+          message: '❌ Validation error: Field length exceeded (topic≤200, decision≤2000, reasoning≤5000)',
+        };
+      }
+
+      // Call MAMA API (mama.save will handle outcome mapping to DB format)
+      const result = await mama.save({
+        topic,
+        decision,
+        reasoning,
+        confidence,
+        user_involvement: type,
+        outcome,
+      });
+
+      return {
+        success: true,
+        decision_id: result.id,
+        topic: topic,
+        message: `✅ Decision saved successfully (ID: ${result.id})`,
+        recall_command: `To recall: mama.recall('${topic}')`,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      return {
+        success: false,
+        message: `❌ Failed to save decision: ${errorMessage}`,
+      };
+    }
+  },
+};
+
+module.exports = { saveDecisionTool };