@armor/zuora-mcp 0.0.0-development

package/.env.example

@@ -0,0 +1,16 @@
+# Zuora OAuth Configuration
+# Required: OAuth2 Client ID (create at Zuora Admin > Settings > Administration > OAuth Clients)
+ZUORA_CLIENT_ID=your-oauth-client-id
+
+# Required: OAuth2 Client Secret
+ZUORA_CLIENT_SECRET=your-oauth-client-secret
+
+# Required: Zuora base URL for your environment
+# Production US:  https://rest.zuora.com
+# Sandbox US:     https://rest.apisandbox.zuora.com
+# Production EU:  https://rest.eu.zuora.com
+# Sandbox EU:     https://rest.sandbox.eu.zuora.com
+ZUORA_BASE_URL=https://rest.apisandbox.zuora.com
+
+# Optional: Enable debug logging (true/false)
+DEBUG=false

package/README.md

@@ -0,0 +1,249 @@
+# Zuora MCP Server
+
+A Model Context Protocol (MCP) server that enables Claude to interact with Zuora's billing platform. Query accounts, invoices, subscriptions, payments, and execute ZOQL queries directly from Claude Code.
+
+## Quick Start
+
+Run one command — no cloning, no building:
+
+```bash
+npx @armor/zuora-mcp setup
+```
+
+The setup wizard will:
+1. Ask for your Zuora OAuth credentials
+2. Let you choose your Zuora environment (sandbox, production, EU)
+3. Auto-configure Claude Code and/or Claude Desktop
+
+Then restart Claude Code and the Zuora tools are ready.
+
+### Prerequisites
+
+- Node.js 20+
+- Zuora OAuth credentials (create at Zuora Admin > Settings > Administration > OAuth Clients)
+
+### Manual Configuration (Alternative)
+
+If you prefer to configure manually, add to `~/.claude/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zuora": {
+      "command": "npx",
+      "args": ["-y", "@armor/zuora-mcp"],
+      "env": {
+        "ZUORA_CLIENT_ID": "your-client-id",
+        "ZUORA_CLIENT_SECRET": "your-client-secret",
+        "ZUORA_BASE_URL": "https://rest.apisandbox.zuora.com"
+      }
+    }
+  }
+}
+```
+
+### Install from Source
+
+```bash
+git clone git@github.com:armor/zuora-mcp.git
+cd zuora-mcp
+npm install
+npm run build
+```
+
+When installing from source, point to the built file in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "zuora": {
+      "command": "node",
+      "args": ["/path/to/zuora-mcp/dist/index.js"],
+      "env": {
+        "ZUORA_CLIENT_ID": "your-client-id",
+        "ZUORA_CLIENT_SECRET": "your-client-secret",
+        "ZUORA_BASE_URL": "https://rest.apisandbox.zuora.com"
+      }
+    }
+  }
+}
+```
+
+### Configuration
+
+Required environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `ZUORA_CLIENT_ID` | OAuth2 client ID |
+| `ZUORA_CLIENT_SECRET` | OAuth2 client secret |
+| `ZUORA_BASE_URL` | One of the Zuora base URLs (see below) |
+
+Optional variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DEBUG` | Set to `true` for verbose logging |
+
+#### Zuora Base URLs
+
+| Environment | URL |
+|-------------|-----|
+| US Production | `https://rest.zuora.com` |
+| US Sandbox | `https://rest.apisandbox.zuora.com` |
+| EU Production | `https://rest.eu.zuora.com` |
+| EU Sandbox | `https://rest.sandbox.eu.zuora.com` |
+
+### Getting Zuora OAuth Credentials
+
+1. Log into Zuora (production or sandbox)
+2. Navigate to **Settings > Administration > Manage Users**
+3. Select your user or create a service account
+4. Go to **OAuth Clients** tab and create a new client
+5. Copy the **Client ID** and **Client Secret** (secret is shown only once)
+
+## Available Tools
+
+### Account Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_account` | Get account details by key (ID or account number) |
+| `get_account_summary` | Get comprehensive account summary with balances, subscriptions, invoices, and payments |
+
+### Invoice Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_invoice` | Get invoice details including line items |
+| `list_invoices` | List invoices for an account with pagination |
+
+### Subscription Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_subscription` | Get subscription details with rate plans and charges |
+| `list_subscriptions` | List all subscriptions for an account |
+
+### Payment Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_payment` | Get payment details |
+| `list_payments` | List payments with optional account filter and pagination |
+
+### ZOQL Query Tools
+
+| Tool | Description |
+|------|-------------|
+| `execute_zoql_query` | Execute a ZOQL query for ad-hoc data retrieval |
+| `continue_zoql_query` | Continue paginated ZOQL results using queryLocator |
+
+### Product Catalog
+
+| Tool | Description |
+|------|-------------|
+| `list_products` | List products with rate plans and pricing |
+
+## Upgrading
+
+```bash
+npm update -g @armor/zuora-mcp
+```
+
+## Development
+
+```bash
+npm run dev        # Run with tsx (no build required)
+npm run build      # Build TypeScript to dist/
+npm run lint       # Run ESLint
+npm run typecheck  # Type check without building
+npm test           # Build and run tests
+npm run clean      # Remove dist/
+```
+
+### Debug Mode
+
+Set `DEBUG=true` to enable verbose logging to stderr:
+
+```bash
+DEBUG=true npm start
+```
+
+Debug output goes to stderr to avoid corrupting the stdio JSON-RPC transport.
+
+### Release Process
+
+This project uses semantic-release with branch-based publishing:
+
+| Branch | npm Tag | Description |
+|--------|---------|-------------|
+| `dev` | `alpha` | Development pre-releases |
+| `stage` | `beta` | Staging pre-releases |
+| `main` | `latest` | Production releases |
+
+Merging to any of these branches triggers the CD pipeline which:
+1. Runs lint, typecheck, build, and tests
+2. Determines the next version from commit messages
+3. Creates a GitHub release with notes
+4. Publishes to npm with the appropriate tag
+
+#### Commit Convention
+
+Follow conventional commits for automatic version bumps:
+
+| Prefix | Version Bump |
+|--------|--------------|
+| `feat:` | Minor (1.x.0) |
+| `fix:` | Patch (1.0.x) |
+| `breaking:` | Major (x.0.0) |
+
+## Architecture
+
+```
+src/
+├── cli.ts              # CLI entry point (bin): server, setup, --help, --version
+├── setup.ts            # Interactive setup wizard (zero external deps)
+├── index.ts            # MCP server bootstrap (exports startServer)
+├── config.ts           # Zod-validated environment configuration
+├── token-manager.ts    # OAuth2 token lifecycle (refresh, coalescing)
+├── zuora-client.ts     # Zuora REST API client with resilience
+├── tools.ts            # Tool definitions, Zod schemas, handlers
+├── zoql-helpers.ts     # ZOQL query composition utilities
+├── resources.ts        # MCP resources (data model, ZOQL guides)
+├── prompts.ts          # MCP prompts (finance workflow templates)
+└── types.ts            # TypeScript interfaces
+```
+
+### Authentication
+
+Uses OAuth 2.0 Client Credentials flow:
+- Tokens are stored in memory only (not persisted)
+- Proactive refresh 60 seconds before expiry
+- Promise coalescing prevents duplicate refresh requests under concurrency
+- Automatic 401 retry with token refresh
+
+### Resilience
+
+- Exponential backoff with jitter on 429/502/503/504
+- Idempotent methods (GET, PUT, DELETE) retry on transport failures
+- POST requests are NOT retried on HTTP errors (financial safety)
+- 20-second request timeout with AbortController
+
+### Security
+
+- All inputs validated with Zod schemas
+- Sensitive fields (card numbers, bank accounts) redacted from debug logs
+- Bearer tokens scrubbed from error messages
+- OAuth credentials never logged
+- Base URL validated against known Zuora endpoints at startup
+
+## Version History
+
+### v1.0.0
+
+- Initial release with 11 read-only tools
+- OAuth 2.0 authentication with token lifecycle management
+- Account, invoice, subscription, payment, and ZOQL query support
+- Product catalog access
+- Resilient HTTP client with retry and backoff

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for zuora-mcp.
+ *
+ * Routes between:
+ *   zuora-mcp          → starts the MCP server (stdio transport)
+ *   zuora-mcp setup    → runs the interactive setup wizard
+ *   zuora-mcp --help   → prints usage
+ *   zuora-mcp --version → prints version from package.json
+ *
+ * Dynamic imports keep the server and setup wizard fully isolated —
+ * `setup` never loads the MCP SDK, and server code only loads when serving.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for zuora-mcp.
+ *
+ * Routes between:
+ *   zuora-mcp          → starts the MCP server (stdio transport)
+ *   zuora-mcp setup    → runs the interactive setup wizard
+ *   zuora-mcp --help   → prints usage
+ *   zuora-mcp --version → prints version from package.json
+ *
+ * Dynamic imports keep the server and setup wizard fully isolated —
+ * `setup` never loads the MCP SDK, and server code only loads when serving.
+ */
+import { readFileSync } from "node:fs";
+function getVersion() {
+    try {
+        const packageJsonPath = new URL("../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (typeof pkg.version === "string" && pkg.version.length) {
+            return pkg.version;
+        }
+    }
+    catch {
+        // Fall through to safe default.
+    }
+    return "0.0.0";
+}
+function printHelp() {
+    const version = getVersion();
+    console.log(`zuora-mcp v${version} — Zuora Billing MCP Server
+
+Usage:
+  zuora-mcp            Start the MCP server (stdio transport)
+  zuora-mcp setup      Interactive setup wizard for Claude Code / Desktop
+  zuora-mcp --help     Show this help message
+  zuora-mcp --version  Show version number
+
+Environment variables (required for server mode):
+  ZUORA_CLIENT_ID      OAuth2 client ID from Zuora Admin
+  ZUORA_CLIENT_SECRET  OAuth2 client secret
+  ZUORA_BASE_URL       Zuora API base URL
+
+More info: https://github.com/armor/zuora-mcp`);
+}
+async function run() {
+    const arg = process.argv[2];
+    if (arg === "--help" || arg === "-h") {
+        printHelp();
+        return;
+    }
+    if (arg === "--version" || arg === "-v") {
+        console.log(getVersion());
+        return;
+    }
+    if (arg === "setup") {
+        const { runSetup } = await import("./setup.js");
+        await runSetup();
+        return;
+    }
+    if (arg !== undefined) {
+        console.error(`Unknown command: ${arg}\n`);
+        printHelp();
+        process.exit(1);
+    }
+    // Default: start the MCP server
+    const { startServer } = await import("./index.js");
+    await startServer();
+}
+run().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,SAAS,UAAU;IACjB,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAE3D,CAAC;QACF,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC1D,OAAO,GAAG,CAAC,OAAO,CAAC;QACrB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO;;;;;;;;;;;;;8CAaW,CAAC,CAAC;AAChD,CAAC;AAED,KAAK,UAAU,GAAG;IAChB,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE5B,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACrC,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,QAAQ,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;QAC3C,SAAS,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,gCAAgC;IAChC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IACnD,MAAM,WAAW,EAAE,CAAC;AACtB,CAAC;AAED,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACpB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration management for Zuora MCP Server
+ * Security-first: No hardcoded values, all from environment
+ */
+import { z } from "zod";
+declare const configSchema: z.ZodObject<{
+    zuoraClientId: z.ZodString;
+    zuoraClientSecret: z.ZodString;
+    zuoraBaseUrl: z.ZodEffects<z.ZodString, string, string>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    zuoraClientId: string;
+    zuoraClientSecret: string;
+    zuoraBaseUrl: string;
+    debug: boolean;
+}, {
+    zuoraClientId: string;
+    zuoraClientSecret: string;
+    zuoraBaseUrl: string;
+    debug?: boolean | undefined;
+}>;
+export type Config = z.infer<typeof configSchema>;
+export declare function loadConfig(): Config;
+export declare function validateConfig(): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;EAoBhB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,wBAAgB,UAAU,IAAI,MAAM,CAkBnC;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/config.js

@@ -0,0 +1,56 @@
+/**
+ * Configuration management for Zuora MCP Server
+ * Security-first: No hardcoded values, all from environment
+ */
+import { config as dotenvConfig } from "dotenv";
+import { z } from "zod";
+// Load .env files with quiet mode to prevent stdout corruption of JSON-RPC.
+// Precedence: process env > .env.local > .env
+// Base .env does NOT use override so process-level env vars take precedence.
+// .env.local uses override so it can override both .env and process env for local dev.
+dotenvConfig({ path: ".env", quiet: true });
+dotenvConfig({ path: ".env.local", override: true, quiet: true });
+const VALID_ZUORA_BASE_URLS = new Set([
+    "https://rest.zuora.com",
+    "https://rest.apisandbox.zuora.com",
+    "https://rest.eu.zuora.com",
+    "https://rest.sandbox.eu.zuora.com",
+]);
+const configSchema = z.object({
+    zuoraClientId: z
+        .string()
+        .min(1, "ZUORA_CLIENT_ID is required")
+        .describe("OAuth2 client ID from Zuora Admin"),
+    zuoraClientSecret: z
+        .string()
+        .min(1, "ZUORA_CLIENT_SECRET is required")
+        .describe("OAuth2 client secret"),
+    zuoraBaseUrl: z
+        .string()
+        .url("ZUORA_BASE_URL must be a valid URL")
+        .refine((url) => VALID_ZUORA_BASE_URLS.has(url.replace(/\/$/, "")), {
+        message: `ZUORA_BASE_URL must be one of: ${[...VALID_ZUORA_BASE_URLS].join(", ")}`,
+    })
+        .describe("Zuora REST API base URL"),
+    debug: z.boolean().default(false).describe("Enable debug logging"),
+});
+export function loadConfig() {
+    const rawConfig = {
+        zuoraClientId: process.env.ZUORA_CLIENT_ID,
+        zuoraClientSecret: process.env.ZUORA_CLIENT_SECRET,
+        zuoraBaseUrl: process.env.ZUORA_BASE_URL?.replace(/\/$/, ""),
+        debug: process.env.DEBUG === "true",
+    };
+    const result = configSchema.safeParse(rawConfig);
+    if (!result.success) {
+        const errors = result.error.errors
+            .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
+            .join("\n");
+        throw new Error(`Configuration validation failed:\n${errors}`);
+    }
+    return result.data;
+}
+export function validateConfig() {
+    loadConfig();
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4EAA4E;AAC5E,8CAA8C;AAC9C,6EAA6E;AAC7E,uFAAuF;AACvF,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC5C,YAAY,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAElE,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,wBAAwB;IACxB,mCAAmC;IACnC,2BAA2B;IAC3B,mCAAmC;CACpC,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,6BAA6B,CAAC;SACrC,QAAQ,CAAC,mCAAmC,CAAC;IAChD,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,iCAAiC,CAAC;SACzC,QAAQ,CAAC,sBAAsB,CAAC;IACnC,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,oCAAoC,CAAC;SACzC,MAAM,CACL,CAAC,GAAG,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAC1D;QACE,OAAO,EAAE,kCAAkC,CAAC,GAAG,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;KACnF,CACF;SACA,QAAQ,CAAC,yBAAyB,CAAC;IACtC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;CACnE,CAAC,CAAC;AAIH,MAAM,UAAU,UAAU;IACxB,MAAM,SAAS,GAAG;QAChB,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe;QAC1C,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAClD,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAC5D,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,MAAM;KACpC,CAAC;IAEF,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAEjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACnD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,UAAU,EAAE,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Zuora MCP Server
+ *
+ * A Model Context Protocol server for Zuora billing operations.
+ * Provides account, invoice, subscription, payment, and ZOQL query tools.
+ *
+ * Features:
+ * - OAuth 2.0 authentication with automatic token lifecycle
+ * - Account and billing entity read operations
+ * - ZOQL query support with pagination
+ * - Product catalog access
+ * - Resilient HTTP client with retry and backoff
+ *
+ * Security:
+ * - No hardcoded credentials
+ * - Input validation with Zod schemas
+ * - Sensitive data redaction in logs
+ * - OAuth token promise coalescing for concurrency safety
+ */
+declare function main(): Promise<void>;
+export { main as startServer };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8DH,iBAAe,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA+HnC;AAED,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,148 @@
+/**
+ * Zuora MCP Server
+ *
+ * A Model Context Protocol server for Zuora billing operations.
+ * Provides account, invoice, subscription, payment, and ZOQL query tools.
+ *
+ * Features:
+ * - OAuth 2.0 authentication with automatic token lifecycle
+ * - Account and billing entity read operations
+ * - ZOQL query support with pagination
+ * - Product catalog access
+ * - Resilient HTTP client with retry and backoff
+ *
+ * Security:
+ * - No hardcoded credentials
+ * - Input validation with Zod schemas
+ * - Sensitive data redaction in logs
+ * - OAuth token promise coalescing for concurrency safety
+ */
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "./config.js";
+import { ZuoraClient } from "./zuora-client.js";
+import { toolRegistrations, ToolHandlers } from "./tools.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
+const SERVER_NAME = "zuora-mcp";
+function getServerVersion() {
+    try {
+        const packageJsonPath = new URL("../package.json", import.meta.url);
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (typeof packageJson.version === "string" &&
+            packageJson.version.length) {
+            return packageJson.version;
+        }
+    }
+    catch {
+        // Fall through to safe default.
+    }
+    return "0.0.0";
+}
+function toCallToolResult(result) {
+    const structuredContent = {
+        success: result.success,
+        message: result.message,
+    };
+    if (result.data !== undefined) {
+        structuredContent.data = result.data;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(structuredContent, null, 2),
+            },
+        ],
+        structuredContent,
+        isError: !result.success,
+    };
+}
+async function main() {
+    // Validate configuration before starting
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        console.error("Configuration error:", error instanceof Error ? error.message : error);
+        console.error("\nRequired environment variables:");
+        console.error("  ZUORA_CLIENT_ID     - OAuth2 client ID from Zuora Admin");
+        console.error("  ZUORA_CLIENT_SECRET - OAuth2 client secret");
+        console.error("  ZUORA_BASE_URL      - Zuora API base URL (e.g., https://rest.apisandbox.zuora.com)");
+        console.error("\nOptional:");
+        console.error("  DEBUG=true          - Enable debug logging");
+        process.exit(1);
+    }
+    const client = new ZuoraClient(config);
+    const handlers = new ToolHandlers(client);
+    // Create MCP server
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: getServerVersion(),
+    });
+    // Register tools for MCP capability advertisement (tool listing).
+    // Dispatch is handled by the setRequestHandler override below.
+    for (const registration of toolRegistrations) {
+        server.registerTool(registration.name, {
+            description: registration.description,
+            inputSchema: registration.inputSchema,
+        }, async (args) => {
+            // Stub: actual dispatch is handled by setRequestHandler below.
+            const result = await registration.invoke(handlers, args);
+            return toCallToolResult(result);
+        });
+    }
+    // Register MCP resources (Zuora data model, ZOQL guides)
+    registerResources(server);
+    // Register MCP prompts (finance workflow templates)
+    registerPrompts(server);
+    // Map-based dispatch with protocol-level error handling.
+    // This overrides the SDK's default CallToolRequest handler to provide
+    // proper McpError responses for unknown tools and invalid parameters.
+    const registrationByName = new Map(toolRegistrations.map((registration) => [
+        registration.name,
+        registration,
+    ]));
+    server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const registration = registrationByName.get(name);
+        if (!registration) {
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        if (config.debug) {
+            console.error(`[${SERVER_NAME}] Tool called: ${registration.name}`, args);
+        }
+        let validatedArgs;
+        try {
+            validatedArgs = registration.inputSchema.parse(args);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for ${registration.name}: ${message}`);
+        }
+        try {
+            const result = await registration.invoke(handlers, validatedArgs);
+            return toCallToolResult(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toCallToolResult({
+                success: false,
+                message: `Unhandled tool error: ${message}`,
+            });
+        }
+    });
+    // Connect via stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (config.debug) {
+        console.error(`[${SERVER_NAME}] Server started successfully`);
+        console.error(`[${SERVER_NAME}] Connected to ${config.zuoraBaseUrl}`);
+        console.error(`[${SERVER_NAME}] Tools registered: ${toolRegistrations.length}`);
+    }
+}
+export { main as startServer };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/prompts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Prompt Definitions for Zuora Finance Workflows
+ *
+ * Workflow templates that guide Claude through multi-tool sequences
+ * for common finance scenarios. Each prompt provides structured
+ * instructions for using composite and base tools in the right order
+ * with proper formatting.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6PvD"}