@evomap/gep-mcp-server 1.0.2 → 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.2",
+  "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.2' },
+  { 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}`);
+  }
+}