agent-services-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth1953
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# agent-services-mcp
+
+A single **thin MCP (Model Context Protocol) server** that exposes two existing
+services as discoverable tools, so AI agents and MCP-compatible clients can find
+and use them through one connection:
+
+- **[provenance-receipts](https://github.com/Gareth1953/provenance-receipts)** — certifies content **origin**;
+  returns an Ed25519-signed receipt.
+- **[quality-gate](https://github.com/Gareth1953/quality-gate)** — scores content **quality** against a
+  published rubric; returns an Ed25519-signed score receipt.
+
+> **It is a thin wrapper.** Every tool forwards an HTTP call to the underlying
+> Worker and returns its response verbatim. It does **not** reimplement signing,
+> scoring, or payment logic — those live in the two services. The honesty about
+> what each service proves carries through to the tool descriptions.
+
+## What the wrapped services prove (and do not)
+
+- **Provenance:** proves the content is unmodified (SHA-256 hash) and the receipt
+  was issued by the service's key. The `generator_metadata` is **caller-attested**
+  — it proves you *claimed* it, not that a specific model ran. Not AI-detection,
+  not a truth guarantee.
+- **Quality:** a reproducible score **against the published rubric** (clarity,
+  completeness, internal consistency, obvious-error freedom). **Not** absolute
+  truth, **not** an external standard, **not** a fact-check. Read the rubric via
+  the `get_quality_rubric` tool.
+
+## Tools
+
+| Tool                 | Forwards to                              | Paid?      | Input |
+| -------------------- | ---------------------------------------- | ---------- | ----- |
+| `certify_provenance` | provenance-receipts `POST /v1/certify`   | yes (x402) | `content` (string), `generator_metadata` (object, optional) |
+| `verify_provenance`  | provenance-receipts `POST /v1/verify`    | no         | `content` (string), `receipt` (object) |
+| `score_quality`      | quality-gate `POST /v1/score`            | yes (x402) | `content` (string), `rubric_version` (string, optional), `target_score` (number 0–100, optional) |
+| `verify_quality`     | quality-gate `POST /v1/verify`           | no         | `content` (string), `receipt` (object) |
+| `get_quality_rubric` | quality-gate `GET /v1/rubric`            | no         | none |
+
+Full descriptions and Zod input schemas: [`src/tools.ts`](src/tools.ts). Each
+tool returns the service's raw JSON (or markdown, for the rubric) as text. A
+non-2xx response from a service (including a `402 Payment Required`) is surfaced
+with `isError: true` and the response body preserved, so the caller can react.
+
+## Configuration
+
+The two service URLs are environment-configurable (no secrets — just base URLs):
+
+| Env var            | Live (deployed)                                          | Local dev fallback        |
+| ------------------ | -------------------------------------------------------- | ------------------------- |
+| `PROVENANCE_URL`   | `https://provenance-receipts.gpmiddleton71.workers.dev`  | `http://localhost:8787`   |
+| `QUALITY_GATE_URL` | `https://quality-gate.gpmiddleton71.workers.dev`         | `http://localhost:8788`   |
+
+`.env.example` and the client config below point at the **live** deployments. If
+the vars are unset, the server falls back to localhost for local `wrangler dev`
+(both Workers default to `:8787`, so run quality-gate on `:8788` to avoid a clash).
+
+> Against the live services, the **paid** tools (`certify_provenance`,
+> `score_quality`) require x402 — this wrapper forwards the request and holds no
+> wallet, so without an `X-PAYMENT` they return a `402` (the payment requirements)
+> surfaced as `isError`. The free tools work as normal.
+
+## Quickstart (local)
+
+```bash
+# 1. Build the MCP server
+npm install
+npm run build            # -> dist/index.js
+
+# 2. In separate terminals, run the two services (free; payments off)
+#    (provenance-receipts) npm run dev                 # http://localhost:8787
+#    (quality-gate)        npx wrangler dev --port 8788 # http://localhost:8788
+
+# 3a. Smoke-test the free tool paths through an MCP stdio client
+node scripts/test-client.mjs
+
+# 3b. (optional, costs ~$0.012) prove the paid score_quality path end-to-end
+node scripts/test-score.mjs
+
+# 3c. Smoke-test the wrapper against the LIVE deployed services (free — the
+#     paid tools return a forwarded 402; no payment, no scoring call)
+node scripts/test-live.mjs
+```
+
+`scripts/test-client.mjs` exercises the free tools locally; `scripts/test-score.mjs`
+makes one real Anthropic scoring call through `score_quality`;
+`scripts/test-live.mjs` points the wrapper at the deployed workers.dev URLs and
+asserts the free tools work and the paid tools forward the x402 `402`.
+
+## Connecting an MCP client (stdio)
+
+This server speaks MCP over **stdio** (stdin/stdout). Any MCP client launches it
+as a subprocess. Example for a Claude Desktop / Claude Code style
+`mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "agent-services": {
+      "command": "node",
+      "args": ["C:\\Users\\Gareth\\agent-services-mcp\\dist\\index.js"],
+      "env": {
+        "PROVENANCE_URL": "https://provenance-receipts.gpmiddleton71.workers.dev",
+        "QUALITY_GATE_URL": "https://quality-gate.gpmiddleton71.workers.dev"
+      }
+    }
+  }
+}
+```
+
+- Run `npm run build` first so `dist/index.js` exists.
+- The client connects, calls `tools/list` (it will see the 5 tools above), and
+  invokes them via `tools/call`.
+- The underlying services must be reachable at the configured URLs when a tool is
+  called.
+- Logs go to **stderr**; stdout is reserved for the MCP protocol.
+
+Programmatically, connect with the SDK's `Client` + `StdioClientTransport`
+(`command: "node"`, `args: ["dist/index.js"]`) — see `scripts/test-client.mjs`.
+
+## x402 payments (forwarded, not handled here)
+
+The paid endpoints (`/v1/certify`, `/v1/score`) are gated by
+[x402](https://github.com/coinbase/x402) on the underlying services. This wrapper
+**forwards** requests and does not hold a wallet. If a service has payments
+enabled and no valid `X-PAYMENT` is supplied, it returns `402` with the payment
+requirements — the wrapper surfaces that as `isError` with the requirements body
+intact. Settling a payment (signing an x402 authorization) is the client's
+responsibility against the underlying service. See each service's `README.md` /
+`docs/API.md` for the x402 details. **Base Sepolia testnet only — no mainnet.**
+
+## Verifying receipts independently
+
+The receipts returned by `certify_provenance` and `score_quality` are
+Ed25519-signed and verifiable **without trusting any of these services** — re-hash
+the content and check the signature against the service's public key. Each service
+ships a runnable independent verifier and recipe: see
+[provenance-receipts/docs/VERIFYING.md](https://github.com/Gareth1953/provenance-receipts/blob/main/docs/VERIFYING.md)
+and [quality-gate/docs/VERIFYING.md](https://github.com/Gareth1953/quality-gate/blob/main/docs/VERIFYING.md).
+
+## Build status
+
+- [x] **Step 1 — skeleton + tool definitions** (`src/tools.ts`)
+- [x] **Step 2 — tool handlers (HTTP forwarding) + local smoke test**
+- [x] **Step 3 — README: what it is, the tools, and how an MCP client connects**
+- [x] **Live — pointed at the deployed services** (`*.gpmiddleton71.workers.dev`)
+      and verified end-to-end via `scripts/test-live.mjs`: free tools work; paid
+      tools forward the x402 `402`.
+
+All five tool paths verified locally (including one paid `score_quality` call
+end-to-end through the wrapper) and against the live deployments.
+
+## Stack
+
+- Official MCP SDK: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
+  v1.29.0 (TypeScript), stdio transport, [`zod`](https://www.npmjs.com/package/zod)
+  input schemas.
+- Node ESM + TypeScript (`tsc` → `dist/`).
+
+## Project layout
+
+```
+agent-services-mcp/
+├── src/
+│   ├── index.ts     # MCP server: registers tools, forwards HTTP, stdio transport
+│   └── tools.ts     # the 5 tool definitions (names, descriptions, Zod schemas)
+├── scripts/
+│   ├── test-client.mjs  # MCP stdio client — free tool smoke test (local)
+│   ├── test-score.mjs   # MCP stdio client — one paid score_quality e2e check
+│   └── test-live.mjs    # MCP stdio client — against the live deployed services
+├── package.json
+├── tsconfig.json
+├── .gitignore
+└── .env.example     # PROVENANCE_URL, QUALITY_GATE_URL
+```

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// agent-services-mcp — MCP server entry point.
+//
+// A thin MCP server (official @modelcontextprotocol/sdk, stdio transport) that
+// exposes provenance-receipts and quality-gate as tools. Each handler forwards
+// an HTTP call to the relevant service; it does NOT reimplement service logic.
+//
+// IMPORTANT: stdout is the MCP protocol channel — all logging goes to stderr.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOLS } from "./tools.js";
+// Configurable base URLs of the two underlying services (default to local
+// `wrangler dev`; nothing is deployed to a public URL yet). No secrets here.
+export const PROVENANCE_URL = process.env.PROVENANCE_URL ?? "http://localhost:8787";
+export const QUALITY_GATE_URL = process.env.QUALITY_GATE_URL ?? "http://localhost:8788";
+function baseUrlFor(service) {
+    return (service === "provenance" ? PROVENANCE_URL : QUALITY_GATE_URL).replace(/\/$/, "");
+}
+// Forward a tool call to its underlying HTTP endpoint and wrap the response as
+// an MCP tool result. The raw response body is returned verbatim (JSON for the
+// API endpoints, markdown for /v1/rubric); a non-2xx status (incl. 402) sets
+// isError so the caller can react, with the body preserved.
+async function forward(tool, args) {
+    const url = baseUrlFor(tool.service) + tool.path;
+    try {
+        const init = {
+            method: tool.method,
+            signal: AbortSignal.timeout(30_000),
+        };
+        if (tool.method === "POST") {
+            init.headers = { "content-type": "application/json" };
+            init.body = JSON.stringify(args ?? {});
+        }
+        const res = await fetch(url, init);
+        const body = await res.text();
+        return {
+            content: [{ type: "text", text: body }],
+            isError: !res.ok,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to reach ${tool.service} service at ${url}: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+async function main() {
+    const server = new McpServer({
+        name: "agent-services-mcp",
+        version: "0.1.0",
+    });
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, (args) => forward(tool, (args ?? {})));
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`agent-services-mcp ready — ${TOOLS.length} tools | provenance=${PROVENANCE_URL} quality=${QUALITY_GATE_URL}`);
+}
+main().catch((err) => {
+    console.error("agent-services-mcp failed to start:", err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,139 @@
+// Tool definitions for the agent-services-mcp server.
+//
+// This file is the single source of truth for the tools this MCP server exposes.
+// Each entry maps a tool name -> an HTTP endpoint on one of the two underlying
+// services (provenance-receipts or quality-gate). Handlers that actually forward
+// the HTTP call are implemented in step 2; this file is definitions only.
+//
+// Descriptions are written to be HONEST and precise — they state what each
+// service proves AND what it does not, consistent with the services' own docs.
+import { z } from "zod";
+// A receipt is an arbitrary signed object returned by a service. We keep the
+// schema permissive (pass-through) — the wrapper does not re-validate receipt
+// internals; the underlying /v1/verify endpoint is the authority.
+const receiptShape = z
+    .record(z.unknown())
+    .describe("A signed receipt object exactly as returned by the service.");
+export const TOOLS = [
+    {
+        name: "certify_provenance",
+        title: "Certify content provenance",
+        service: "provenance",
+        method: "POST",
+        path: "/v1/certify",
+        paid: true,
+        description: "Certify the ORIGIN of a piece of content via the provenance-receipts service. " +
+            "Returns an Ed25519-signed receipt committing to a SHA-256 hash of the content, " +
+            "your caller-attested generator_metadata, and a service-set timestamp.\n\n" +
+            "PROVES: the content is unmodified (hash) and the receipt was issued by the holder " +
+            "of the service's signing key.\n" +
+            "DOES NOT PROVE: it does not independently verify generator_metadata — the receipt " +
+            "proves you CLAIMED that metadata at certification time, not that a specific model " +
+            "actually produced the content. This is proof-of-origin/tamper-evidence, not " +
+            "AI-detection and not a truth guarantee.\n\n" +
+            "Note: /v1/certify is the paid action; when the underlying service has x402 payments " +
+            "enabled it may require a micropayment. This wrapper forwards the request as-is.",
+        inputSchema: {
+            content: z
+                .string()
+                .min(1)
+                .describe("The exact content to certify. Non-empty."),
+            generator_metadata: z
+                .record(z.unknown())
+                .optional()
+                .describe("Optional caller-attested metadata about what generated the content " +
+                "(e.g. { model, provider }). Recorded verbatim; the receipt proves you " +
+                "claimed it, not that a specific model ran."),
+        },
+    },
+    {
+        name: "verify_provenance",
+        title: "Verify a provenance receipt",
+        service: "provenance",
+        method: "POST",
+        path: "/v1/verify",
+        paid: false,
+        description: "Verify a provenance receipt against its content via provenance-receipts. " +
+            "Re-hashes the content and checks the Ed25519 signature; returns { valid, details }. " +
+            "`valid` is true only if BOTH the content hash matches the receipt AND the signature " +
+            "is valid under the service's public key. Free. A 200 response means verification ran " +
+            "— always read `valid` (false means the content was modified or the receipt was " +
+            "altered/forged).",
+        inputSchema: {
+            content: z
+                .string()
+                .describe("The content to check against the receipt."),
+            receipt: receiptShape.describe("A provenance receipt as returned by certify_provenance."),
+        },
+    },
+    {
+        name: "score_quality",
+        title: "Score content against the published quality rubric",
+        service: "quality",
+        method: "POST",
+        path: "/v1/score",
+        paid: true,
+        description: "Score content against the quality-gate service's PUBLISHED rubric and get an " +
+            "Ed25519-signed score receipt. The rubric scores four dimensions — clarity, " +
+            "completeness, internal consistency, and obvious-error freedom (0–25 each, summing " +
+            "to 0–100) — plus flags from a closed vocabulary. Read the exact rubric with " +
+            "get_quality_rubric.\n\n" +
+            "WHAT THIS IS: a reproducible score AGAINST OUR PUBLISHED RUBRIC (vX).\n" +
+            "WHAT IT IS NOT: a measure of absolute truth, an external/third-party standard, or a " +
+            "fact-check — 'obvious-error freedom' catches errors evident from the text or common " +
+            "knowledge, not external verification.\n\n" +
+            "Optional target_score (0–100) enables 'no pass, no pay': if the score is below your " +
+            "target, no receipt is issued and (when payments are on) no charge is made — the " +
+            "response returns the failing breakdown with receipt: null.\n\n" +
+            "Note: /v1/score is the paid action (one Claude API scoring pass per call) and may " +
+            "require an x402 micropayment when the underlying service has payments enabled.",
+        inputSchema: {
+            content: z
+                .string()
+                .min(1)
+                .describe("The content to score. Non-empty."),
+            rubric_version: z
+                .string()
+                .optional()
+                .describe("Optional rubric version to score against; must match the service's current " +
+                "version (e.g. \"v1\") if provided."),
+            target_score: z
+                .number()
+                .min(0)
+                .max(100)
+                .optional()
+                .describe("Optional 0–100 threshold. Enables 'no pass, no pay': below this, no receipt " +
+                "is issued and no charge is made."),
+        },
+    },
+    {
+        name: "verify_quality",
+        title: "Verify a quality score receipt",
+        service: "quality",
+        method: "POST",
+        path: "/v1/verify",
+        paid: false,
+        description: "Verify a quality score receipt against its content via quality-gate. Re-hashes the " +
+            "content and checks the Ed25519 signature, which covers the score itself — so a " +
+            "forged or altered score fails. Returns { valid, details }. Free. A 200 response " +
+            "means verification ran — always read `valid`.",
+        inputSchema: {
+            content: z
+                .string()
+                .describe("The content the score receipt was issued for."),
+            receipt: receiptShape.describe("A quality score receipt as returned by score_quality."),
+        },
+    },
+    {
+        name: "get_quality_rubric",
+        title: "Get the published quality rubric",
+        service: "quality",
+        method: "GET",
+        path: "/v1/rubric",
+        paid: false,
+        description: "Fetch the published Quality Gate rubric (markdown) that score_quality grades " +
+            "against, along with its version. Read this to understand exactly what a quality " +
+            "score means and does not mean. Free; takes no input.",
+        inputSchema: {},
+    },
+];

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agent-services-mcp",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Thin MCP server exposing provenance-receipts and quality-gate as discoverable tools. Wraps the existing Workers over HTTP; does not reimplement their logic.",
+  "mcpName": "io.github.Gareth1953/agent-services-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gareth1953/agent-services-mcp.git"
+  },
+  "bin": { "agent-services-mcp": "dist/index.js" },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}