@evomap/gep-mcp-server 1.0.1 → 1.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @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) |
+
+## 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` |
+
+## 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.1",
+  "version": "1.1.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.1' },
+  { name: 'gep-mcp-server', version: '1.1.0' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -187,23 +191,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: 'gep_install_gene is only available in local mode' }], 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: 'gep_export is only available in local mode' }], 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);
@@ -273,7 +285,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,109 @@
+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 } = args || {};
+    return this._request('POST', '/a2a/memory/recall', {
+      node_id: this.nodeId,
+      query,
+      signals,
+      limit: 20,
+    });
+  }
+
+  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 recallResult = await this.recall({ query: args?.context, signals: null });
+    const signals = recallResult.signals_extracted || [];
+
+    let communityGenes = [];
+    try {
+      const params = new URLSearchParams({ q: (args?.context || '').slice(0, 200), type: 'Gene', limit: '5' });
+      const searchResult = await this._request('GET', `/a2a/assets/semantic-search?${params}`);
+      communityGenes = (searchResult.assets || []).slice(0, 3);
+    } catch { /* best effort */ }
+
+    return {
+      ok: true,
+      mode: 'remote',
+      signals,
+      recall_matches: recallResult.matches || [],
+      community_genes: communityGenes.map(g => ({
+        id: g.asset_id || g.id,
+        category: g.category,
+        summary: g.summary || g.description,
+      })),
+      instructions: [
+        'Review recalled experiences above for patterns that worked or failed.',
+        'If a community gene matches your situation, follow its strategy.',
+        '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}`);
+  }
+}

package/src/runtime.js

@@ -16,7 +16,8 @@ export class GepRuntime {
     this.store.ensureFiles();
   }
 
-  evolve({ context, intent }) {
+  evolve(args) {
+    const { context, intent } = args || {};
     const signals = this._extractSignals(context);
 
     if (intent) {
@@ -96,7 +97,8 @@ export class GepRuntime {
     };
   }
 
-  recall({ query, signals }) {
+  recall(args) {
+    const { query, signals } = args || {};
     const events = this._readGraphEvents(500);
     const querySignals = signals || this._extractSignals(query);
     const queryKey = this._computeSignalKey(querySignals);
@@ -130,7 +132,8 @@ export class GepRuntime {
     };
   }
 
-  recordOutcome({ geneId, signals, status, score, summary }) {
+  recordOutcome(args) {
+    const { geneId, signals, status, score, summary } = args || {};
     const signalKey = this._computeSignalKey(signals);
     const ev = {
       type: 'MemoryGraphEvent',
@@ -178,7 +181,8 @@ export class GepRuntime {
     };
   }
 
-  installGene({ gene }) {
+  installGene(args) {
+    const { gene } = args || {};
     if (!gene || gene.type !== 'Gene' || !gene.id) {
       return { ok: false, error: 'Invalid gene: must have type="Gene" and a non-empty id' };
     }
@@ -188,7 +192,8 @@ export class GepRuntime {
     return { ok: true, installed: gene.id };
   }
 
-  exportEvolution({ outputPath, agentName }) {
+  exportEvolution(args) {
+    let { outputPath, agentName } = args || {};
     const resolvedOutput = resolve(outputPath);
     const allowedRoots = [resolve(this.assetsDir), resolve(this.memoryDir, '..')];
     if (!allowedRoots.some(root => resolvedOutput.startsWith(root + '/'))) {
@@ -217,7 +222,7 @@ export class GepRuntime {
       created_at: new Date().toISOString(),
       agent_name: agentName || 'unknown',
       statistics: this.getStatus().statistics,
-      source: { platform: 'gep-mcp-server', version: '1.0.0' },
+      source: { platform: 'gep-mcp-server', version: '1.0.2' },
     };
     writeFileSync(join(tmpDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
@@ -236,7 +241,7 @@ export class GepRuntime {
     const genes = this.store.loadGenes();
     const capsules = this.store.loadCapsules();
     const events = this.store.readAllEvents();
-    const graphEvents = this._readGraphEvents(100);
+    const graphEntryCount = this._countGraphEntries();
 
     const recentEvents = events.slice(-5).map(e => ({
       id: e.id,
@@ -253,7 +258,7 @@ export class GepRuntime {
         total_genes: genes.length,
         total_capsules: capsules.length,
         total_events: events.length,
-        memory_graph_entries: graphEvents.length,
+        memory_graph_entries: graphEntryCount,
         success_rate: events.length > 0 ? Math.round((successCount / events.length) * 100) / 100 : 0,
       },
       recent_events: recentEvents,
@@ -372,6 +377,14 @@ export class GepRuntime {
     return 'improve success rate and efficiency';
   }
 
+  _countGraphEntries() {
+    try {
+      if (!existsSync(this.memoryGraphPath)) return 0;
+      const raw = readFileSync(this.memoryGraphPath, 'utf8');
+      return raw.split('\n').filter(l => l.trim()).length;
+    } catch { return 0; }
+  }
+
   _readGraphEvents(limit = 1000) {
     try {
       if (!existsSync(this.memoryGraphPath)) return [];