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

package/dist/data.js

@@ -0,0 +1,307 @@
+/**
+ * Data layer for the GeraNexus action-rails MCP server.
+ *
+ * Three honest data strategies, in priority order, per marketplace:
+ *
+ *   1. LIVE Gera marketplace API (best-effort) — if the production backend is
+ *      reachable and returns rows, we use them and label the source "live_api".
+ *   2. LIVE public open data — for restaurants we call the UK Food Standards
+ *      Agency FHRS open API (api.ratings.food.gov.uk, no auth), which is
+ *      genuinely live UK restaurant data. Labelled "live_fhrs".
+ *   3. Bundled real crawled seed data — the CSVs shipped in ./data were
+ *      crawled from List.am/Spyur (Yerevan home-service providers) and from
+ *      real UK recruitment agencies. Labelled "bundled_seed".
+ *
+ * Every result carries a `data_source` field so an agent can tell a user
+ * exactly where the data came from. We NEVER fabricate rows.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// dist/ sits next to data/ at the package root: dist/data.js -> ../data
+const DATA_DIR = join(__dirname, '..', 'data');
+// Production base URLs for the live Gera marketplace backends (Railway).
+// These are real, but their databases may be empty/seeded, so every call is
+// best-effort with a short timeout and a graceful fall-back to seed data.
+export const MARKETPLACE_API = {
+    home: 'https://taskova-production-ace3.up.railway.app',
+    jobs: 'https://gerajobs-production.up.railway.app',
+    eats: 'https://fooddash-production-0c1e.up.railway.app',
+};
+const PUBLIC_SURFACE = {
+    home: 'https://gerahome.com',
+    jobs: 'https://gerajobs.com',
+    eats: 'https://geraeats.com',
+};
+// ─── Minimal CSV parser (handles quoted fields + embedded commas) ─────────────
+function parseCsv(text) {
+    const rows = [];
+    let field = '';
+    let row = [];
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += c;
+            }
+        }
+        else if (c === '"') {
+            inQuotes = true;
+        }
+        else if (c === ',') {
+            row.push(field);
+            field = '';
+        }
+        else if (c === '\n' || c === '\r') {
+            if (c === '\r' && text[i + 1] === '\n')
+                i++;
+            if (field !== '' || row.length > 0) {
+                row.push(field);
+                rows.push(row);
+                row = [];
+                field = '';
+            }
+        }
+        else {
+            field += c;
+        }
+    }
+    if (field !== '' || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    if (rows.length === 0)
+        return [];
+    const header = rows[0];
+    return rows.slice(1).map((r) => {
+        const obj = {};
+        header.forEach((h, idx) => {
+            obj[h.trim()] = (r[idx] ?? '').trim();
+        });
+        return obj;
+    });
+}
+let _homeSeed = null;
+let _jobsSeed = null;
+function homeSeed() {
+    if (_homeSeed === null) {
+        try {
+            _homeSeed = parseCsv(readFileSync(join(DATA_DIR, 'gerahome_providers_yerevan.csv'), 'utf8'));
+        }
+        catch {
+            _homeSeed = [];
+        }
+    }
+    return _homeSeed;
+}
+function jobsSeed() {
+    if (_jobsSeed === null) {
+        try {
+            _jobsSeed = parseCsv(readFileSync(join(DATA_DIR, 'gerajobs_providers.csv'), 'utf8'));
+        }
+        catch {
+            _jobsSeed = [];
+        }
+    }
+    return _jobsSeed;
+}
+// ─── best-effort live fetch with timeout ──────────────────────────────────────
+async function fetchJson(url, opts = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 4000);
+    try {
+        const res = await fetch(url, {
+            headers: opts.headers,
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ─── HOME SERVICES ────────────────────────────────────────────────────────────
+export async function searchHomeServices(args) {
+    // 1. Best-effort live GeraHome API.
+    const q = new URLSearchParams();
+    if (args.city)
+        q.set('city', args.city);
+    q.set('limit', String(args.limit));
+    const live = (await fetchJson(`${MARKETPLACE_API.home}/api/v1/providers?${q.toString()}`, { headers: { 'x-tenant-id': 'AM' } }));
+    const liveRows = (live?.data ?? live?.items ?? null);
+    if (Array.isArray(liveRows) && liveRows.length > 0) {
+        const providers = liveRows.slice(0, args.limit).map((r, i) => ({
+            id: String(r.id ?? `home-live-${i}`),
+            name: String(r.business_name ?? r.name ?? 'Provider'),
+            category: String(r.category ?? r.category_name ?? args.category ?? 'general'),
+            city: String(r.city ?? args.city ?? ''),
+            area: r.district ? String(r.district) : undefined,
+            phone: r.phone ? String(r.phone) : undefined,
+        }));
+        return {
+            data_source: 'live_api',
+            providers,
+            public_url: PUBLIC_SURFACE.home,
+            note: 'Live results from the GeraHome production API.',
+        };
+    }
+    // 2. Bundled real crawled seed (Yerevan providers).
+    let rows = homeSeed();
+    if (args.category) {
+        const cat = args.category.toLowerCase();
+        rows = rows.filter((r) => (r.category ?? '').toLowerCase().includes(cat));
+    }
+    if (args.city) {
+        const city = args.city.toLowerCase();
+        rows = rows.filter((r) => (r.full_address ?? '').toLowerCase().includes(city) ||
+            (r.district ?? '').toLowerCase().includes(city));
+    }
+    const providers = rows.slice(0, args.limit).map((r, i) => ({
+        id: `home-seed-${i}`,
+        name: r.business_name,
+        category: r.category,
+        city: 'Yerevan',
+        area: r.district || undefined,
+        phone: r.phone_e164 || undefined,
+        contact: r.email_or_whatsapp || undefined,
+        languages: r.languages_spoken || undefined,
+        years_in_business: r.years_in_business || undefined,
+        why_qualified: r.why_qualified || undefined,
+        source_url: r.source_evidence_url || undefined,
+    }));
+    return {
+        data_source: 'bundled_seed',
+        providers,
+        public_url: PUBLIC_SURFACE.home,
+        note: 'Bundled real crawled providers (Yerevan, sourced from List.am/Spyur). The live GeraHome API was unreachable or empty; these are verified seed records.',
+    };
+}
+// ─── JOBS ─────────────────────────────────────────────────────────────────────
+export async function searchJobs(args) {
+    // 1. Best-effort live GeraJobs API.
+    const q = new URLSearchParams();
+    if (args.query)
+        q.set('query', args.query);
+    if (args.location)
+        q.set('location', args.location);
+    q.set('limit', String(args.limit));
+    const live = (await fetchJson(`${MARKETPLACE_API.jobs}/api/v1/jobs?${q.toString()}`, { headers: { 'x-tenant-id': 'GB' } }));
+    const liveRows = (live?.data ?? live?.items ?? null);
+    if (Array.isArray(liveRows) && liveRows.length > 0) {
+        const jobs = liveRows.slice(0, args.limit).map((r, i) => ({
+            id: String(r.id ?? `job-live-${i}`),
+            title: String(r.title ?? 'Job'),
+            organization: String(r.company_name ?? r.company ?? r.organization ?? ''),
+            location: String(r.location ?? args.location ?? ''),
+            category: r.category ? String(r.category) : undefined,
+            job_type: r.job_type ? String(r.job_type) : undefined,
+            salary: r.salary_min || r.salary_max
+                ? `${r.salary_min ?? ''}-${r.salary_max ?? ''}`
+                : undefined,
+        }));
+        return {
+            data_source: 'live_api',
+            jobs,
+            public_url: PUBLIC_SURFACE.jobs,
+            note: 'Live results from the GeraJobs production API.',
+        };
+    }
+    // 2. Bundled real seed — recruitment-agency supply partners. These are
+    // organizations that supply jobs, not individual postings, so we present
+    // them honestly as "recruiters / job sources", not as live vacancies.
+    let rows = jobsSeed();
+    if (args.query) {
+        const kw = args.query.toLowerCase();
+        rows = rows.filter((r) => (r.name ?? '').toLowerCase().includes(kw) ||
+            (r.notes ?? '').toLowerCase().includes(kw));
+    }
+    if (args.location) {
+        const loc = args.location.toLowerCase();
+        rows = rows.filter((r) => (r.city ?? '').toLowerCase().includes(loc) ||
+            (r.country ?? '').toLowerCase().includes(loc));
+    }
+    const jobs = rows.slice(0, args.limit).map((r, i) => ({
+        id: `job-seed-${i}`,
+        title: `Recruiter / job source: ${r.name}`,
+        organization: r.name,
+        location: [r.city, r.country].filter(Boolean).join(', '),
+        website: r.website || undefined,
+        notes: r.notes || undefined,
+    }));
+    return {
+        data_source: 'bundled_seed',
+        jobs,
+        public_url: PUBLIC_SURFACE.jobs,
+        note: 'The live GeraJobs API was unreachable or has no matching vacancies. These are real recruitment-agency / job-board supply partners (not individual vacancies) — use them as the place to find live openings.',
+    };
+}
+// ─── RESTAURANTS (live FHRS open data) ────────────────────────────────────────
+export async function searchRestaurants(args) {
+    // LIVE: UK Food Standards Agency FHRS open API — real, no auth.
+    const q = new URLSearchParams();
+    if (args.name)
+        q.set('name', args.name);
+    if (args.city)
+        q.set('address', args.city);
+    // FHRS BusinessTypeId 1 = "Restaurant/Cafe/Canteen", 7843 = pub/bar; we
+    // leave type open and filter to food-serving types client-side.
+    q.set('pageSize', String(Math.min(args.limit * 3, 100)));
+    const data = (await fetchJson(`https://api.ratings.food.gov.uk/Establishments?${q.toString()}`, { headers: { 'x-api-version': '2', accept: 'application/json' }, timeoutMs: 6000 }));
+    if (data && Array.isArray(data.establishments)) {
+        let rows = data.establishments;
+        if (typeof args.min_rating === 'number') {
+            rows = rows.filter((r) => {
+                const v = parseInt(String(r.RatingValue), 10);
+                return !Number.isNaN(v) && v >= args.min_rating;
+            });
+        }
+        const restaurants = rows.slice(0, args.limit).map((r) => {
+            const geo = (r.geocode ?? {});
+            return {
+                id: `fhrs-${r.FHRSID}`,
+                name: String(r.BusinessName ?? ''),
+                business_type: r.BusinessType ? String(r.BusinessType) : undefined,
+                address: [r.AddressLine1, r.AddressLine2, r.AddressLine3, r.AddressLine4]
+                    .filter(Boolean)
+                    .map(String)
+                    .join(', '),
+                postcode: r.PostCode ? String(r.PostCode) : undefined,
+                city: args.city,
+                hygiene_rating: r.RatingValue ? String(r.RatingValue) : undefined,
+                rating_date: r.RatingDate ? String(r.RatingDate).slice(0, 10) : undefined,
+                phone: r.Phone ? String(r.Phone) : undefined,
+                local_authority: r.LocalAuthorityName ? String(r.LocalAuthorityName) : undefined,
+                lat: geo.latitude ? String(geo.latitude) : undefined,
+                lng: geo.longitude ? String(geo.longitude) : undefined,
+            };
+        });
+        return {
+            data_source: 'live_fhrs',
+            restaurants,
+            public_url: PUBLIC_SURFACE.eats,
+            note: 'Live UK restaurant data with current Food Hygiene Ratings from the Food Standards Agency (api.ratings.food.gov.uk). GeraEats lists and delivers from establishments like these.',
+        };
+    }
+    return {
+        data_source: 'live_fhrs',
+        restaurants: [],
+        public_url: PUBLIC_SURFACE.eats,
+        note: 'The FHRS open data API was unreachable. No restaurants returned — try again or refine the city/name.',
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @gera-services/mcp-gera-nexus
+ *
+ * MCP server for GeraNexus — the agentic-commerce ACTION rails by Gera Systems.
+ * Re-exports the server factory for programmatic / HTTP use.
+ *
+ * @packageDocumentation
+ */
+export { server, createServer, registerTools, main } from './server.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @gera-services/mcp-gera-nexus
+ *
+ * MCP server for GeraNexus — the agentic-commerce ACTION rails by Gera Systems.
+ * Re-exports the server factory for programmatic / HTTP use.
+ *
+ * @packageDocumentation
+ */
+export { server, createServer, registerTools, main } from './server.js';

package/dist/intents.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Consent-first action intents for GeraNexus.
+ *
+ * An "intent" is a structured, human-confirmable lead. It is explicitly NOT an
+ * executed transaction: no payment is taken, no provider is committed. The
+ * intent records what the agent + user want, assigns a tracking id, builds a
+ * deep-link the human opens to confirm/pay on the real Gera surface, and
+ * appends to an in-process audit trail.
+ *
+ * This mirrors the GeraNexus protocol's ConsentGate / human-in-the-loop step
+ * (services/gera-nexus protocol.service.ts) — the spend-threshold gate that
+ * routes to out-of-band human approval. Here, EVERY action is gated, because
+ * an MCP server acting for a user must never silently spend their money.
+ *
+ * Storage is in-process (Map). It is intentionally ephemeral: a real
+ * deployment would persist these to the GeraNexus backend's audit log. We do
+ * not pretend otherwise — get_action_status only sees intents created in this
+ * same process/session.
+ */
+export type ActionKind = 'home_booking' | 'job_application' | 'restaurant_order';
+export type IntentStatus = 'pending_human_confirmation' | 'expired' | 'unknown';
+export interface ActionIntent {
+    intent_id: string;
+    kind: ActionKind;
+    status: IntentStatus;
+    created_at: string;
+    expires_at: string;
+    summary: string;
+    target: {
+        marketplace: 'GeraHome' | 'GeraJobs' | 'GeraEats';
+        provider_id?: string;
+        provider_name?: string;
+    };
+    details: Record<string, unknown>;
+    confirmation_url: string;
+    audit_signature: string;
+    audit_trail: Array<{
+        at: string;
+        event: string;
+    }>;
+}
+export declare function createIntent(input: {
+    kind: ActionKind;
+    marketplace: ActionIntent['target']['marketplace'];
+    provider_id?: string;
+    provider_name?: string;
+    summary: string;
+    details: Record<string, unknown>;
+}): ActionIntent;
+export declare function getIntent(id: string): ActionIntent | null;

package/dist/intents.js

@@ -0,0 +1,94 @@
+/**
+ * Consent-first action intents for GeraNexus.
+ *
+ * An "intent" is a structured, human-confirmable lead. It is explicitly NOT an
+ * executed transaction: no payment is taken, no provider is committed. The
+ * intent records what the agent + user want, assigns a tracking id, builds a
+ * deep-link the human opens to confirm/pay on the real Gera surface, and
+ * appends to an in-process audit trail.
+ *
+ * This mirrors the GeraNexus protocol's ConsentGate / human-in-the-loop step
+ * (services/gera-nexus protocol.service.ts) — the spend-threshold gate that
+ * routes to out-of-band human approval. Here, EVERY action is gated, because
+ * an MCP server acting for a user must never silently spend their money.
+ *
+ * Storage is in-process (Map). It is intentionally ephemeral: a real
+ * deployment would persist these to the GeraNexus backend's audit log. We do
+ * not pretend otherwise — get_action_status only sees intents created in this
+ * same process/session.
+ */
+import { randomUUID, createHash } from 'node:crypto';
+const store = new Map();
+const PUBLIC_SURFACE = {
+    GeraHome: 'https://gerahome.com',
+    GeraJobs: 'https://gerajobs.com',
+    GeraEats: 'https://geraeats.com',
+};
+const INTENT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+function signature(payload) {
+    return ('sha256:' +
+        createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, 32));
+}
+export function createIntent(input) {
+    const id = `intent_${randomUUID()}`;
+    const now = new Date();
+    const created_at = now.toISOString();
+    const expires_at = new Date(now.getTime() + INTENT_TTL_MS).toISOString();
+    // Deep-link to the relevant public surface, carrying the intent id so the
+    // human lands on the right place to review and confirm. The path differs per
+    // marketplace and matches the real public surfaces.
+    const base = PUBLIC_SURFACE[input.marketplace];
+    const pathByKind = {
+        home_booking: '/book',
+        job_application: '/apply',
+        restaurant_order: '/order',
+    };
+    const params = new URLSearchParams({ intent: id, source: 'mcp-gera-nexus' });
+    if (input.provider_id)
+        params.set('ref', input.provider_id);
+    const confirmation_url = `${base}${pathByKind[input.kind]}?${params.toString()}`;
+    const corePayload = {
+        id,
+        kind: input.kind,
+        marketplace: input.marketplace,
+        provider_id: input.provider_id,
+        details: input.details,
+        created_at,
+    };
+    const intent = {
+        intent_id: id,
+        kind: input.kind,
+        status: 'pending_human_confirmation',
+        created_at,
+        expires_at,
+        summary: input.summary,
+        target: {
+            marketplace: input.marketplace,
+            provider_id: input.provider_id,
+            provider_name: input.provider_name,
+        },
+        details: input.details,
+        confirmation_url,
+        audit_signature: signature(corePayload),
+        audit_trail: [
+            { at: created_at, event: 'intent_created_via_mcp (no payment taken)' },
+            { at: created_at, event: 'awaiting_human_confirmation' },
+        ],
+    };
+    store.set(id, intent);
+    return intent;
+}
+export function getIntent(id) {
+    const intent = store.get(id);
+    if (!intent)
+        return null;
+    if (intent.status === 'pending_human_confirmation' &&
+        Date.now() > new Date(intent.expires_at).getTime()) {
+        intent.status = 'expired';
+        intent.audit_trail.push({
+            at: new Date().toISOString(),
+            event: 'intent_expired_unconfirmed',
+        });
+    }
+    return intent;
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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';
+export declare function registerTools(server: McpServer): void;
+/** Construct a fully-configured GeraNexus McpServer (all tools registered). */
+export declare function createServer(): McpServer;
+export declare const server: McpServer;
+export declare function main(): Promise<void>;