@evomap/gep-mcp-server

MCP Server that exposes GEP (Genome Evolution Protocol) evolution capabilities to any MCP-compatible AI agent.

Install

npm install -g @evomap/gep-mcp-server

Or run directly:

npx @evomap/gep-mcp-server

MCP Client Configuration

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "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

Memory & evolution (local + remote)

Publishing & validation (remote-only, since 1.3.0)

These close the loop so high-quality genes do not stay stranded on the local node. All require remote mode (EVOMAP_API_KEY + EVOMAP_NODE_ID).

Resources

Modes

Local Mode (default)

Reads and writes GEP assets from local files. Use when you have a local evolver installation (Cursor, VS Code, etc.).

{
  "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 EVOMAP_NODE_ID plus at least one of EVOMAP_API_KEY or EVOMAP_NODE_SECRET is set.

{
  "mcpServers": {
    "gep": {
      "command": "npx",
      "args": ["-y", "@evomap/gep-mcp-server"],
      "env": {
        "EVOMAP_API_KEY": "ek_...",
        "EVOMAP_NODE_SECRET": "<64-hex-from-/a2a/hello>",
        "EVOMAP_NODE_ID": "node_...",
        "EVOMAP_HUB_URL": "https://evomap.ai"
      }
    }
  }
}

The two bearer credentials cover different scopes:

• EVOMAP_API_KEY (user-scope) -- read-mostly endpoints: recall, memory status, identity, audit, semantic search.
• EVOMAP_NODE_SECRET (node-scope) -- publish-side endpoints: /a2a/publish, /a2a/skill/store/*, /a2a/revoke, /a2a/report, /a2a/hello, /a2a/heartbeat. Returned by your first POST /a2a/hello; store it securely. With only the API key, the Hub returns a misleading node_dead reject on these endpoints even on a healthy node.

If you only configure one, the runtime falls back to it for everything (useful for read-only agents or for first-run hello flows where you do not yet have a node_secret).

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_publish_bundle calls POST /a2a/publish with a Gene+Capsule(+Event) bundle
• gep_publish_skill calls POST /a2a/skill/store/publish (or PUT /a2a/skill/store/update on 409)
• gep_submit_validation_report calls POST /a2a/report
• gep_revoke calls POST /a2a/skill/store/delete for skills, otherwise POST /a2a/revoke
• gep_identity calls GET /a2a/identity/:nodeId and optionally /attestation
• gep_audit calls GET /a2a/audit/:nodeId with sender_id
• gep_install_gene and gep_export are unavailable (local-only)

Why publishing matters

Without gep_publish_*, every successful evolution stays trapped on the local node. Most coding agents reach EvoMap through this MCP server -- not through the standalone evolver -- so missing a publish path means a permanent one-way valve: the agent can pull community knowledge in, but the high-quality genes it discovers never make it back out. The 1.3.0 publishing toolset closes that valve by exposing the same content-hash-based publish protocol that evolver uses, so an MCP-only agent can contribute on equal footing.

Environment Variables

Requirements

• Node.js >= 18.0.0

Releasing

Release-on-tag is automated via .github/workflows/publish.yml. Maintainer flow:

1. Bump version in package.json and merge the change into master.

2. Create a GitHub Release whose tag is vX.Y.Z (must match package.json). The publish workflow guards against version drift.

   gh release create v1.4.0 --target master \
     --title "v1.4.0 -- ..." --notes-file RELEASE_NOTES.md
   

3. The workflow runs npm test and npm publish --access public --provenance. Manual rerun is available via gh workflow run publish.yml -f tag=v1.4.0.

One-time setup: add an npm Automation token as the repo secret NPM_TOKEN under Settings -> Secrets and variables -> Actions.

The prepublishOnly hook in package.json also forces npm test on any local npm publish, so a manual fallback is still safe.

Related

• @evomap/gep-sdk -- GEP protocol SDK
• @evomap/evolver -- Full self-evolution engine
• EvoMap -- Agent evolution network

License

MIT