@evomap/gep-mcp-server 1.0.2 → 1.2.0

package/README.md

@@ -0,0 +1,127 @@
+# @evomap/gep-mcp-server
+
+MCP Server that exposes GEP (Genome Evolution Protocol) evolution capabilities to any MCP-compatible AI agent.
+
+## Install
+
+```bash
+npm install -g @evomap/gep-mcp-server
+```
+
+Or run directly:
+
+```bash
+npx @evomap/gep-mcp-server
+```
+
+## MCP Client Configuration
+
+Add to your MCP client config (Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "gep": {
+      "command": "npx",
+      "args": ["@evomap/gep-mcp-server"],
+      "env": {
+        "GEP_ASSETS_DIR": "/path/to/your/gep/assets",
+        "GEP_MEMORY_DIR": "/path/to/your/memory/evolution"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `gep_evolve` | Trigger an evolution cycle with context and optional intent (repair/optimize/innovate) |
+| `gep_recall` | Query the memory graph for relevant past experience |
+| `gep_record_outcome` | Record the outcome of an evolution attempt |
+| `gep_list_genes` | List available evolution strategies with optional category filter |
+| `gep_install_gene` | Install a new gene from JSON definition |
+| `gep_export` | Export evolution history as a portable .gepx archive |
+| `gep_status` | Get current evolution state: gene count, capsule count, success rate |
+| `gep_search_community` | Search the EvoMap Hub for strategies published by other agents |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `gep://spec` | GEP protocol specification |
+| `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` | (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
+
+- Node.js >= 18.0.0
+
+## Related
+
+- [@evomap/gep-sdk](https://github.com/EvoMap/gep-sdk-js) -- GEP protocol SDK
+- [@evomap/evolver](https://github.com/EvoMap/evolver) -- Full self-evolution engine
+- [EvoMap](https://evomap.ai) -- Agent evolution network
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/gep-mcp-server",
-  "version": "1.0.2",
+  "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

@@ -15,15 +15,19 @@ import { existsSync, readFileSync } from 'node:fs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 import { GepRuntime } from './runtime.js';
+import { RemoteRuntime } from './remote.js';
 
 const ASSETS_DIR = process.env.GEP_ASSETS_DIR || resolve(process.cwd(), 'assets/gep');
 const MEMORY_DIR = process.env.GEP_MEMORY_DIR || resolve(process.cwd(), 'memory/evolution');
 const HUB_URL = process.env.EVOMAP_HUB_URL || 'https://evomap.ai';
 
-const runtime = new GepRuntime({ assetsDir: ASSETS_DIR, memoryDir: MEMORY_DIR });
+const IS_REMOTE = !!(process.env.EVOMAP_API_KEY && process.env.EVOMAP_NODE_ID);
+const runtime = IS_REMOTE
+  ? new RemoteRuntime({ hubUrl: HUB_URL, nodeId: process.env.EVOMAP_NODE_ID, apiKey: process.env.EVOMAP_API_KEY })
+  : new GepRuntime({ assetsDir: ASSETS_DIR, memoryDir: MEMORY_DIR });
 
 const server = new Server(
-  { name: 'gep-mcp-server', version: '1.0.2' },
+  { name: 'gep-mcp-server', version: '1.2.0' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -63,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',
@@ -85,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',
@@ -93,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'],
       },
     },
     {
@@ -187,23 +195,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (name) {
       case 'gep_evolve':
-        return { content: [{ type: 'text', text: JSON.stringify(runtime.evolve(args), null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(await runtime.evolve(args), null, 2) }] };
       case 'gep_recall':
-        return { content: [{ type: 'text', text: JSON.stringify(runtime.recall(args), null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(await runtime.recall(args), null, 2) }] };
       case 'gep_record_outcome':
-        return { content: [{ type: 'text', text: JSON.stringify(runtime.recordOutcome(args), null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(await runtime.recordOutcome(args), null, 2) }] };
       case 'gep_list_genes':
-        return { content: [{ type: 'text', text: JSON.stringify(runtime.listGenes(args), null, 2) }] };
-      case 'gep_install_gene':
+        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: 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':
+      }
+      case 'gep_export': {
+        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':
-        return { content: [{ type: 'text', text: JSON.stringify(runtime.getStatus(), null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(await runtime.getStatus(), null, 2) }] };
       case 'gep_search_community': {
         if (!args.query || typeof args.query !== 'string' || args.query.trim().length < 2) {
           return { content: [{ type: 'text', text: JSON.stringify({ error: 'query must be a string with at least 2 characters' }) }], isError: true };
         }
+        if (IS_REMOTE) {
+          const data = await runtime.searchCommunity(args);
+          return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
         const params = new URLSearchParams();
         params.set('q', args.query.trim().slice(0, 500));
         if (args.type && ['Gene', 'Capsule'].includes(args.type)) params.set('type', args.type);
@@ -261,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}`);
   }
@@ -273,7 +298,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('GEP MCP Server running on stdio');
+  console.error(`GEP MCP Server running on stdio (${IS_REMOTE ? 'remote' : 'local'} mode)`);
 }
 
 main().catch(err => {

package/src/remote.js

@@ -0,0 +1,147 @@
+const DEFAULT_HUB_URL = 'https://evomap.ai';
+const TIMEOUT_MS = 15000;
+
+export class RemoteRuntime {
+  constructor({ hubUrl, nodeId, apiKey }) {
+    this.hubUrl = (hubUrl || DEFAULT_HUB_URL).replace(/\/+$/, '');
+    this.nodeId = nodeId;
+    this.apiKey = apiKey;
+  }
+
+  async _request(method, path, body) {
+    const url = `${this.hubUrl}${path}`;
+    const headers = {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+    };
+    const opts = { method, headers, signal: AbortSignal.timeout(TIMEOUT_MS) };
+    if (body) opts.body = JSON.stringify(body);
+    const res = await fetch(url, opts);
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`Hub ${method} ${path} returned ${res.status}: ${text.slice(0, 200)}`);
+    }
+    return res.json();
+  }
+
+  async recall(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: effectiveLimit,
+    });
+  }
+
+  async recordOutcome(args) {
+    const { geneId, signals, status, score, summary } = args || {};
+    return this._request('POST', '/a2a/memory/record', {
+      node_id: this.nodeId,
+      signals,
+      gene_id: geneId,
+      status,
+      score,
+      summary,
+    });
+  }
+
+  async getStatus() {
+    return this._request('GET', `/a2a/memory/status?node_id=${encodeURIComponent(this.nodeId)}`);
+  }
+
+  async evolve(args) {
+    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 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: 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: [
+        ...(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.',
+      ],
+    };
+  }
+
+  async listGenes(args) {
+    try {
+      const params = new URLSearchParams({ q: args?.category || 'evolution strategy', type: 'Gene', limit: '20' });
+      const result = await this._request('GET', `/a2a/assets/semantic-search?${params}`);
+      return {
+        total: (result.assets || []).length,
+        source: 'hub',
+        genes: (result.assets || []).map(g => ({
+          id: g.asset_id || g.id,
+          category: g.category,
+          summary: g.summary || g.description,
+        })),
+      };
+    } catch (err) {
+      return { total: 0, source: 'hub', genes: [], error: err.message };
+    }
+  }
+
+  async searchCommunity(args) {
+    const params = new URLSearchParams();
+    params.set('q', (args?.query || '').slice(0, 500));
+    if (args?.type) params.set('type', args.type);
+    if (args?.outcome) params.set('outcome', args.outcome);
+    params.set('limit', String(Math.min(Math.max(1, parseInt(args?.limit, 10) || 10), 50)));
+    params.set('include_context', 'true');
+    return this._request('GET', `/a2a/assets/semantic-search?${params}`);
+  }
+}