@verify-api/mcp 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# VerifyAPI MCP server
+
+A tiny stdio Model Context Protocol server that wraps the VerifyAPI REST endpoints. Install it into any MCP-capable client (Claude Desktop, Cursor, Windsurf, VS Code with the MCP extension, ChatGPT Desktop, custom agents built on the MCP SDKs) and the model gets one tool:
+
+- **`verify_claim`** — check a factual claim, get back `{verdict, confidence, source_url, exact_quote, published_date}`.
+
+The server is a thin adapter: your API key lives in the client's env, one HTTPS call per invocation, no state. Because it is the same account and same billing surface as REST callers, every MCP verification counts toward the same balance and idempotency semantics.
+
+## Install (Claude Desktop, Cursor, Windsurf)
+
+```bash
+npm install -g @verify-api/mcp   # (once published; for now, npm link from this dir)
+```
+
+Add to your MCP client config (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "verifyapi": {
+      "command": "verifyapi-mcp",
+      "env": {
+        "VERIFYAPI_API_KEY": "csk_live_...",
+        "VERIFYAPI_BASE_URL": "https://api.verify-api.dev"
+      }
+    }
+  }
+}
+```
+
+Restart the client. The `verify_claim` tool now shows up in the model's tool list.
+
+## Run from source (during development)
+
+```bash
+cd mcp
+npm install
+npm run build
+VERIFYAPI_API_KEY=csk_test_... VERIFYAPI_BASE_URL=http://localhost:8080 node dist/server.js
+```
+
+Then in your MCP client config point `command` at that `node dist/server.js` path.
+
+## What the model sees
+
+Tool name: `verify_claim`
+Tool description:
+> Verify a single factual claim against live web sources. Returns one of `supported`, `refuted`, `insufficient_evidence`, or `out_of_scope`, with confidence, a source URL, and a verbatim quote. Costs $0.02 per successful verification (unsupported/refuted); free otherwise. Use this when you need to check a specific fact before acting on it.
+
+Input schema:
+```json
+{
+  "claim": "string (a single factual claim, ideally < 300 chars)",
+  "as_of": "string (ISO date, optional — for time-sensitive facts)",
+  "max_wait_ms": "number (optional, default 15000)"
+}
+```
+
+Return value: the JSON body of `POST /v1/verify`, unmodified.

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// VerifyAPI MCP server (stdio transport).
+//
+// One tool: verify_claim. Stateless HTTPS wrapper over POST /v1/verify.
+// The user's API key is read from env; every call is billed to that account.
+// Because the MCP surface has no per-tool auth of its own, all we can do at
+// this layer is pass through the caller's key — no key, no tool.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { randomUUID } from "node:crypto";
+const API_KEY = process.env.VERIFYAPI_API_KEY;
+const BASE_URL = process.env.VERIFYAPI_BASE_URL?.replace(/\/$/, "") ?? "https://api.verify-api.dev";
+const DEFAULT_TIMEOUT_MS = 20_000;
+if (!API_KEY) {
+    // Write to stderr so the MCP client shows it in the connection error.
+    process.stderr.write("verifyapi-mcp: VERIFYAPI_API_KEY is not set. Add it to the mcpServers env block.\n");
+    process.exit(2);
+}
+const TOOLS = [
+    {
+        name: "verify_claim",
+        description: "Verify a single factual claim against live web sources. Returns one of `supported`, `refuted`, `insufficient_evidence`, or `out_of_scope`, with confidence, a source URL, published date, and a verbatim quote drawn from that source. Costs $0.02 per successful verification (supported/refuted); insufficient_evidence, out_of_scope, and malformed are free. Use this before acting on a specific fact you are not sure about.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                claim: {
+                    type: "string",
+                    description: "A single factual claim, ideally under 300 characters. If you have multiple claims, call verify_claim once per claim.",
+                },
+                as_of: {
+                    type: "string",
+                    description: "Optional ISO date (YYYY-MM-DD). Use for time-sensitive facts, e.g. prices or standings.",
+                },
+                max_wait_ms: {
+                    type: "number",
+                    description: "Optional soft deadline in milliseconds. Default 15000. If the pipeline cannot finish in time you'll get insufficient_evidence.",
+                },
+            },
+            required: ["claim"],
+            additionalProperties: false,
+        },
+    },
+];
+const server = new Server({ name: "verifyapi-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    if (req.params.name !== "verify_claim") {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+        };
+    }
+    const args = (req.params.arguments ?? {});
+    const claim = typeof args.claim === "string" ? args.claim.trim() : "";
+    if (!claim) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: "verify_claim requires a non-empty `claim` string." }],
+        };
+    }
+    const body = { claim };
+    if (typeof args.as_of === "string" && args.as_of.length > 0)
+        body.as_of = args.as_of;
+    if (typeof args.max_wait_ms === "number" && args.max_wait_ms > 0)
+        body.max_wait_ms = Math.min(args.max_wait_ms, 30_000);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), (Number(body.max_wait_ms) || DEFAULT_TIMEOUT_MS) + 5_000);
+    try {
+        const resp = await fetch(`${BASE_URL}/v1/verify`, {
+            method: "POST",
+            signal: controller.signal,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${API_KEY}`,
+                "idempotency-key": randomUUID(),
+                "user-agent": "verifyapi-mcp/0.1.0",
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await resp.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { raw: text };
+        }
+        if (!resp.ok) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `verifyapi ${resp.status}: ${JSON.stringify(parsed)}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [{ type: "text", text: `verifyapi request failed: ${msg}` }],
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+});
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@verify-api/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for VerifyAPI — one tool: verify_claim.",
+  "type": "module",
+  "bin": {
+    "verifyapi-mcp": "dist/server.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "dev": "tsx watch src/server.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}