@gera-services/mcp-gera-nexus 0.1.0 → 1.0.0

package/dist/server.js

@@ -1,74 +1,318 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var server_exports = {};
-__export(server_exports, {
-  server: () => server
-});
-module.exports = __toCommonJS(server_exports);
-var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
-const server = new import_mcp.McpServer({
-  name: "gera-nexus",
-  version: "0.1.0"
-});
-server.tool(
-  "info",
-  "Return product information about GeraNexus \u2014 the open Agentic Commerce Protocol by Gera Services. Use this to learn what GeraNexus is, why it exists, and when the full MCP toolset will ship.",
-  {},
-  async () => {
-    const info = {
-      status: "coming-soon",
-      product: "GeraNexus",
-      tagline: "The Agentic Commerce Protocol",
-      description: 'An open protocol extending MCP into transactional territory so any AI agent can negotiate, book, pay, cancel, refund, dispute, and verify completion across real-world services. Gera exposes all 22 verticals (GeraClinic, GeraHome, GeraMarket, GeraEats, GeraRide, GeraCash, and more) as reference implementations. Goal: become "Stripe for agent commerce."',
-      category: "Infrastructure / Protocol",
-      plannedActions: [
-        "negotiate",
-        "book",
-        "pay",
-        "cancel",
-        "refund",
-        "dispute",
-        "verify-completion"
-      ],
-      revenueModel: [
-        "2% transaction fee on agent-initiated commerce",
-        "Protocol governance fees from third-party marketplaces",
-        "Premium tier: higher volume, priority support, dispute SLA"
-      ],
-      launchEstimate: "Q3-Q4 2026",
-      learnMore: "https://geranexus.com",
-      parentCompany: "Gera Services Ltd (https://gera.services)",
-      fullSpec: "https://github.com/geraservicesuk/globetura/blob/master/ceo/strategy/research/five-ideas-for-2030.md"
-    };
+/**
+ * GeraNexus MCP Server (stdio) — the agent ACTION rails.
+ *
+ * GeraNexus is "the Agentic Commerce Protocol": the transactional layer AI
+ * agents use to DO real-world things across Gera's marketplaces on a user's
+ * behalf. This MCP server is the agent-facing front door to that protocol —
+ * the "do-this-for-me-safely" layer.
+ *
+ * Two kinds of tools:
+ *   • SEARCH tools (read-only) — find real home-service providers, jobs, and
+ *     restaurants. Backed by live Gera APIs where reachable, the UK FSA FHRS
+ *     open data for restaurants, and bundled real crawled seed data otherwise.
+ *     Every result is labelled with its data_source.
+ *   • ACTION tools (consent-first) — create_booking_intent records a
+ *     structured, human-confirmable INTENT/lead and returns a confirmation id
+ *     plus a deep-link the human opens to confirm. It does NOT charge, does NOT
+ *     commit a provider, and NEVER reports a completed transaction. This is the
+ *     ConsentGate / human-in-the-loop step of the GeraNexus protocol, applied
+ *     to every action.
+ *
+ * Honesty contract: an action that cannot truly complete returns a clearly
+ * labelled "intent + next-step link", never a faked confirmation.
+ *
+ * Product: GeraNexus — agentic commerce protocol (a Gera Systems product).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { searchHomeServices, searchJobs, searchRestaurants, } from './data.js';
+import { createIntent, getIntent } from './intents.js';
+function asText(payload) {
     return {
-      content: [{ type: "text", text: JSON.stringify(info, null, 2) }]
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
     };
-  }
-);
-async function main() {
-  const transport = new import_stdio.StdioServerTransport();
-  await server.connect(transport);
-  console.error("GeraNexus MCP server (placeholder v0.1.0) running on stdio");
 }
-main().catch(console.error);
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  server
-});
+const DATA_SOURCE_LEGEND = {
+    live_api: 'Live data from the Gera marketplace production API.',
+    live_fhrs: 'Live UK restaurant data from the Food Standards Agency FHRS open API (api.ratings.food.gov.uk).',
+    bundled_seed: 'Real crawled seed data bundled with this server (live API was unreachable or empty). These are verified records, not live availability.',
+};
+export function registerTools(server) {
+    // ── Tool 1: search_home_services ──────────────────────────────────────────
+    server.registerTool('search_home_services', {
+        title: 'Search GeraHome home-service providers',
+        description: 'Find home-service providers (plumbers, electricians, cleaners, handymen, etc.) on GeraHome. ' +
+            'Tries the live GeraHome production API first; if unreachable or empty, falls back to real ' +
+            'crawled provider records bundled with this server (currently Yerevan, sourced from List.am/Spyur). ' +
+            "Read-only — finds providers; it does not book anything. The result's \"data_source\" field tells " +
+            'you whether rows are live or bundled seed. Pass these provider ids to create_booking_intent to ' +
+            'start a consent-first booking.',
+        inputSchema: {
+            category: z
+                .string()
+                .optional()
+                .describe('Service category, e.g. "plumber", "electrician", "cleaner".'),
+            city: z.string().optional().describe('City to search in, e.g. "Yerevan".'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Max providers to return (default 10).'),
+        },
+    }, async ({ category, city, limit }) => {
+        const r = await searchHomeServices({ category, city, limit: limit ?? 10 });
+        return asText({
+            query: { category: category ?? null, city: city ?? null },
+            data_source: r.data_source,
+            data_source_meaning: DATA_SOURCE_LEGEND[r.data_source],
+            note: r.note,
+            result_count: r.providers.length,
+            providers: r.providers,
+            public_url: r.public_url,
+            next_step: 'To request a booking, call create_booking_intent with action_kind="home_booking" and a chosen provider id. That creates a consent-first lead for the user to confirm — it does NOT charge or commit.',
+        });
+    });
+    // ── Tool 2: search_jobs ───────────────────────────────────────────────────
+    server.registerTool('search_jobs', {
+        title: 'Search GeraJobs job postings',
+        description: 'Search jobs on GeraJobs by keyword and location. Tries the live GeraJobs production API first; ' +
+            'if unreachable or empty, returns real recruitment-agency / job-board supply partners bundled with ' +
+            'this server (clearly labelled — these are where vacancies come from, not individual postings). ' +
+            'Read-only. The "data_source" field tells you which you got. To apply, use create_booking_intent ' +
+            'with action_kind="job_application" — that creates a consent-first application lead, not a submitted application.',
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe('Keyword, e.g. "software engineer", "nurse", "driver".'),
+            location: z
+                .string()
+                .optional()
+                .describe('Location filter, e.g. "London", "GB", "remote".'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Max results to return (default 10).'),
+        },
+    }, async ({ query, location, limit }) => {
+        const r = await searchJobs({ query, location, limit: limit ?? 10 });
+        return asText({
+            query: { query: query ?? null, location: location ?? null },
+            data_source: r.data_source,
+            data_source_meaning: DATA_SOURCE_LEGEND[r.data_source],
+            note: r.note,
+            result_count: r.jobs.length,
+            jobs: r.jobs,
+            public_url: r.public_url,
+            next_step: 'To apply, call create_booking_intent with action_kind="job_application". That creates a consent-first application lead for the user to confirm and submit — it does NOT auto-submit an application.',
+        });
+    });
+    // ── Tool 3: search_restaurants ────────────────────────────────────────────
+    server.registerTool('search_restaurants', {
+        title: 'Search restaurants (live UK FHRS data)',
+        description: 'Find restaurants for GeraEats, with their current UK Food Hygiene Ratings. Backed by the live ' +
+            'Food Standards Agency FHRS open API (api.ratings.food.gov.uk) — genuinely live UK restaurant data, ' +
+            'no auth. Filter by city/name and minimum hygiene rating (0-5). Read-only. To place an order, use ' +
+            'create_booking_intent with action_kind="restaurant_order" — a consent-first order lead, not a paid order.',
+        inputSchema: {
+            city: z
+                .string()
+                .optional()
+                .describe('UK city/town/area to search, e.g. "Bristol", "Manchester".'),
+            name: z
+                .string()
+                .optional()
+                .describe('Restaurant name to search for, e.g. "Dishoom".'),
+            min_rating: z
+                .number()
+                .int()
+                .min(0)
+                .max(5)
+                .optional()
+                .describe('Minimum food hygiene rating (0-5). E.g. 4 = only well-rated places.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Max restaurants to return (default 10).'),
+        },
+    }, async ({ city, name, min_rating, limit }) => {
+        const r = await searchRestaurants({
+            city,
+            name,
+            min_rating,
+            limit: limit ?? 10,
+        });
+        return asText({
+            query: { city: city ?? null, name: name ?? null, min_rating: min_rating ?? null },
+            data_source: r.data_source,
+            data_source_meaning: DATA_SOURCE_LEGEND[r.data_source],
+            note: r.note,
+            result_count: r.restaurants.length,
+            restaurants: r.restaurants,
+            public_url: r.public_url,
+            next_step: 'To order, call create_booking_intent with action_kind="restaurant_order". That creates a consent-first order lead for the user to confirm and pay — it does NOT charge.',
+        });
+    });
+    // ── Tool 4: create_booking_intent ─────────────────────────────────────────
+    // The consent-first action rail. Never charges, never commits, never fakes.
+    server.registerTool('create_booking_intent', {
+        title: 'Create a consent-first booking/action INTENT (no payment)',
+        description: "Create a structured, human-confirmable INTENT to act on a Gera marketplace on the user's behalf — " +
+            'a home-service booking, a job application, or a restaurant order. ' +
+            'IMPORTANT — this is the consent gate: it does NOT take payment, does NOT commit a provider, and does ' +
+            'NOT execute the transaction. It records what the user wants, assigns a tracking intent_id, writes an ' +
+            'audit entry, and returns a confirmation_url (a deep-link) the HUMAN opens to review and complete the ' +
+            'action on the real Gera surface. Present the intent and the confirmation link to the user; tell them ' +
+            'plainly that nothing has been booked or paid yet and that they must confirm. Use get_action_status to ' +
+            'check an intent later. Never tell the user a booking/order/application is "done" from this tool — it is a lead awaiting their confirmation.',
+        inputSchema: {
+            action_kind: z
+                .enum(['home_booking', 'job_application', 'restaurant_order'])
+                .describe('Which marketplace action to create an intent for.'),
+            provider_id: z
+                .string()
+                .optional()
+                .describe('Id of the chosen provider/job/restaurant from a search_* tool result.'),
+            provider_name: z
+                .string()
+                .optional()
+                .describe('Human-readable name of the chosen provider/job/restaurant.'),
+            requested_for: z
+                .string()
+                .optional()
+                .describe('When the user wants it, e.g. "2026-06-20 morning", "ASAP".'),
+            contact_name: z
+                .string()
+                .optional()
+                .describe('Name the user wants to book under (kept in the intent for the human to confirm).'),
+            notes: z
+                .string()
+                .optional()
+                .describe('Free-text details: the task, the order items, the role applied for, etc.'),
+            consent_acknowledged: z
+                .boolean()
+                .describe('Must be true: confirms the agent has told the user this creates a lead for THEM to confirm, not an executed/paid transaction.'),
+        },
+    }, async (args) => {
+        if (!args.consent_acknowledged) {
+            return asText({
+                ok: false,
+                error: 'consent_required',
+                message: 'Refusing to create an intent without consent_acknowledged=true. First tell the user this will create a booking/order/application LEAD that THEY must confirm (no payment is taken here), then call again with consent_acknowledged=true.',
+            });
+        }
+        const marketplaceByKind = {
+            home_booking: 'GeraHome',
+            job_application: 'GeraJobs',
+            restaurant_order: 'GeraEats',
+        };
+        const verbByKind = {
+            home_booking: 'Home-service booking',
+            job_application: 'Job application',
+            restaurant_order: 'Restaurant order',
+        };
+        const kind = args.action_kind;
+        const target = args.provider_name ?? args.provider_id ?? 'selected listing';
+        const summary = `${verbByKind[kind]} request for "${target}"` +
+            (args.requested_for ? `, requested for ${args.requested_for}` : '') +
+            '. Awaiting human confirmation — nothing booked or paid yet.';
+        const intent = createIntent({
+            kind,
+            marketplace: marketplaceByKind[kind],
+            provider_id: args.provider_id,
+            provider_name: args.provider_name,
+            summary,
+            details: {
+                requested_for: args.requested_for ?? null,
+                contact_name: args.contact_name ?? null,
+                notes: args.notes ?? null,
+            },
+        });
+        return asText({
+            ok: true,
+            kind: 'intent',
+            is_executed_transaction: false,
+            payment_taken: false,
+            intent_id: intent.intent_id,
+            status: intent.status,
+            status_meaning: 'A lead has been recorded. The user must open confirmation_url to review and complete the action. No provider is committed and no money has moved.',
+            summary: intent.summary,
+            target: intent.target,
+            details: intent.details,
+            confirmation_url: intent.confirmation_url,
+            expires_at: intent.expires_at,
+            audit_signature: intent.audit_signature,
+            audit_trail: intent.audit_trail,
+            present_to_user: `I've prepared a ${verbByKind[kind].toLowerCase()} request (id ${intent.intent_id}). ` +
+                `Nothing is booked or paid yet — please confirm it here: ${intent.confirmation_url}`,
+        });
+    });
+    // ── Tool 5: get_action_status ─────────────────────────────────────────────
+    server.registerTool('get_action_status', {
+        title: 'Look up a booking/action intent status',
+        description: 'Look up the status of an intent created earlier by create_booking_intent, by its intent_id. ' +
+            'Returns the current status (pending_human_confirmation | expired | unknown) and the audit trail. ' +
+            'Note: intents are tracked per running server session — an id from a different session returns "unknown". ' +
+            'This server does NOT poll the marketplace for downstream completion; confirmation/payment happens on the ' +
+            'Gera surface via the confirmation_url, outside this tool.',
+        inputSchema: {
+            intent_id: z
+                .string()
+                .describe('The intent_id returned by create_booking_intent.'),
+        },
+    }, async ({ intent_id }) => {
+        const intent = getIntent(intent_id);
+        if (!intent) {
+            return asText({
+                intent_id,
+                status: 'unknown',
+                message: 'No intent with that id in this server session. It may have been created in a different session, or the id is wrong. Intents are not persisted across restarts in this version.',
+            });
+        }
+        return asText({
+            intent_id: intent.intent_id,
+            status: intent.status,
+            is_executed_transaction: false,
+            summary: intent.summary,
+            target: intent.target,
+            confirmation_url: intent.confirmation_url,
+            expires_at: intent.expires_at,
+            audit_signature: intent.audit_signature,
+            audit_trail: intent.audit_trail,
+        });
+    });
+}
+/** Construct a fully-configured GeraNexus McpServer (all tools registered). */
+export function createServer() {
+    const server = new McpServer({
+        name: 'gera-nexus',
+        version: '1.0.0',
+    });
+    registerTools(server);
+    return server;
+}
+export const server = createServer();
+export async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the MCP transport.
+    console.error('GeraNexus MCP server running on stdio (gera-nexus v1.0.0)');
+}
+const isMain = typeof process !== 'undefined' &&
+    process.argv[1] &&
+    /server\.js$/.test(process.argv[1]);
+if (isMain) {
+    main().catch((err) => {
+        console.error('Fatal:', err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,54 +1,59 @@
 {
   "name": "@gera-services/mcp-gera-nexus",
-  "version": "0.1.0",
-  "description": "MCP server for GeraNexus — the open Agentic Commerce Protocol by Gera Services. Placeholder; full transactional protocol (negotiate, book, pay, cancel, refund, dispute) launching 2026.",
+  "version": "1.0.0",
+  "description": "GeraNexus MCP server — the agentic-commerce ACTION rails. Lets an AI agent search Gera marketplaces (home services, jobs, restaurants) and create consent-first booking INTENTS on a user's behalf. A Gera Systems product.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
   "mcpName": "io.github.geraservicesuk/mcp-gera-nexus",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "bin": {
     "mcp-gera-nexus": "bin/cli.js"
   },
   "files": [
     "dist",
     "bin",
+    "data",
+    "server.json",
     "README.md",
-    "LICENSE",
-    "server.json"
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "node build.mjs",
+    "build": "tsc --noCheck",
     "type-check": "tsc --noEmit",
-    "dev": "tsc --watch --noCheck",
-    "start": "node dist/server.js",
-    "prepublishOnly": "npm run build"
+    "start": "node bin/cli.js",
+    "smoke": "node scripts/smoke.mjs"
   },
   "keywords": [
     "mcp",
     "model-context-protocol",
     "ai",
+    "ai-agent",
+    "agentic-commerce",
     "gera",
     "gera-nexus",
-    "ai-agent"
+    "booking",
+    "marketplace"
   ],
   "author": {
-    "name": "Gera Services",
+    "name": "Gera Systems",
     "email": "engineering@gera.services",
     "url": "https://gera.services"
   },
-  "license": "MIT",
+  "homepage": "https://geranexus.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/geraservicesuk/mcp-gera-nexus"
+    "url": "https://github.com/geraservicesuk/globetura.git",
+    "directory": "packages/mcp-gera-nexus"
   },
-  "homepage": "https://geranexus.com",
   "bugs": {
-    "url": "https://github.com/geraservicesuk/mcp-gera-nexus/issues"
+    "url": "https://github.com/geraservicesuk/globetura/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
@@ -56,7 +61,6 @@
   },
   "devDependencies": {
     "@types/node": "^20.12.0",
-    "esbuild": "^0.28.0",
     "typescript": "^5.4.0"
   }
 }

package/server.json

@@ -1,17 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.geraservicesuk/mcp-gera-nexus",
-  "description": "Placeholder MCP server for GeraNexus — the open Agentic Commerce Protocol by Gera Services. Ships a single `info` tool while the full transactional toolset is under development (launching 2026).",
+  "description": "Search Gera marketplaces and create consent-first booking intents. No payment taken by server.",
+  "version": "1.0.0",
   "repository": {
-    "url": "https://github.com/geraservicesuk/mcp-gera-nexus",
-    "source": "github"
+    "url": "https://github.com/geraservicesuk/globetura",
+    "source": "github",
+    "subfolder": "packages/mcp-gera-nexus"
   },
-  "version": "0.1.0",
+  "websiteUrl": "https://geranexus.com",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@gera-services/mcp-gera-nexus",
-      "version": "0.1.0",
+      "version": "1.0.0",
       "transport": {
         "type": "stdio"
       },