@usethrottle/mcp 0.1.0 → 0.2.0

package/dist/mcp.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync } from "fs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // ../errors/dist/index.js
@@ -504,6 +503,116 @@ var ACTIONS = [
     requests: [{ method: "GET", path: "/api/v1/invoices/aging" }],
     channels: ["mcp", "zapier", "make", "n8n"]
   },
+  // --------------------------------------------------------------- discounts
+  {
+    id: "search_discounts",
+    title: "Search discounts",
+    description: "List discount codes with optional filters \u2014 type, active state, and creation date range.",
+    kind: "read",
+    scopes: ["discounts:read"],
+    input: [
+      { name: "q", type: "string", required: false, description: "Free-text search." },
+      { name: "code", type: "string", required: false, description: "Exact code match." },
+      {
+        name: "type",
+        type: "string",
+        required: false,
+        description: "Filter by discount type.",
+        enum: ["percentage", "fixed_amount"]
+      },
+      { name: "isActive", type: "boolean", required: false, description: "Filter by active state." },
+      { name: "createdAfter", type: "string", required: false, description: "ISO 8601 date lower bound." },
+      { name: "createdBefore", type: "string", required: false, description: "ISO 8601 date upper bound." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/discounts" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_discount",
+    title: "Get one discount",
+    description: "Read a single discount code: value, conditions, usage limits and redemption count.",
+    kind: "read",
+    scopes: ["discounts:read"],
+    input: [{ name: "id", type: "string", required: true, description: "Discount id." }],
+    requests: [{ method: "GET", path: "/api/v1/discounts/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ---------------------------------------------------------------- payments
+  {
+    id: "search_payments",
+    title: "Search payments",
+    description: "List payments with optional filters \u2014 method, status, order, amount range, or a Net-N overdue bucket. Today payments are only reachable nested inside get_order; this is the standalone entry point.",
+    kind: "read",
+    scopes: ["payments:read"],
+    input: [
+      { name: "method", type: "string", required: false, description: "Filter by payment method." },
+      { name: "status", type: "string", required: false, description: "Filter by payment status." },
+      { name: "orderId", type: "string", required: false, description: "Filter to one order." },
+      {
+        name: "aging",
+        type: "string",
+        required: false,
+        description: "Overdue bucket filter, Net-N payments only.",
+        enum: ["0_30", "31_60", "61_90", "90_plus"]
+      },
+      { name: "dueFrom", type: "string", required: false, description: "Due-date range start, YYYY-MM-DD." },
+      { name: "dueTo", type: "string", required: false, description: "Due-date range end, YYYY-MM-DD." },
+      { name: "amountMin", type: "number", required: false, description: "Minimum amount, minor units." },
+      { name: "amountMax", type: "number", required: false, description: "Maximum amount, minor units." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/payments" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_payment",
+    title: "Get one payment with its transactions",
+    description: "Read a single payment plus its full transaction history (authorize/capture/refund/void attempts).",
+    kind: "read",
+    scopes: ["payments:read"],
+    input: [{ name: "id", type: "string", required: true, description: "Payment id." }],
+    requests: [
+      { method: "GET", path: "/api/v1/payments/:id" },
+      { method: "GET", path: "/api/v1/payments/:id/transactions" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "The transactions sub-read needs its own read of the same payment scope; report it as unavailable rather than failing the whole call if the underlying request errors."
+    ]
+  },
+  // ---------------------------------------------------------------- invoices
+  {
+    id: "get_invoice",
+    title: "Get one invoice",
+    description: "Read a single issued invoice: line items, totals, status and the billing snapshot at issue time.",
+    kind: "read",
+    scopes: ["invoices:read"],
+    input: [{ name: "id", type: "string", required: true, description: "Invoice id." }],
+    requests: [{ method: "GET", path: "/api/v1/invoices/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ------------------------------------------------------------------ carts
+  {
+    id: "list_abandoned_carts",
+    title: "List abandoned carts",
+    description: "Carts that were started but never finalized, with recovery status \u2014 the abandoned-cart recovery list.",
+    kind: "read",
+    scopes: ["carts:read"],
+    input: [
+      { name: "sinceDays", type: "number", required: false, description: "How many days back to look." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/abandoned-carts" },
+      { method: "GET", path: "/api/v1/abandoned-carts/summary" }
+    ],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: ["Report the summary as unavailable rather than failing the whole call if that sub-read errors."]
+  },
   // ---------------------------------------------------------------- debugging
   {
     id: "search_events",
@@ -526,7 +635,7 @@ var ACTIONS = [
     title: "List webhook deliveries",
     description: "Recent outbound webhook deliveries, filterable by endpoint and status.",
     kind: "read",
-    scopes: ["webhooks:read"],
+    scopes: ["webhook_deliveries:read"],
     input: [
       { name: "endpointId", type: "string", required: false, description: "Filter by endpoint." },
       { name: "status", type: "string", required: false, description: "Filter by delivery status." },
@@ -540,7 +649,7 @@ var ACTIONS = [
     title: "Get one webhook delivery",
     description: "Full delivery record: the signed payload we sent, the response we got back, and every attempt.",
     kind: "read",
-    scopes: ["webhooks:read"],
+    scopes: ["webhook_deliveries:read"],
     input: [{ name: "id", type: "string", required: true, description: "Delivery id." }],
     requests: [{ method: "GET", path: "/api/v1/webhook-deliveries/:id" }],
     channels: ["mcp", "n8n"]
@@ -570,6 +679,46 @@ var ACTIONS = [
       "Report which sections were unavailable rather than failing the call when a sub-read is unscoped."
     ]
   },
+  // ------------------------------------------------------------- extensions
+  {
+    id: "list_extension_installations",
+    title: "List installed extensions",
+    description: "Extensions installed on this application, with status and configuration.",
+    kind: "read",
+    scopes: ["extensions:read"],
+    input: [
+      {
+        name: "status",
+        type: "string",
+        required: false,
+        description: "Filter by installation status.",
+        enum: ["active", "suspended", "uninstalled"]
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/installations" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ------------------------------------------------------------- connectors
+  {
+    id: "get_connector_routing",
+    title: "Payment routing and decline rules",
+    description: "Read the payment-routing cascade, active routing connectors, and card/other decline rules \u2014 what determines which processor handles a payment and what happens on a decline.",
+    kind: "read",
+    scopes: ["connectors:read"],
+    input: [],
+    requests: [
+      { method: "GET", path: "/api/v1/payment-routing" },
+      { method: "GET", path: "/api/v1/routing-connectors" },
+      { method: "GET", path: "/api/v1/card-decline" },
+      { method: "GET", path: "/api/v1/other-decline" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "Every sub-read proxies live to the payment provider's routing API and none are guaranteed to succeed together; report any that fail as unavailable rather than failing the whole call."
+    ]
+  },
   {
     id: "get_integration_status",
     title: "Integration readiness",
@@ -588,6 +737,64 @@ var ACTIONS = [
       'Each section needs its own scope (connectors:read, webhooks:read). Report a section as "not readable with this credential" instead of failing.'
     ]
   },
+  // --------------------------------------------------------------- workspace
+  {
+    id: "get_workspace_settings",
+    title: "Get workspace settings",
+    description: "Read this workspace's identity and settings: name, slug, branding, onboarding state, and the default Net-N payment terms.",
+    kind: "read",
+    scopes: ["merchant:read"],
+    input: [],
+    requests: [{ method: "GET", path: "/api/v1/merchants/me" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_audit_log",
+    title: "Get the workspace audit log",
+    description: "Recent admin actions taken on this workspace \u2014 invites, billing changes, key rotation, suspensions.",
+    kind: "read",
+    scopes: ["audit_logs:read"],
+    input: [
+      { name: "limit", type: "number", required: false, description: "Maximum entries (1-200).", default: 100 }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/audit-log" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_business_summary",
+    title: "Business summary",
+    description: "How are we doing? Orders/revenue, subscription MRR, receivables and quotes pipeline for a week/month/quarter, always compared to the immediately preceding period of equal length.",
+    kind: "read",
+    scopes: [],
+    input: [
+      {
+        name: "period",
+        type: "string",
+        required: false,
+        description: "Reporting window.",
+        enum: ["week", "month", "quarter"],
+        default: "month"
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/business-summary" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Each section needs its own scope (orders:read, subscriptions:read, invoices:read, quotes:read). A section without its scope is reported as omitted rather than failing the whole call."
+    ]
+  },
+  {
+    id: "get_attention_digest",
+    title: "Attention digest",
+    description: "What needs attention right now? Open disputes, subscriptions in dunning, overdue Net-N invoices, and webhooks with degraded delivery health \u2014 a point-in-time snapshot, not a time range.",
+    kind: "read",
+    scopes: [],
+    input: [],
+    requests: [{ method: "GET", path: "/api/v1/analytics/attention-digest" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Each section needs its own scope (payment_disputes:read, subscriptions:read, invoices:read, webhook_deliveries:read). A section without its scope is reported as omitted rather than failing the whole call."
+    ]
+  },
   // ------------------------------------------------------------ sandbox write
   {
     id: "seed_test_data",
@@ -622,9 +829,9 @@ var ACTIONS = [
     scopes: ["quotes:write"],
     input: [
       { name: "customerId", type: "string", required: true, description: "Customer the quote is for." },
-      { name: "lineItems", type: "array", required: true, description: "Quote line items." },
+      { name: "items", type: "array", required: true, description: "Quote line items: { name, unitPrice, quantity }." },
       { name: "expiresAt", type: "string", required: false, description: "ISO 8601 expiry." },
-      { name: "netN", type: "number", required: false, description: "Payment terms in days." },
+      { name: "netN", type: "number", required: false, description: "Payment terms in days. Omit for pay-in-full." },
       { name: "notes", type: "string", required: false, description: "Buyer-visible notes." }
     ],
     requests: [{ method: "POST", path: "/api/v1/quotes" }],
@@ -715,7 +922,7 @@ var ACTIONS = [
     title: "Replay a webhook delivery",
     description: "Re-send a past webhook delivery to its endpoint \u2014 useful after fixing a broken handler.",
     kind: "write",
-    scopes: ["webhooks:write"],
+    scopes: ["webhook_deliveries:write"],
     input: [{ name: "id", type: "string", required: true, description: "Delivery id." }],
     requests: [{ method: "POST", path: "/api/v1/webhook-deliveries/:id/replay" }],
     channels: ["mcp", "n8n"],
@@ -1106,6 +1313,54 @@ var HANDLERS = {
   // ---------------------------------------------------------------- invoices
   list_invoices: async (ctx, args) => ctx.client.list("/api/v1/invoices", { status: args.status, ...page(args) }),
   receivables_aging: async (ctx) => ctx.client.get("/api/v1/invoices/aging"),
+  // --------------------------------------------------------------- discounts
+  search_discounts: async (ctx, args) => ctx.client.list("/api/v1/discounts", {
+    q: args.q,
+    code: args.code,
+    type: args.type,
+    isActive: args.isActive,
+    createdAfter: args.createdAfter,
+    createdBefore: args.createdBefore,
+    ...page(args)
+  }),
+  get_discount: async (ctx, args) => ctx.client.get(`/api/v1/discounts/${String(args.id)}`),
+  // ---------------------------------------------------------------- payments
+  search_payments: async (ctx, args) => ctx.client.list("/api/v1/payments", {
+    method: args.method,
+    status: args.status,
+    // The route only accepts these as snake_case query params -- confirmed
+    // by reading its querystring schema directly, not assumed from the
+    // platform's usual camelCase convention.
+    order_id: args.orderId,
+    aging: args.aging,
+    due_from: args.dueFrom,
+    due_to: args.dueTo,
+    amount_min: args.amountMin,
+    amount_max: args.amountMax,
+    ...page(args)
+  }),
+  get_payment: async (ctx, args) => {
+    const id = String(args.id);
+    const payment = await ctx.client.get(`/api/v1/payments/${id}`);
+    const transactions = await optional(() => ctx.client.list(`/api/v1/payments/${id}/transactions`));
+    return {
+      payment,
+      transactions: transactions.ok ? transactions.value.data : transactions.unavailable
+    };
+  },
+  // ---------------------------------------------------------------- invoices
+  get_invoice: async (ctx, args) => ctx.client.get(`/api/v1/invoices/${String(args.id)}`),
+  // ------------------------------------------------------------------ carts
+  list_abandoned_carts: async (ctx, args) => {
+    const [carts, summary] = await Promise.all([
+      optional(() => ctx.client.list("/api/v1/abandoned-carts", { ...page(args) })),
+      optional(() => ctx.client.get("/api/v1/abandoned-carts/summary", { sinceDays: args.sinceDays }))
+    ]);
+    return {
+      carts: carts.ok ? carts.value.data : carts.unavailable,
+      summary: summary.ok ? summary.value : summary.unavailable
+    };
+  },
   // --------------------------------------------------------------- debugging
   search_events: async (ctx, args) => ctx.client.list("/api/v1/events", {
     type: args.type,
@@ -1119,6 +1374,13 @@ var HANDLERS = {
     limit: args.limit
   }),
   get_webhook_delivery: async (ctx, args) => ctx.client.get(`/api/v1/webhook-deliveries/${String(args.id)}`),
+  send_test_webhook: async (ctx, args) => ctx.client.post(`/api/v1/webhook-endpoints/${String(args.id)}/test`, {
+    body: { eventType: args.eventType },
+    idempotencyKey: `mcp-send-test-webhook-${String(args.id)}-${Date.now()}`
+  }),
+  replay_webhook_delivery: async (ctx, args) => ctx.client.post(`/api/v1/webhook-deliveries/${String(args.id)}/replay`, {
+    idempotencyKey: `mcp-replay-webhook-delivery-${String(args.id)}-${Date.now()}`
+  }),
   explain_checkout_failure: async (ctx, args) => {
     const id = String(args.id);
     const session = await optional(() => ctx.client.get(`/api/v1/checkout-sessions/${id}`));
@@ -1163,7 +1425,11 @@ var HANDLERS = {
       idempotencyKey: `mcp-seed-customer-${stamp}`
     });
     const cart = await ctx.client.post("/api/v1/carts", {
-      body: { customerId: customer?.id },
+      // Unlike /api/v1/customers, cart creation requires applicationId
+      // explicitly in the body (it's cross-checked against the caller's own
+      // authenticated application, not inferred) -- omitting it is a real
+      // 400 missing_application_id from the live API, not a hypothetical.
+      body: { applicationId: ctx.identity.application?.id, customerId: customer?.id },
       idempotencyKey: `mcp-seed-cart-${stamp}`
     });
     const requested = Array.isArray(args.lineItems) && args.lineItems.length > 0 ? args.lineItems : [{ name: "Seed widget", unitPrice: 2500, quantity: 2 }];
@@ -1188,6 +1454,54 @@ var HANDLERS = {
       note: "Seeded a finalized DRAFT order. No payment was captured \u2014 that needs a browser-tokenised payment method, which a server-side key cannot produce."
     };
   },
+  // -------------------------------------------------------------- money/mail
+  manage_subscription: async (ctx, args) => {
+    const id = String(args.id);
+    const action = String(args.action);
+    if (action !== "pause" && action !== "resume") {
+      throw new Error(`manage_subscription: action must be "pause" or "resume", got "${action}".`);
+    }
+    return ctx.client.post(`/api/v1/subscriptions/${id}/${action}`, {
+      idempotencyKey: `mcp-manage-subscription-${id}-${action}-${Date.now()}`
+    });
+  },
+  create_quote: async (ctx, args) => (
+    // The real route's body shape differs from this tool's flatter,
+    // model-facing input: line items are "items" (not "lineItems"), Net-N
+    // terms are nested under paymentTerms.netN with an explicit mode (not a
+    // flat "netN"), and the buyer-visible note field is "buyerNote" (not
+    // "notes"). Confirmed against packages/platform-api/src/validation/quotes.ts's
+    // actual zod schema after a live call 400'd with unrecognized_keys.
+    ctx.client.post("/api/v1/quotes", {
+      body: {
+        customerId: args.customerId,
+        items: args.items,
+        expiresAt: args.expiresAt,
+        paymentTerms: args.netN !== void 0 ? { mode: "net_terms", netN: args.netN } : void 0,
+        buyerNote: args.notes
+      },
+      idempotencyKey: `mcp-create-quote-${String(args.customerId)}-${Date.now()}`
+    })
+  ),
+  get_business_summary: async (ctx, args) => ctx.client.get("/api/v1/analytics/business-summary", { period: args.period }),
+  get_attention_digest: async (ctx) => ctx.client.get("/api/v1/analytics/attention-digest"),
+  // ------------------------------------------------------------- extensions
+  list_extension_installations: async (ctx, args) => ctx.client.list("/api/v1/installations", { status: args.status, ...page(args) }),
+  // ------------------------------------------------------------- connectors
+  get_connector_routing: async (ctx) => {
+    const [paymentRouting, routingConnectors, cardDecline, otherDecline] = await Promise.all([
+      optional(() => ctx.client.get("/api/v1/payment-routing")),
+      optional(() => ctx.client.get("/api/v1/routing-connectors")),
+      optional(() => ctx.client.get("/api/v1/card-decline")),
+      optional(() => ctx.client.get("/api/v1/other-decline"))
+    ]);
+    return {
+      paymentRouting: paymentRouting.ok ? paymentRouting.value : paymentRouting.unavailable,
+      routingConnectors: routingConnectors.ok ? routingConnectors.value : routingConnectors.unavailable,
+      cardDecline: cardDecline.ok ? cardDecline.value : cardDecline.unavailable,
+      otherDecline: otherDecline.ok ? otherDecline.value : otherDecline.unavailable
+    };
+  },
   get_integration_status: async (ctx) => {
     const [connectors, endpoints, coverage] = await Promise.all([
       optional(() => ctx.client.list("/api/v1/connectors")),
@@ -1202,7 +1516,10 @@ var HANDLERS = {
       webhookEndpoints: endpoints.ok ? endpoints.value.data : endpoints.unavailable,
       unsubscribedEvents: coverage.ok ? coverage.value : coverage.unavailable
     };
-  }
+  },
+  // --------------------------------------------------------------- workspace
+  get_workspace_settings: async (ctx) => ctx.client.get("/api/v1/merchants/me"),
+  get_audit_log: async (ctx, args) => ctx.client.list("/api/v1/audit-log", { limit: args.limit })
 };
 
 // src/input.ts
@@ -1238,7 +1555,7 @@ function applyModifiers(field, type) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.1.0" : "0.0.0-dev";
+var VERSION = true ? "0.2.0" : "0.0.0-dev";
 function registerableActions(policy) {
   const isProduction = policy.identity.environment.providerEnvironment === "production";
   return actionsForChannel("mcp").filter((action) => {
@@ -1325,6 +1642,26 @@ function describeForModel(action) {
   return parts.join(" ");
 }
 
+// src/indexes.ts
+import { readFileSync } from "fs";
+function loadIndex(file, empty, label) {
+  try {
+    return JSON.parse(readFileSync(new URL(`./${file}`, import.meta.url), "utf8"));
+  } catch {
+    process.stderr.write(
+      `throttle-mcp: ${label} index missing (${file}); that tool will return no results. Run "pnpm --filter @usethrottle/mcp build:indexes".
+`
+    );
+    return empty;
+  }
+}
+function loadDocsIndex() {
+  return loadIndex("docs-index.json", { generatedAt: "", entries: [] }, "docs");
+}
+function loadContractIndex() {
+  return loadIndex("contract-index.json", { generatedAt: "", operations: [] }, "contract");
+}
+
 // src/index.ts
 var DEFAULT_API = "https://api.usethrottle.dev";
 function fail(message) {
@@ -1376,17 +1713,6 @@ function parseArgs(argv) {
     allowLiveWrites: args.includes("--allow-live-writes")
   };
 }
-function loadIndex(file, empty, label) {
-  try {
-    return JSON.parse(readFileSync(new URL(`./${file}`, import.meta.url), "utf8"));
-  } catch {
-    process.stderr.write(
-      `throttle-mcp: ${label} index missing (${file}); that tool will return no results. Run "pnpm --filter @usethrottle/mcp build:indexes".
-`
-    );
-    return empty;
-  }
-}
 async function main() {
   const options = parseArgs(process.argv);
   const client = new ThrottleClient({ apiKey: options.apiKey, apiBaseUrl: options.apiBaseUrl });
@@ -1399,12 +1725,8 @@ async function main() {
       `could not identify the credential via GET /api/v1/whoami (${e?.code ?? "error"}: ${e?.message ?? String(error)}). Check the key and --api URL.`
     );
   }
-  const docs = loadIndex("docs-index.json", { generatedAt: "", entries: [] }, "docs");
-  const contract = loadIndex(
-    "contract-index.json",
-    { generatedAt: "", operations: [] },
-    "contract"
-  );
+  const docs = loadDocsIndex();
+  const contract = loadContractIndex();
   const server = createServer({
     identity,
     client,