@jungjaehoon/mama-server 1.7.4 → 1.7.5

package/README.md

@@ -131,11 +131,17 @@ Once configured, use MAMA through your MCP client:
 - **Local-First** - All data stored on your device (~/.claude/mama-memory.db)
 - **Multilingual** - Supports English, Korean, and other languages
 - **Shared Database** - One database works across all your MCP clients
-- **HTTP Embedding Server** - Shared embedding service for fast hook execution
+- **Optional HTTP Embedding Server** - Legacy/standalone-less embedding HTTP mode (opt-in)
 
 ## HTTP Embedding Server
 
-The MCP server includes an HTTP embedding API that keeps the model loaded in memory:
+The MCP server can expose an HTTP embedding API, but this is now opt-in.
+
+- Default: `stdio` MCP only (no HTTP startup)
+- Recommended: run `@jungjaehoon/mama-os` for API/UI (`3847`) + embedding/chat (`3849`)
+- Legacy opt-in for MCP HTTP: `MAMA_MCP_START_HTTP_EMBEDDING=true`
+
+When enabled, the HTTP embedding API keeps the model loaded in memory:
 
 ```
 ┌─────────────────────────────────────────────────┐
@@ -147,7 +153,7 @@ The MCP server includes an HTTP embedding API that keeps the model loaded in mem
 │                      │                           │
 │     ┌────────────────▼────────────────┐         │
 │     │  HTTP Embedding Server          │         │
-│     │  127.0.0.1:3847                 │         │
+│     │  127.0.0.1:3849                 │         │
 │     │  Model stays loaded in memory   │         │
 │     └─────────────────────────────────┘         │
 └─────────────────────────────────────────────────┘
@@ -163,17 +169,25 @@ The MCP server includes an HTTP embedding API that keeps the model loaded in mem
 
 ### Usage Examples
 
+Enable legacy MCP-launched HTTP mode when starting MCP server:
+
+```bash
+MAMA_MCP_START_HTTP_EMBEDDING=true npx @jungjaehoon/mama-server
+```
+
+Then query the HTTP endpoints:
+
 ```bash
 # Check server health
-curl http://127.0.0.1:3847/health
+curl http://127.0.0.1:3849/health
 
 # Generate embedding
-curl -X POST http://127.0.0.1:3847/embed \
+curl -X POST http://127.0.0.1:3849/embed \
   -H "Content-Type: application/json" \
   -d '{"text": "How does authentication work?"}'
 
 # Batch embeddings
-curl -X POST http://127.0.0.1:3847/embed/batch \
+curl -X POST http://127.0.0.1:3849/embed/batch \
   -H "Content-Type: application/json" \
   -d '{"texts": ["query 1", "query 2", "query 3"]}'
 ```
@@ -182,14 +196,14 @@ curl -X POST http://127.0.0.1:3847/embed/batch \
 
 - **Fast**: ~50ms embedding requests (vs 2-9 seconds loading model each time)
 - **Shared**: Any local LLM client can use this service
-- **Automatic**: Starts with MCP server, no extra configuration needed
+- **Optional**: Enable only when you explicitly need MCP-launched HTTP mode
 - **Secure**: localhost only (127.0.0.1), no external access
 
 ## Graph Viewer
 
 Interactive visualization of your reasoning graph.
 
-**Access:** `http://localhost:3847/viewer`
+**Access:** `http://localhost:3847/viewer` (via Standalone) or `http://localhost:3849/viewer` (legacy MCP HTTP mode)
 
 **Features:**
 
@@ -200,16 +214,18 @@ Interactive visualization of your reasoning graph.
 
 ## Environment Variables
 
-| Variable         | Default                    | Description                |
-| ---------------- | -------------------------- | -------------------------- |
-| `MAMA_DB_PATH`   | `~/.claude/mama-memory.db` | SQLite database location   |
-| `MAMA_HTTP_PORT` | `3847`                     | HTTP embedding server port |
+| Variable                        | Default                    | Description                                  |
+| ------------------------------- | -------------------------- | -------------------------------------------- |
+| `MAMA_DB_PATH`                  | `~/.claude/mama-memory.db` | SQLite database location                     |
+| `MAMA_EMBEDDING_PORT`           | `3849`                     | Embedding HTTP server port                   |
+| `MAMA_HTTP_PORT`                | `3849`                     | Backward-compatible alias for embedding port |
+| `MAMA_MCP_START_HTTP_EMBEDDING` | `false`                    | Start embedding HTTP server from MCP process |
 
 ## Technical Details
 
 - **Database:** SQLite + sqlite-vec extension
 - **Embeddings:** Transformers.js (Xenova/multilingual-e5-small, 384-dim)
-- **Transport:** stdio-based MCP protocol + HTTP embedding server (port 3847)
+- **Transport:** stdio-based MCP protocol (default) + optional HTTP embedding server (port 3849)
 - **Storage:** ~/.claude/mama-memory.db (configurable via MAMA_DB_PATH)
 - **Port File:** ~/.mama-embedding-port (for client discovery)
 - **Node.js:** >= 18.0.0 required

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-server",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "description": "MAMA MCP Server - Memory-Augmented MCP Assistant for Claude Code & Desktop",
   "main": "src/server.js",
   "bin": {
@@ -40,8 +40,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@huggingface/transformers": "^3.0.0",
-    "@jungjaehoon/mama-core": "^1.0.4",
+    "@jungjaehoon/mama-core": "^1.1.1",
     "@modelcontextprotocol/sdk": "^1.0.1",
     "better-sqlite3": "^11.0.0",
     "sqlite-vec": "^0.1.0",

package/src/server.js

@@ -160,6 +160,9 @@ function validateEnvironment() {
  */
 class MAMAServer {
   constructor() {
+    this.legacyHttpEmbeddingMode = process.env.MAMA_MCP_START_HTTP_EMBEDDING === 'true';
+    this.legacyNoticeEmittedInToolResponse = false;
+
     this.server = new Server(
       {
         name: 'mama-server',
@@ -175,6 +178,13 @@ class MAMAServer {
     this.setupHandlers();
   }
 
+  getLegacyMigrationNotice() {
+    return (
+      '⚠️ Legacy MCP HTTP embedding mode is enabled via MAMA_MCP_START_HTTP_EMBEDDING=true. ' +
+      'This mode is deprecated. Recommended runtime: `mama start` (API/UI 3847, embedding 3849).'
+    );
+  }
+
   setupHandlers() {
     // List available tools - Simplified to 4 core tools (2025-11-25)
     // Design principle: LLM infers relationships from search results
@@ -184,7 +194,7 @@ class MAMAServer {
         // 1. SAVE - Unified save for decisions and checkpoints
         {
           name: 'save',
-          description: `🤝 Save a decision or checkpoint to your reasoning graph.
+          description: `${this.legacyHttpEmbeddingMode ? `${this.getLegacyMigrationNotice()}\n\n` : ''}🤝 Save a decision or checkpoint to your reasoning graph.
 
 ⚡ TRIGGERS - Call this when:
 • User says: "기억해줘", "remember", "decided", "결정했어"
@@ -423,11 +433,27 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
             throw new Error(`Unknown tool: ${name}`);
         }
 
+        const shouldInjectLegacyNotice =
+          this.legacyHttpEmbeddingMode && !this.legacyNoticeEmittedInToolResponse;
+
+        if (shouldInjectLegacyNotice) {
+          this.legacyNoticeEmittedInToolResponse = true;
+        }
+
         return {
           content: [
             {
               type: 'text',
-              text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+              text:
+                typeof result === 'string'
+                  ? result
+                  : JSON.stringify(
+                      shouldInjectLegacyNotice
+                        ? { ...result, migration_notice: this.getLegacyMigrationNotice() }
+                        : result,
+                      null,
+                      2
+                    ),
             },
           ],
         };
@@ -653,12 +679,25 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
       console.error('[MAMA MCP] Listening on stdio transport');
       console.error('[MAMA MCP] Ready to accept connections');
 
-      // Start HTTP embedding server in background (non-blocking)
-      // Architecture: Standalone owns the server with chat, MCP reuses if available
-      const embeddingPort = parseInt(
-        process.env.MAMA_HTTP_PORT || process.env.MAMA_EMBEDDING_PORT || '3847',
-        10
-      );
+      // HTTP embedding server startup is disabled by default for MCP.
+      // Architecture: Standalone should own HTTP embedding/chat services.
+      // Legacy opt-in: set MAMA_MCP_START_HTTP_EMBEDDING=true.
+      const startHttpEmbedding = process.env.MAMA_MCP_START_HTTP_EMBEDDING === 'true';
+      const rawEmbeddingPort = process.env.MAMA_EMBEDDING_PORT || process.env.MAMA_HTTP_PORT;
+      const parsedEmbeddingPort = parseInt(rawEmbeddingPort || '', 10);
+      const embeddingPort =
+        Number.isInteger(parsedEmbeddingPort) && parsedEmbeddingPort > 0
+          ? parsedEmbeddingPort
+          : 3849;
+
+      if (!startHttpEmbedding) {
+        console.error('[MAMA MCP] HTTP embedding server startup skipped (default behavior)');
+        console.error('[MAMA MCP] Use Standalone for Graph Viewer/Mobile Chat');
+        console.error(
+          '[MAMA MCP] To enable legacy MCP-launched HTTP: MAMA_MCP_START_HTTP_EMBEDDING=true'
+        );
+        return;
+      }
 
       // Check if Standalone (or another instance) already started the embedding server
       const serverAlreadyRunning = await isEmbeddingServerRunning(embeddingPort);
@@ -667,29 +706,28 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
         console.error(`[MAMA MCP] Embedding server already running on port ${embeddingPort}`);
         console.error('[MAMA MCP] Using existing server (likely started by Standalone with chat)');
         console.error(`[MAMA MCP] Graph Viewer: http://localhost:${embeddingPort}/viewer`);
-      } else {
-        console.error('[MAMA MCP] Starting HTTP embedding server in background...');
-        embeddingServer
-          .startEmbeddingServer(embeddingPort)
-          .then((httpServer) => {
-            if (httpServer) {
-              console.error(`[MAMA MCP] HTTP embedding server running on port ${embeddingPort}`);
-              console.error(`[MAMA MCP] Graph Viewer: http://localhost:${embeddingPort}/viewer`);
-              console.error('[MAMA MCP] Note: Chat disabled (start Standalone for full features)');
-              embeddingServer
-                .warmModel()
-                .catch((err) => console.error('[MAMA MCP] Model warmup error:', err.message));
-            } else {
-              console.error(
-                '[MAMA MCP] HTTP embedding server skipped (port unavailable or blocked)'
-              );
-            }
-          })
-          .catch((err) => {
-            console.error('[MAMA MCP] HTTP embedding server error:', err.message);
-            console.error('[MAMA MCP] MCP tools will continue to work without Graph Viewer');
-          });
+        return;
       }
+
+      console.error('[MAMA MCP] Starting HTTP embedding server in background (legacy opt-in)...');
+      embeddingServer
+        .startEmbeddingServer(embeddingPort)
+        .then((httpServer) => {
+          if (httpServer) {
+            console.error(`[MAMA MCP] HTTP embedding server running on port ${embeddingPort}`);
+            console.error(`[MAMA MCP] Graph Viewer: http://localhost:${embeddingPort}/viewer`);
+            console.error('[MAMA MCP] Note: Chat disabled (start Standalone for full features)');
+            embeddingServer
+              .warmModel()
+              .catch((err) => console.error('[MAMA MCP] Model warmup error:', err.message));
+          } else {
+            console.error('[MAMA MCP] HTTP embedding server skipped (port unavailable or blocked)');
+          }
+        })
+        .catch((err) => {
+          console.error('[MAMA MCP] HTTP embedding server error:', err.message);
+          console.error('[MAMA MCP] MCP tools will continue to work without Graph Viewer');
+        });
     } catch (error) {
       console.error('[MAMA MCP] Failed to start server:', error);
       process.exit(1);