@gera-services/mcp-gera-nexus

MCP (Model Context Protocol) server for GeraNexus — the Agentic Commerce Protocol by Gera Systems.

This is the agent ACTION rails: the "do-this-for-me-safely" layer that lets an AI agent search Gera's marketplaces and act on a user's behalf — without ever silently spending the user's money.

Honesty contract

This server is built to never fake a completed transaction.

• Search tools are real-data-backed. Each result carries a data_source field so the agent (and the user) knows exactly where the data came from: live_api (a Gera marketplace production API), live_fhrs (the UK Food Standards Agency open data), or bundled_seed (real crawled records shipped with this package, used when the live API is unreachable or empty).
• Action tools are consent-first. create_booking_intent records a structured, human-confirmable intent / lead and returns a deep-link the human opens to confirm. It does not take payment, does not commit a provider, and never reports a transaction as "done". This mirrors the GeraNexus protocol's ConsentGate / human-in-the-loop step — applied to every action.

Tools

| Tool | Kind | Description | |------|------|-------------| | search_home_services | read-only | Find home-service providers (plumbers, electricians, cleaners…) on GeraHome. Live API → bundled real crawled providers (Yerevan / List.am / Spyur). | | search_jobs | read-only | Search jobs on GeraJobs. Live API → real recruitment-agency / job-board supply partners. | | search_restaurants | read-only | Find restaurants with current UK Food Hygiene Ratings — live from the FSA FHRS open API (api.ratings.food.gov.uk). | | create_booking_intent | consent-first action | Create a booking / application / order intent for the user to confirm. Returns a tracking intent_id, an audit signature, and a confirmation_url. No payment is taken. | | get_action_status | read-only | Look up an intent created earlier this session by intent_id. |

Data sources (what's real)

| Marketplace | Backing | |---|---| | GeraEats (restaurants) | Live UK FSA FHRS open API — genuinely live restaurant + hygiene-rating data, no auth. | | GeraHome (providers) | Live GeraHome production API (best-effort) → 111 real crawled Yerevan providers bundled in data/. | | GeraJobs (jobs) | Live GeraJobs production API (best-effort) → real recruitment-agency supply partners bundled in data/. |

Installation

npx @gera-services/mcp-gera-nexus

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gera-nexus": {
      "command": "npx",
      "args": ["@gera-services/mcp-gera-nexus"]
    }
  }
}

Or, from a local checkout:

{
  "mcpServers": {
    "gera-nexus": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp-gera-nexus/bin/cli.js"]
    }
  }
}

Build & smoke test

cd packages/mcp-gera-nexus
npx tsc --noCheck          # emit dist/ (no type-check OOM on MCP SDK generics)
node scripts/smoke.mjs     # initialize → tools/list → real search + booking intent

How this relates to the GeraNexus backend

The services/gera-nexus NestJS backend defines the full protocol spec (discover, negotiate, book, pay, cancel, refund, dispute, verify-completion, audit) and its ConsentGate human-in-the-loop gate. This MCP server is the agent-facing front door to that protocol: today it ships the read (search_*) capabilities against real marketplace data plus the consent gate (create_booking_intent). Full payment/settlement execution (pay/refund) wires into the GeraNexus backend + GeraCash/Stripe — see the parent repo's report for the endpoints that remain to be connected.

License

MIT — (c) 2026 Gera Systems Ltd