fastspring-mcp 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# FastSpring MCP Server
+
+MCP server that connects Claude (or any MCP client) to the FastSpring API. Look up subscriptions, accounts, and webhook events through natural language.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_subscription` | Get subscription details by ID |
+| `list_subscriptions` | List/filter subscriptions by account, status, date range |
+| `list_subscription_entries` | Payment history for a subscription |
+| `search_accounts` | Find accounts by email |
+| `get_account` | Get account details by ID |
+| `list_events` | List webhook events (up to 30 days) |
+| `get_event` | Get full event payload by ID |
+
+## Setup
+
+Requires Node.js 22+ and FastSpring API credentials.
+
+Set env vars in your shell profile:
+
+```bash
+export FASTSPRING_API_USERNAME=your_username
+export FASTSPRING_API_PASSWORD=your_password
+```
+
+### Claude Code
+
+```bash
+claude mcp add fastspring -- npx fastspring-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fastspring": {
+      "command": "npx",
+      "args": ["fastspring-mcp"],
+      "env": {
+        "FASTSPRING_API_USERNAME": "your_username",
+        "FASTSPRING_API_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/fastspring-api.ts

@@ -0,0 +1,101 @@
+const BASE_URL = "https://api.fastspring.com";
+
+let authHeader: string | undefined;
+
+export function initAuth(username: string, password: string): void {
+  authHeader = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+}
+
+// Validate ID parameters to prevent path traversal
+function validateId(id: string, label: string): void {
+  if (!/^[\w-]+$/.test(id)) {
+    throw new Error(`Invalid ${label}: must be alphanumeric (got "${id}")`);
+  }
+}
+
+async function request(path: string, params?: Record<string, string>): Promise<unknown> {
+  if (!authHeader) throw new Error("FastSpring API not initialized — call initAuth() first.");
+  const url = new URL(path, BASE_URL);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== "") url.searchParams.set(k, v);
+    }
+  }
+
+  const res = await fetch(url.toString(), {
+    headers: {
+      Authorization: authHeader,
+      "User-Agent": "fastspring-mcp/1.0",
+      Accept: "application/json",
+    },
+  });
+
+  if (res.status === 429) {
+    throw new Error("FastSpring rate limit exceeded (250/min). Wait a moment and retry.");
+  }
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`FastSpring API error (${res.status})`);
+  }
+
+  return res.json();
+}
+
+// --- Subscriptions ---
+
+export async function getSubscription(subscriptionId: string): Promise<unknown> {
+  validateId(subscriptionId, "subscriptionId");
+  return request(`/subscriptions/${subscriptionId}`);
+}
+
+export async function listSubscriptions(filters: {
+  accountId?: string;
+  status?: string;
+  begin?: string;
+  end?: string;
+  limit?: number;
+}): Promise<unknown> {
+  const params: Record<string, string> = {};
+  if (filters.accountId) params.accountId = filters.accountId;
+  if (filters.status) params.status = filters.status;
+  if (filters.begin) params.begin = filters.begin;
+  if (filters.end) params.end = filters.end;
+  if (filters.limit) params.limit = String(filters.limit);
+  return request("/subscriptions", params);
+}
+
+export async function listSubscriptionEntries(subscriptionId: string): Promise<unknown> {
+  validateId(subscriptionId, "subscriptionId");
+  return request(`/subscriptions/${subscriptionId}/entries`);
+}
+
+// --- Accounts ---
+
+export async function searchAccounts(email: string): Promise<unknown> {
+  if (!email.trim()) throw new Error("email is required for account search");
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.trim())) throw new Error("invalid email format");
+  return request("/accounts", { email });
+}
+
+export async function getAccount(accountId: string): Promise<unknown> {
+  validateId(accountId, "accountId");
+  return request(`/accounts/${accountId}`);
+}
+
+// --- Events ---
+
+export async function listEvents(filters: {
+  days?: number;
+  type?: string;
+}): Promise<unknown> {
+  const params: Record<string, string> = {};
+  params.days = String(filters.days ?? 7);
+  if (filters.type) params.type = filters.type;
+  return request("/events", params);
+}
+
+export async function getEvent(eventId: string): Promise<unknown> {
+  validateId(eventId, "eventId");
+  return request(`/events/${eventId}`);
+}

package/index.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env node --experimental-strip-types
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  initAuth,
+  getSubscription,
+  listSubscriptions,
+  listSubscriptionEntries,
+  searchAccounts,
+  getAccount,
+  listEvents,
+  getEvent,
+} from "./fastspring-api.ts";
+
+// --- Init auth from env ---
+const username = process.env.FASTSPRING_API_USERNAME;
+const password = process.env.FASTSPRING_API_PASSWORD;
+
+if (!username || !password) {
+  console.error("Missing FASTSPRING_API_USERNAME or FASTSPRING_API_PASSWORD env vars");
+  process.exit(1);
+}
+
+initAuth(username, password);
+
+// --- Create server ---
+const server = new McpServer({
+  name: "fastspring",
+  version: "1.0.0",
+});
+
+// --- Helper to format tool responses ---
+function ok(data: unknown): { content: Array<{ type: "text"; text: string }> } {
+  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+}
+
+function err(error: unknown): { content: Array<{ type: "text"; text: string }>; isError: true } {
+  const message = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text" as const, text: message }], isError: true };
+}
+
+// --- Register tools ---
+
+server.tool(
+  "get_subscription",
+  "Get full subscription details by FastSpring subscription ID. Returns status, product, next charge date, pricing, account, and tags (referrer = LinkStorm user ID).",
+  { subscriptionId: z.string().describe("FastSpring subscription ID") },
+  async ({ subscriptionId }) => {
+    try {
+      return ok(await getSubscription(subscriptionId));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+server.tool(
+  "list_subscriptions",
+  "List subscriptions with optional filters. Use accountId to find all subs for a customer.",
+  {
+    accountId: z.string().optional().describe("FastSpring account ID"),
+    status: z.enum(["active", "canceled", "deactivated", "overdue", "trial"]).optional().describe("Subscription status filter"),
+    begin: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+    end: z.string().optional().describe("End date (YYYY-MM-DD)"),
+    limit: z.number().min(1).max(100).optional().default(25).describe("Max results (default 25, max 100)"),
+  },
+  async (filters) => {
+    try {
+      return ok(await listSubscriptions(filters));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+server.tool(
+  "list_subscription_entries",
+  "Get charge/payment history for a subscription. Shows successful charges, failed payments, refunds. Use to distinguish voluntary churn (canceled) from involuntary churn (payment failure).",
+  { subscriptionId: z.string().describe("FastSpring subscription ID") },
+  async ({ subscriptionId }) => {
+    try {
+      return ok(await listSubscriptionEntries(subscriptionId));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+server.tool(
+  "search_accounts",
+  "Search FastSpring accounts by email. This is the entry point for debugging — you typically start from a customer email, not a FastSpring ID.",
+  { email: z.string().describe("Customer email to search for") },
+  async ({ email }) => {
+    try {
+      return ok(await searchAccounts(email));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+server.tool(
+  "get_account",
+  "Get full account details by FastSpring account ID. Returns email, name, address, and associated subscriptions.",
+  { accountId: z.string().describe("FastSpring account ID") },
+  async ({ accountId }) => {
+    try {
+      return ok(await getAccount(accountId));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+server.tool(
+  "list_events",
+  "List FastSpring webhook events. Use for webhook gap analysis — comparing what FastSpring sent vs what Symfony processed. Note: 'processed' means delivered to your endpoint, NOT successfully handled by your code.",
+  {
+    days: z.number().min(1).max(30).optional().default(7).describe("Number of days to look back (max 30, default 7)"),
+    type: z.string().optional().describe("Event type filter, e.g. 'subscription.deactivated', 'subscription.activated'"),
+  },
+  async (filters) => {
+    try {
+      return ok(await listEvents(filters));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+server.tool(
+  "get_event",
+  "Get full webhook event payload by event ID. Use after list_events to inspect the complete data FastSpring sent.",
+  { eventId: z.string().describe("FastSpring event ID") },
+  async ({ eventId }) => {
+    try {
+      return ok(await getEvent(eventId));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+
+// --- Start server ---
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "fastspring-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the FastSpring API — manage subscriptions, accounts, and webhook events from Claude",
+  "type": "module",
+  "bin": {
+    "fastspring-mcp": "index.ts"
+  },
+  "files": [
+    "index.ts",
+    "fastspring-api.ts"
+  ],
+  "scripts": {
+    "start": "node --experimental-strip-types index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "fastspring", "claude", "mcp-server"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ssv445/fastspring-mcp-server.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  }
+}