Merge pull request #16 from Affitor/feat/recipe-registry-mcp-plan

feat(recipes): canonical recipe registry + MCP get_integration_plan (#5+#7)

Author: sonpiaz

package-lock.json

@@ -5,6 +5,7 @@
   "description": "Affitor CLI (affitor). The SDK now ships separately as @affitor/sdk.",
   "type": "module",
   "workspaces": [
+    "packages/recipes",
     "packages/cli",
     "packages/mcp"
   ],

package.json

@@ -44,7 +44,8 @@
     "@inquirer/prompts": "^7.5.0",
     "picocolors": "^1.1.1",
     "open": "^10.1.0",
-    "stripe": "^17.7.0"
+    "stripe": "^17.7.0",
+    "@affitor/recipes": "*"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

packages/cli/package.json

@@ -1,11 +1,16 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { getRecipe, type Provider as RecipeProvider } from "@affitor/recipes";
 
 /**
  * Server-side conversion tracking helpers for the wizard (@affitor/sdk/server path).
  * Pure functions (detection + generated source/snippets) — easy to unit test.
  * The wizard installs @affitor/sdk + scaffolds the client file, then PRINTS the
  * trackLead/trackSale snippets — it never edits auth/payment code (per PR-4 §9.3).
+ *
+ * The per-provider `sale` snippet is SOURCED FROM `@affitor/recipes` (the canonical
+ * single source of truth read by CLI + MCP + docs). Do NOT re-inline the snippet
+ * strings here — edit them in `@affitor/recipes` so all three surfaces stay in sync.
  */
 
 export type PaymentProvider = "stripe" | "polar" | "lemonsqueezy" | "paddle" | "unknown";
@@ -52,6 +57,19 @@ export interface TrackingSnippets {
   refund: string;
 }
 
+/**
+ * The trackSale snippet body for a provider, sourced from the canonical
+ * `@affitor/recipes` registry. We use framework "unknown" (the snippet body is
+ * framework-independent) + mode "s2s" (so a sale snippet exists, not the
+ * Connect/metadata-only path), then strip the leading `@affitor/sdk/server`
+ * import + its blank line — the wizard prints that import via the lead snippet.
+ */
+function recipeSaleBody(provider: PaymentProvider): string {
+  const recipe = getRecipe("unknown", provider as RecipeProvider, "s2s");
+  const snippet = recipe.sale?.snippet ?? "";
+  return snippet.replace(/^import \{ Affitor \} from '@affitor\/sdk\/server';\n\n/, "");
+}
+
 /**
  * Tailored trackLead + trackSale snippets. The sale snippet is provider-specific
  * (event name + field paths from the verified provider research). Printed, not
@@ -67,60 +85,30 @@ export function serverTrackingSnippets(
     `await affitor.trackLead({ customerExternalId: user.id, clickId: cookies.affitor_click_id });`,
   ].join("\n");
 
+  // The trackSale snippet body is canonical in @affitor/recipes. We pull it from
+  // there (framework "unknown" — the body is framework-independent; only the
+  // inject_target differs, which the wizard doesn't print) and strip the SDK
+  // import line the recipe prepends (the wizard already prints the import as part
+  // of the lead snippet, via `importPath`).
+  const sale = recipeSaleBody(provider);
+
   let saleContext: string;
-  let sale: string;
   switch (provider) {
     case "polar":
       saleContext = "in your Polar webhook handler (event 'order.paid')";
-      sale = [
-        `await affitor.trackSale({`,
-        `  customerExternalId: order.metadata.user_id ?? order.customer_id,`,
-        `  amount: order.total_amount,        // integer cents`,
-        `  invoiceId: order.id,`,
-        `  saleType: order.subscription_id ? 'subscription' : 'payment',`,
-        `});`,
-      ].join("\n");
       break;
     case "lemonsqueezy":
       saleContext = "in your Lemon Squeezy webhook handler (event 'order_created')";
-      sale = [
-        `await affitor.trackSale({`,
-        `  customerExternalId: payload.meta.custom_data?.user_id ?? data.attributes.user_email,`,
-        `  amount: data.attributes.total,     // integer cents`,
-        `  invoiceId: String(data.id),`,
-        `});`,
-      ].join("\n");
       break;
     case "paddle":
       saleContext = "in your Paddle webhook handler (event 'transaction.completed')";
-      sale = [
-        `await affitor.trackSale({`,
-        `  customerExternalId: data.custom_data?.user_id,`,
-        `  amount: Number(data.details.totals.total),   // cents`,
-        `  invoiceId: data.id,`,
-        `});`,
-      ].join("\n");
       break;
     case "stripe":
       saleContext =
         "Stripe: prefer Connect autocapture (`affitor stripe connect`). To track manually, in your checkout.session.completed handler";
-      sale = [
-        `await affitor.trackSale({`,
-        `  customerExternalId: session.client_reference_id,`,
-        `  amount: session.amount_total,      // cents`,
-        `  invoiceId: session.id,`,
-        `});`,
-      ].join("\n");
       break;
     default:
       saleContext = "in your payment provider's webhook handler, when a payment succeeds";
-      sale = [
-        `await affitor.trackSale({`,
-        `  customerExternalId: user.id,`,
-        `  amount: amountInCents,`,
-        `  invoiceId: transactionId,`,
-        `});`,
-      ].join("\n");
   }
 
   const refund = [

packages/cli/src/lib/server-tracking.ts

@@ -49,6 +49,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@affitor/sdk": "^2.1.0",
+    "@affitor/recipes": "*",
     "zod": "^3.23.8"
   },
   "devDependencies": {

packages/mcp/package.json

@@ -29,6 +29,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { Affitor } from '@affitor/sdk/server';
+import { getIntegrationPlan } from '@affitor/recipes';
 
 /**
  * The subset of the `Affitor` client the MCP tools depend on. Declaring it here
@@ -77,8 +78,12 @@ async function runCall(fn: () => Promise<unknown>): Promise<CallToolResult> {
 }
 
 /**
- * Register the 5 Affitor tools on an MCP server. Exported for unit testing the
+ * Register the 6 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.
  */
 export function registerTools(server: McpServer, affitor: AffitorLike): void {
   server.registerTool(
@@ -217,6 +222,39 @@ export function registerTools(server: McpServer, affitor: AffitorLike): void {
         }),
       ),
   );
+
+  server.registerTool(
+    'affitor_get_integration_plan',
+    {
+      description:
+        'Return the deterministic Affitor payment-tracking integration plan for a given stack — the install, the checkout-metadata snippet, the trackSale snippet + where to inject it, and the self-verify step. The agent follows this instead of guessing a contract.',
+      inputSchema: {
+        framework: z
+          .enum(['next-app', 'next-pages', 'fastify', 'express', 'node', 'unknown'])
+          .describe('The detected app framework. Determines where trackSale is injected.'),
+        provider: z
+          .enum(['stripe', 'polar', 'lemonsqueezy', 'paddle', 'unknown'])
+          .default('stripe')
+          .describe('The detected payment provider.'),
+        mode: z
+          .enum(['stripe_connect', 's2s'])
+          .optional()
+          .default('stripe_connect')
+          .describe(
+            "Payment-tracking mode. 'stripe_connect' (default) = Connect autocaptures the sale (metadata only, no trackSale); 's2s' = inject trackSale in your webhook.",
+          ),
+      },
+    },
+    async (args) => {
+      // Pure: reads the canonical recipe registry. No SDK client, no network.
+      const plan = getIntegrationPlan({
+        framework: args.framework,
+        provider: args.provider,
+        mode: args.mode,
+      });
+      return ok(plan);
+    },
+  );
 }
 
 /** Read the server version from this package's package.json at runtime. */

packages/mcp/src/index.ts

@@ -17,6 +17,7 @@ const EXPECTED_TOOLS = [
   'affitor_track_sale',
   'affitor_track_refund',
   'affitor_track_click',
+  'affitor_get_integration_plan',
 ] as const;
 
 // ── 1. Integration: spawn the BUILT server over stdio, drive with MCP Client ──
@@ -44,7 +45,7 @@ describe('@affitor/mcp stdio server (spawned, built dist)', () => {
     expect(info?.name).toBe('affitor');
   });
 
-  it('tools/list returns the 5 tools with input schemas', async () => {
+  it('tools/list returns the 6 tools with input schemas', async () => {
     const { tools } = await client.listTools();
     const names = tools.map((t) => t.name).sort();
     expect(names).toEqual([...EXPECTED_TOOLS].sort());
@@ -191,6 +192,48 @@ describe('@affitor/mcp tool handlers (stubbed client)', () => {
     await client.close();
   });
 
+  it('affitor_get_integration_plan returns a pure plan (no client call)', async () => {
+    const stub: AffitorLike = {
+      readiness: async () => {
+        throw new Error('readiness should not be called');
+      },
+      trackLead: async () => {
+        throw new Error('trackLead should not be called');
+      },
+      trackSale: async () => {
+        throw new Error('trackSale should not be called');
+      },
+      trackRefund: async () => {
+        throw new Error('trackRefund should not be called');
+      },
+      trackClick: async () => {
+        throw new Error('trackClick should not be called');
+      },
+    };
+
+    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_get_integration_plan',
+      arguments: { framework: 'fastify', provider: 'stripe', mode: 's2s' },
+    });
+    expect(res.isError).toBeFalsy();
+    const text = (res.content as { type: string; text: string }[])[0].text;
+    const plan = JSON.parse(text) as {
+      steps: string[];
+      recipe: { sale_path: string; sale: { inject_target: string } | null };
+    };
+    expect(plan.recipe.sale_path).toBe('webhook_sdk');
+    expect(plan.recipe.sale?.inject_target).toContain("fastify.post('/webhooks/stripe'");
+    expect(plan.steps).toHaveLength(5);
+
+    await client.close();
+  });
+
   it('affitor_track_lead rejects when neither customerExternalId nor clickId is given', async () => {
     const stub: AffitorLike = {
       readiness: async () => ({}) as never,

packages/mcp/tests/server.test.ts

@@ -0,0 +1,46 @@
+{
+  "name": "@affitor/recipes",
+  "version": "0.1.0",
+  "description": "Canonical per-stack payment-tracking recipe registry for Affitor — the single source of truth read by the CLI, the MCP server, and the docs. Pure data, no runtime deps.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "keywords": [
+    "affitor",
+    "recipes",
+    "affiliate",
+    "tracking",
+    "payment",
+    "integration",
+    "agent"
+  ],
+  "author": "Affitor <hello@affitor.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Affitor/cli"
+  },
+  "homepage": "https://affitor.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0",
+    "@types/node": "^22.0.0"
+  }
+}