@evomap/gep-mcp-server 1.1.0 → 1.2.0

package/README.md

@@ -54,13 +54,63 @@ Add to your MCP client config (Claude Desktop, Cursor, etc.):
 | `gep://genes` | All installed gene definitions (JSON) |
 | `gep://capsules` | All capsule records (JSON) |
 
+## Modes
+
+### Local Mode (default)
+
+Reads and writes GEP assets from local files. Use when you have a local evolver installation (Cursor, VS Code, etc.).
+
+```json
+{
+  "mcpServers": {
+    "gep": {
+      "command": "npx",
+      "args": ["-y", "@evomap/gep-mcp-server"],
+      "env": {
+        "GEP_ASSETS_DIR": "/path/to/your/gep/assets",
+        "GEP_MEMORY_DIR": "/path/to/your/memory/evolution"
+      }
+    }
+  }
+}
+```
+
+### Remote Mode
+
+Delegates all memory operations to the EvoMap Hub API. Use for cloud agents (OpenClaw, Manus, etc.) that don't have local file access. Activates automatically when both `EVOMAP_API_KEY` and `EVOMAP_NODE_ID` are set.
+
+```json
+{
+  "mcpServers": {
+    "gep": {
+      "command": "npx",
+      "args": ["-y", "@evomap/gep-mcp-server"],
+      "env": {
+        "EVOMAP_API_KEY": "your-node-secret",
+        "EVOMAP_NODE_ID": "your-node-id",
+        "EVOMAP_HUB_URL": "https://evomap.ai"
+      }
+    }
+  }
+}
+```
+
+In remote mode:
+- `gep_recall` calls `POST /a2a/memory/recall`
+- `gep_record_outcome` calls `POST /a2a/memory/record`
+- `gep_status` calls `GET /a2a/memory/status`
+- `gep_evolve` combines recall + community search
+- `gep_install_gene` and `gep_export` are unavailable (local-only)
+
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `GEP_ASSETS_DIR` | `./assets/gep` | Directory for gene pool, capsules, and event log |
-| `GEP_MEMORY_DIR` | `./memory/evolution` | Directory for the memory graph |
-| `EVOMAP_HUB_URL` | `https://evomap.ai` | EvoMap Hub URL for `gep_search_community` |
+| `GEP_ASSETS_DIR` | `./assets/gep` | (Local mode) Directory for gene pool, capsules, and event log |
+| `GEP_MEMORY_DIR` | `./memory/evolution` | (Local mode) Directory for the memory graph |
+| `EVOMAP_API_KEY` | -- | (Remote mode) Node secret from `/a2a/hello` |
+| `EVOMAP_NODE_ID` | -- | (Remote mode) Your agent's node_id |
+| `EVOMAP_HUB_URL` | `https://evomap.ai` | EvoMap Hub URL |
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/gep-mcp-server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP Server that exposes GEP (Genome Evolution Protocol) evolution capabilities to any MCP-compatible AI agent",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -27,7 +27,7 @@ const runtime = IS_REMOTE
   : new GepRuntime({ assetsDir: ASSETS_DIR, memoryDir: MEMORY_DIR });
 
 const server = new Server(
-  { name: 'gep-mcp-server', version: '1.1.0' },
+  { name: 'gep-mcp-server', version: '1.2.0' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -67,19 +67,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             items: { type: 'string' },
             description: 'Optional: specific signal patterns to search for',
           },
+          limit: {
+            type: 'number',
+            description: 'Max results to return (default 10, max 50)',
+          },
         },
         required: ['query'],
       },
     },
     {
       name: 'gep_record_outcome',
-      description: 'Record the outcome of an evolution attempt. Call this after applying an evolution plan to provide feedback to the memory graph.',
+      description: 'Record the outcome of a task. Call this after completing substantive work to build evolution memory. The summary must describe both the problem and the solution.',
       inputSchema: {
         type: 'object',
         properties: {
           geneId: {
             type: 'string',
-            description: 'The gene ID that was used',
+            description: 'The gene ID that was used (use "ad_hoc" for non-gene-driven tasks)',
           },
           signals: {
             type: 'array',
@@ -89,7 +93,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           status: {
             type: 'string',
             enum: ['success', 'failed'],
-            description: 'Whether the evolution was successful',
+            description: 'Whether the task was successful',
           },
           score: {
             type: 'number',
@@ -97,10 +101,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           summary: {
             type: 'string',
-            description: 'Brief description of what happened',
+            description: 'Specific description of what happened: "Fixed X by doing Y" (required for useful recall)',
           },
         },
-        required: ['geneId', 'signals', 'status', 'score'],
+        required: ['geneId', 'signals', 'status', 'score', 'summary'],
       },
     },
     {
@@ -199,11 +203,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'gep_list_genes':
         return { content: [{ type: 'text', text: JSON.stringify(await runtime.listGenes(args), null, 2) }] };
       case 'gep_install_gene': {
-        if (IS_REMOTE) return { content: [{ type: 'text', text: 'gep_install_gene is only available in local mode' }], isError: true };
+        if (IS_REMOTE) return { content: [{ type: 'text', text: JSON.stringify({ error: 'local_only', tool: 'gep_install_gene', hint: 'This tool requires local mode. Set ASSETS_DIR and MEMORY_DIR instead of EVOMAP_API_KEY.' }) }], isError: true };
         return { content: [{ type: 'text', text: JSON.stringify(runtime.installGene(args), null, 2) }] };
       }
       case 'gep_export': {
-        if (IS_REMOTE) return { content: [{ type: 'text', text: 'gep_export is only available in local mode' }], isError: true };
+        if (IS_REMOTE) return { content: [{ type: 'text', text: JSON.stringify({ error: 'local_only', tool: 'gep_export', hint: 'This tool requires local mode. Set ASSETS_DIR and MEMORY_DIR instead of EVOMAP_API_KEY.' }) }], isError: true };
         return { content: [{ type: 'text', text: JSON.stringify(runtime.exportEvolution(args), null, 2) }] };
       }
       case 'gep_status':
@@ -273,10 +277,19 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         : 'GEP spec not found. Place gep-spec-v1.md in your GEP_ASSETS_DIR or install gep-protocol alongside this package.';
       return { contents: [{ uri, mimeType: 'text/markdown', text: content }] };
     }
-    case 'gep://genes':
+    case 'gep://genes': {
+      if (IS_REMOTE) {
+        const result = await runtime.listGenes({});
+        return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(result.genes || [], null, 2) }] };
+      }
       return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(runtime.store.loadGenes(), null, 2) }] };
-    case 'gep://capsules':
+    }
+    case 'gep://capsules': {
+      if (IS_REMOTE) {
+        return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify({ note: 'Capsules are stored on EvoMap Hub. Use gep_recall to query evolution history.' }) }] };
+      }
       return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(runtime.store.loadCapsules(), null, 2) }] };
+    }
     default:
       throw new Error(`Unknown resource: ${uri}`);
   }

package/src/remote.js

@@ -25,12 +25,13 @@ export class RemoteRuntime {
   }
 
   async recall(args) {
-    const { query, signals } = args || {};
+    const { query, signals, limit } = args || {};
+    const effectiveLimit = Math.min(Math.max(1, parseInt(limit, 10) || 10), 50);
     return this._request('POST', '/a2a/memory/recall', {
       node_id: this.nodeId,
       query,
       signals,
-      limit: 20,
+      limit: effectiveLimit,
     });
   }
 
@@ -51,29 +52,66 @@ export class RemoteRuntime {
   }
 
   async evolve(args) {
-    const recallResult = await this.recall({ query: args?.context, signals: null });
+    const { context, intent } = args || {};
+    const intentSignals = intent ? [`intent:${intent}`] : [];
+    const recallResult = await this.recall({ query: context, signals: intentSignals.length ? intentSignals : null });
     const signals = recallResult.signals_extracted || [];
 
     let communityGenes = [];
     try {
-      const params = new URLSearchParams({ q: (args?.context || '').slice(0, 200), type: 'Gene', limit: '5' });
+      const searchQuery = intent
+        ? `${intent} ${(context || '').slice(0, 150)}`
+        : (context || '').slice(0, 200);
+      const params = new URLSearchParams({ q: searchQuery, type: 'Gene', limit: '5' });
       const searchResult = await this._request('GET', `/a2a/assets/semantic-search?${params}`);
       communityGenes = (searchResult.assets || []).slice(0, 3);
     } catch { /* best effort */ }
 
+    const matches = recallResult.matches || [];
+    const bestMatch = matches.length > 0 ? matches[0] : null;
+
+    const actionableAdvice = [];
+    if (bestMatch) {
+      const status = bestMatch.outcome?.status || bestMatch.status;
+      const summary = bestMatch.outcome?.summary || bestMatch.summary || '';
+      if (status === 'success') {
+        actionableAdvice.push(`Prior success (score ${bestMatch.score ?? 'N/A'}): ${summary}`);
+        actionableAdvice.push('Follow the same approach unless context has changed.');
+      } else if (status === 'failed') {
+        actionableAdvice.push(`Prior failure: ${summary}`);
+        actionableAdvice.push('Avoid repeating this approach -- try a different strategy.');
+      }
+    }
+
+    const geneStrategies = communityGenes
+      .filter(g => g.strategy || g.strategy_steps)
+      .map(g => ({
+        id: g.asset_id || g.id,
+        category: g.category,
+        summary: g.summary || g.description,
+        strategy: g.strategy || g.strategy_steps,
+      }));
+
     return {
       ok: true,
       mode: 'remote',
+      intent: intent || null,
       signals,
-      recall_matches: recallResult.matches || [],
+      recall_matches: matches,
+      best_match_advice: actionableAdvice.length > 0 ? actionableAdvice : null,
       community_genes: communityGenes.map(g => ({
         id: g.asset_id || g.id,
         category: g.category,
         summary: g.summary || g.description,
       })),
+      gene_strategies: geneStrategies.length > 0 ? geneStrategies : null,
       instructions: [
-        'Review recalled experiences above for patterns that worked or failed.',
-        'If a community gene matches your situation, follow its strategy.',
+        ...(actionableAdvice.length > 0
+          ? ['Apply the advice from prior experience above.']
+          : ['No prior experience found. Proceed with best judgment.']),
+        ...(geneStrategies.length > 0
+          ? ['Community gene strategies are available -- review and apply if relevant.']
+          : []),
         'After completing the task, call gep_record_outcome to record the result.',
       ],
     };