@gera-services/mcp-gera-verify 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# Gera Verify MCP Server — "Proof-of-Real"
+
+[![A Gera Systems product](https://img.shields.io/badge/Gera-Systems-0a7?style=flat)](https://gera.services)
+
+An [MCP](https://modelcontextprotocol.io) server that lets any AI agent — Claude
+Desktop, ChatGPT with tools, Cursor, Windsurf, or any MCP client — answer
+**"is this real / how trustworthy is this?"** about a UK business, food
+establishment, or care provider, grounded in **real verified data Gera already
+owns**.
+
+It is seeded with first- and third-party verified datasets that Gera already
+renders on its products:
+
+| Signal | Source | Records (this snapshot) |
+|---|---|---|
+| Food-hygiene ratings | **FSA Food Hygiene Rating Scheme (FHRS/FHIS)** — as used by [GeraEats](https://geraeats.com) | 10,266 establishments |
+| Care-provider registry | **CQC** (Care Quality Commission) — as used by [GeraClinic](https://geraclinic.com) | 5,411 providers |
+| Verified providers | **Gera's own crawled verified-provider set** | 25 providers |
+| Public doctor listings | Practo public profiles | 406 doctors |
+
+**Everything is offline.** The data is a committed on-disk snapshot, so the
+server gives the same verified answer the Gera products give and runs anywhere
+with **no backend, no network, no auth**.
+
+> **Honesty contract.** Every signal is source-attributed with an as-of date.
+> When a subject is **not** in our records, the tools say so plainly
+> (`not_in_our_records`) — they **never invent** a rating or status. Signals we
+> do not hold (e.g. CQC's categorical overall rating) are returned as
+> `"unknown"`, never guessed.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `check_business_trust` | **Flagship.** Given a business name (+ optional city/postcode/type), returns *every* real verified signal Gera holds — FSA hygiene rating, CQC registration, Gera verified-provider presence — each source-attributed. Returns `overall_verification` = `verified` or `not_in_our_records`. |
+| `lookup_food_hygiene` | Real FSA food-hygiene rating for a UK food business: FHRS 0–5 (England/Wales/NI) or FHIS Pass/Improvement-Required (Scotland), with establishment, business type, local authority, and rating date. |
+| `lookup_care_rating` | Confirms a UK care/health provider is in the **CQC** registry; returns registered name, address, service types, last-inspection date, region, and a link to the live CQC profile. CQC's overall rating is **categorical** (Outstanding/Good/Requires improvement/Inadequate) and not in this snapshot, so it is honestly returned as `unknown` with a live link. |
+| `verify_provider` | Checks Gera's own crawled **verified-provider / Passport** set; returns type, specialty, location, website, crawl source + date. |
+| `get_trust_summary` | Aggregates the above into a short, **citation-ready sentence** (plus structured signals) for an agent to quote a grounded "what we can verify about X" answer. |
+| `issue_attestation` | **Gera Vouch.** Runs the same real verification and returns a **cryptographically signed (Ed25519) attestation receipt** an agent can present to a counterparty (who verifies it with the public key). Verdict is `pass` (a strong, source-attributed verifying signal exists) or `unverified` (not in our records — never a guess). A signed *proof-of-diligence receipt*; indemnity/underwriting is roadmap and is never implied. |
+| `get_vouch_public_key` | Returns the Ed25519 public key + `key_id` + verification recipe so **any party can independently verify** an `issue_attestation` receipt without trusting the transport. |
+
+A typical agent flow: `check_business_trust` (or `get_trust_summary`) → drill
+into `lookup_food_hygiene` / `lookup_care_rating` / `verify_provider` for the
+source-attributed detail behind any signal → `issue_attestation` to get a
+**signed receipt** before the agent acts (book / pay / recommend).
+
+### Gera Vouch — signed attestations (the agent trust layer)
+
+`issue_attestation` is the keystone of [Gera Labs](https://gera.services/labs)'
+agent-trust spine: AI agents can't be liable, so before an agent takes a
+real-world action it calls Vouch for a signed verdict it (and the counterparty)
+can verify. The signature covers the canonical (sorted-key UTF-8) JSON of the
+`attestation` object; verify with the key from `get_vouch_public_key`. Set
+`GERA_VOUCH_SEED` (base64, 32+ bytes) in production; without it a deterministic,
+stable **dev** key is used so signatures verify out-of-the-box (`is_production_key`
+flags which). Vouch only attests a `pass` on a **strong** name match (the record
+name contains the full query), stricter than the read-only lookup tools.
+
+## Install & run
+
+```bash
+# Run directly (no global install) once published to npm:
+npx -y @gera-services/mcp-gera-verify
+
+# Or from this repo:
+cd packages/mcp-gera-verify
+npm run build:data   # extract the real on-disk datasets -> src/data/*.json (committed)
+npm run build        # tsc --noCheck -> dist/  + copy datasets to dist/data
+node bin/cli.js      # starts on stdio
+```
+
+> The datasets are committed (`src/data/*.json`), so you only need
+> `npm run build:data` if you want to re-snapshot from the latest
+> `apps/*/src/data/*.generated.ts` sources.
+
+## Client configuration
+
+### Claude Desktop / Claude Code (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "gera-verify": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-gera-verify"]
+    }
+  }
+}
+```
+
+Local (unpublished) variant — point at the built CLI:
+
+```json
+{
+  "mcpServers": {
+    "gera-verify": {
+      "command": "node",
+      "args": ["/Users/armen/Gera/packages/mcp-gera-verify/bin/cli.js"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf (`.cursor/mcp.json` etc.)
+
+```json
+{
+  "mcpServers": {
+    "gera-verify": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-gera-verify"]
+    }
+  }
+}
+```
+
+## Hosted transport (Streamable HTTP / SSE — for ChatGPT Apps & remote MCP clients)
+
+**Live now:** `https://gera-verify-mcp-production.up.railway.app/mcp`
+(POST JSON-RPC, `Accept: application/json, text/event-stream`; `GET /health` →
+`ok`). All 7 tools — including the signed `issue_attestation` (Gera Vouch) — are
+callable over HTTP today, no install. A branded `verify-mcp.gera.services`
+domain is next.
+
+The same seven tools are served over the MCP **Streamable HTTP** transport, so
+remote MCP clients and **ChatGPT Apps** can connect to a public URL instead of
+spawning a local stdio process. The HTTP server reuses the exact same tool
+handlers — it just swaps the transport.
+
+```bash
+cd packages/mcp-gera-verify
+npm run build           # tsc --noCheck -> dist/ (builds both transports)
+npm run start:http      # or: node bin/http.js
+# -> listening on http://0.0.0.0:3400/mcp  (POST JSON-RPC; GET /health)
+```
+
+Endpoints:
+
+| Method & path | Purpose |
+|---|---|
+| `POST /mcp` | MCP JSON-RPC (and SSE streaming). This is the MCP endpoint clients connect to. |
+| `GET /health` | Plain-text liveness probe (`ok`) — exempt, never gated. |
+| `GET /mcp` | `405` — stateless mode has no server-initiated stream to open. |
+
+It runs **stateless** (a fresh server per request, no session id) — correct for
+a read-only, offline lookup service with no cross-call state, and safe to host
+behind a serverless function or a horizontally-scaled container.
+
+Configure host/port via env vars: `PORT` (or `MCP_HTTP_PORT`, default `3400`)
+and `HOST` (default `0.0.0.0`).
+
+### Connecting a remote MCP client
+
+```json
+{
+  "mcpServers": {
+    "gera-verify": {
+      "type": "streamable-http",
+      "url": "https://verify.gera.services/mcp"
+    }
+  }
+}
+```
+
+For **ChatGPT Apps** / remote-MCP connectors, register the same
+`https://verify.gera.services/mcp` URL as the server endpoint. No auth is
+required — the lookups are read-only and offline.
+
+> Quick check once running:
+> `curl -s http://localhost:3400/health` → `ok`
+> `curl -s -X POST http://localhost:3400/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'`
+
+## Verify it works
+
+```bash
+npm run build
+node scripts/smoke.mjs
+```
+
+The smoke test speaks raw MCP JSON-RPC over stdio (`initialize` → `tools/list`
+→ several `tools/call` against **real** records) and asserts the responses,
+including the honesty checks (a fake business → `not_in_our_records`; CQC
+categorical rating → `unknown`, never invented). Expected output ends with
+`ALL SMOKE CHECKS PASSED`.
+
+## Example
+
+Ask your agent: *"Is Etci Mehmet Steak House in Birmingham a real, hygienic
+restaurant?"*
+
+The agent calls `check_business_trust` / `lookup_food_hygiene` and gets back:
+
+```json
+{
+  "found": true,
+  "best_match": {
+    "establishment": "Etci Mehmet Steak House",
+    "address": "Unit 16, Star City, Watson Road, Birmingham",
+    "postcode": "B7 5SA",
+    "businessType": "Restaurant/Cafe/Canteen",
+    "localAuthority": "Birmingham",
+    "scheme": "FHRS",
+    "rating": 5,
+    "rating_date": "2026-05-29",
+    "source": "Source: FSA Food Hygiene Rating Scheme, local authority \"Birmingham\", as of 2026-06-12."
+  }
+}
+```
+
+## Data & attribution
+
+- **FSA FHRS/FHIS** — Contains public sector information licensed under the Open
+  Government Licence v3.0. <https://ratings.food.gov.uk>
+- **CQC** — Source: Care Quality Commission www.cqc.org.uk. Licensed under the
+  Open Government Licence v3.0.
+- **Gera verified-provider set** — Gera's own supplier crawler.
+- **Doctor listings** — public Practo professional profiles.
+
+Snapshots are extracted by `scripts/build-data.mjs` from the same on-disk
+`*.generated.ts` files that GeraEats and GeraClinic render — no data is
+invented; every record traces to a source row.
+
+## License
+
+MIT © Gera Systems Ltd

package/bin/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the Gera Verify MCP server.
+ * Starts the server on stdio. Intended to be launched by an MCP client
+ * (Claude Desktop, ChatGPT-with-tools, Cursor, etc.) — not run interactively.
+ */
+import { main } from '../dist/server.js';
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/bin/http.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the HOSTED Gera Verify MCP server.
+ * Starts the Streamable HTTP / SSE transport so remote MCP clients and
+ * ChatGPT Apps can connect over HTTP. Listens on PORT (default 3400) at /mcp.
+ */
+import { main } from '../dist/http.js';
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});