feat(mcp): affitor_run_verification — fire the synthetic chain (G3)

The MCP could poll readiness but not TRIGGER the proof, so an MCP-driven
agent had to shell out to verify. Add affitor_run_verification: fires
POST /api/v1/cli/test-event {type:'chain'} (the real click->lead->sale
synthetic chain, isolated is_test rows) via an injected fetch helper
(the SDK's post is private). The agent now does detect -> wire -> verify
-> done entirely over MCP: run this, then poll affitor_readiness until
integration_verified:true. 429 (10/program/hour) returns
retry_after_seconds without throwing so the agent backs off.

Injected as registerTools(server, affitor, runVerification?) for
testability; absent => the tool returns a not-configured failure.
Tool count 6 -> 7. Build clean, suite 43/43.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sonpiaz

packages/mcp/src/index.ts

@@ -78,14 +78,60 @@ async function runCall(fn: () => Promise<unknown>): Promise<CallToolResult> {
 }
 
 /**
- * Register the 6 Affitor tools on an MCP server. Exported for unit testing the
+ * Fires Affitor's synthetic verification chain and resolves to the parsed body.
+ * Injected into `registerTools` so the `affitor_run_verification` handler stays
+ * unit-testable without a real network call.
+ */
+export type RunVerification = () => Promise<unknown>;
+
+/**
+ * POST `{base}/api/v1/cli/test-event` with `{ type: 'chain' }` to fire the
+ * synthetic click→lead→sale verification chain through Affitor's REAL
+ * attribution pipeline (isolated `is_test` rows).
+ *
+ * Returns the parsed JSON body for a 2xx response. For a non-2xx (including a
+ * 429 rate-limit), returns the parsed error body with the HTTP status merged in
+ * (`{ http_status, ...body }`) so the agent can read `retry_after_seconds` and
+ * back off — it does NOT throw on 429. Throws only on a network or JSON-parse
+ * failure, which `runCall` converts into an MCP error result.
+ */
+export async function fireVerificationChain(apiKey: string, apiUrl: string): Promise<unknown> {
+  const res = await fetch(`${apiUrl}/api/v1/cli/test-event`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ type: 'chain' }),
+  });
+
+  const body = (await res.json()) as Record<string, unknown>;
+
+  if (res.ok) {
+    return body;
+  }
+
+  // Non-2xx (incl. 429): merge the HTTP status in so the agent can read
+  // retry_after_seconds and back off rather than crash.
+  return { http_status: res.status, ...body };
+}
+
+/**
+ * Register the 7 Affitor tools on an MCP server. Exported for unit testing the
  * handlers with a stubbed `Affitor` client.
  *
  * Five tools wrap the `Affitor` client (readiness + track*). The sixth,
  * `affitor_get_integration_plan`, is PURE — it reads the canonical recipe
  * registry (`@affitor/recipes`) and never touches the client or the network.
+ * The seventh, `affitor_run_verification`, fires the synthetic verification
+ * chain via the injected `runVerification` (omitted → the tool degrades to a
+ * "not configured" failure).
  */
-export function registerTools(server: McpServer, affitor: AffitorLike): void {
+export function registerTools(
+  server: McpServer,
+  affitor: AffitorLike,
+  runVerification?: RunVerification,
+): void {
   server.registerTool(
     'affitor_readiness',
     {
@@ -255,6 +301,21 @@ export function registerTools(server: McpServer, affitor: AffitorLike): void {
       return ok(plan);
     },
   );
+
+  server.registerTool(
+    'affitor_run_verification',
+    {
+      description:
+        "Fire the synthetic click->lead->sale verification chain through Affitor's REAL attribution pipeline (isolated is_test rows). This is the agent's PROOF step: run it, then poll affitor_readiness until integration_verified:true. Rate-limited to 10/program/hour — on a rate_limited result, wait retry_after_seconds, don't hammer.",
+      inputSchema: {},
+    },
+    async () => {
+      if (!runVerification) {
+        return fail('affitor_run_verification is not configured in this MCP build');
+      }
+      return runCall(() => runVerification());
+    },
+  );
 }
 
 /** Read the server version from this package's package.json at runtime. */
@@ -284,8 +345,13 @@ async function main(): Promise<void> {
   const apiUrl = process.env.AFFITOR_API_URL;
   const affitor = new Affitor({ apiKey, ...(apiUrl ? { apiUrl } : {}) });
 
+  // Chain-firing isn't exposed by the SDK client (its `post` is private), so we
+  // fire the endpoint via a small authenticated fetch — injected for testability.
+  const runVerification: RunVerification = () =>
+    fireVerificationChain(apiKey, apiUrl ?? 'https://api.affitor.com');
+
   const server = new McpServer({ name: 'affitor', version: SERVER_VERSION });
-  registerTools(server, affitor);
+  registerTools(server, affitor, runVerification);
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

packages/mcp/tests/server.test.ts

@@ -18,6 +18,7 @@ const EXPECTED_TOOLS = [
   'affitor_track_refund',
   'affitor_track_click',
   'affitor_get_integration_plan',
+  'affitor_run_verification',
 ] as const;
 
 // ── 1. Integration: spawn the BUILT server over stdio, drive with MCP Client ──
@@ -45,7 +46,7 @@ describe('@affitor/mcp stdio server (spawned, built dist)', () => {
     expect(info?.name).toBe('affitor');
   });
 
-  it('tools/list returns the 6 tools with input schemas', async () => {
+  it('tools/list returns the 7 tools with input schemas', async () => {
     const { tools } = await client.listTools();
     const names = tools.map((t) => t.name).sort();
     expect(names).toEqual([...EXPECTED_TOOLS].sort());
@@ -234,6 +235,59 @@ describe('@affitor/mcp tool handlers (stubbed client)', () => {
     await client.close();
   });
 
+  it('affitor_run_verification returns the injected runVerification payload (no network)', async () => {
+    const stub: AffitorLike = {
+      readiness: async () => ({}) as never,
+      trackLead: async () => ({ ok: true, status: 200, data: null }),
+      trackSale: async () => ({ ok: true, status: 200, data: null }),
+      trackRefund: async () => ({ ok: true, status: 200, data: null }),
+      trackClick: async () => ({ ok: true, status: 200, data: null }),
+    };
+    const payload = {
+      data: {
+        type: 'chain',
+        verdict: { click: 'attributed', lead: 'attributed', sale: 'attributed' },
+        attributed: true,
+      },
+    };
+
+    const server = new McpServer({ name: 'affitor', version: '0.1.0' });
+    registerTools(server, stub, async () => payload);
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test', version: '0.0.0' });
+    await Promise.all([server.connect(st), client.connect(ct)]);
+
+    const res = await client.callTool({ name: 'affitor_run_verification', arguments: {} });
+    expect(res.isError).toBeFalsy();
+    const text = (res.content as { type: string; text: string }[])[0].text;
+    expect(JSON.parse(text)).toEqual(payload);
+
+    await client.close();
+  });
+
+  it('affitor_run_verification degrades to a not-configured failure when runVerification is absent', async () => {
+    const stub: AffitorLike = {
+      readiness: async () => ({}) as never,
+      trackLead: async () => ({ ok: true, status: 200, data: null }),
+      trackSale: async () => ({ ok: true, status: 200, data: null }),
+      trackRefund: async () => ({ ok: true, status: 200, data: null }),
+      trackClick: async () => ({ ok: true, status: 200, data: null }),
+    };
+
+    const server = new McpServer({ name: 'affitor', version: '0.1.0' });
+    registerTools(server, stub);
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test', version: '0.0.0' });
+    await Promise.all([server.connect(st), client.connect(ct)]);
+
+    const res = await client.callTool({ name: 'affitor_run_verification', arguments: {} });
+    expect(res.isError).toBe(true);
+    const text = (res.content as { type: string; text: string }[])[0].text;
+    expect(text).toBe('affitor_run_verification is not configured in this MCP build');
+
+    await client.close();
+  });
+
   it('affitor_track_lead rejects when neither customerExternalId nor clickId is given', async () => {
     const stub: AffitorLike = {
       readiness: async () => ({}) as never,