@armor/zuora-mcp 0.0.0-development

package/dist/prompts.js

@@ -0,0 +1,236 @@
+/**
+ * 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 { z } from "zod";
+// ==================== Registration ====================
+export function registerPrompts(server) {
+    // Prompt 1: Billing Inquiry
+    server.registerPrompt("billing-inquiry", {
+        description: "Investigate a billing question for a specific account. " +
+            "Guides you through retrieving the account overview, recent invoices, " +
+            "payments, and subscriptions to answer billing-related questions.",
+        argsSchema: {
+            accountKey: z.string().describe("Account number or ID (e.g., A00012345)"),
+            question: z.string().optional().describe("The specific billing question"),
+        },
+    }, async ({ accountKey, question }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Investigate the following billing question for account ${accountKey}:`,
+                        question ? `Question: ${question}` : "Provide a general billing overview.",
+                        "",
+                        "Follow these steps:",
+                        "1. Call get_account_billing_overview with the account key to get a comprehensive snapshot",
+                        "2. Review the overview for any red flags (high balance, overdue invoices, payment failures)",
+                        "3. If there are overdue invoices, note the amounts and due dates",
+                        "4. If more detail is needed on a specific invoice, use get_invoice",
+                        "5. If more detail is needed on a specific subscription, use get_subscription",
+                        "",
+                        "Format your response as:",
+                        "- Account summary (name, status, balance, currency)",
+                        "- Outstanding invoices (if any) with amounts and due dates",
+                        "- Recent payment activity",
+                        "- Active subscriptions with MRR",
+                        "- Answer to the specific billing question",
+                        "- Recommended actions (if applicable)",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // Prompt 2: Collections Review
+    server.registerPrompt("collections-review", {
+        description: "Analyze overdue accounts for collections. Generates an AR aging report, " +
+            "identifies high-risk accounts, and provides actionable collection priorities.",
+        argsSchema: {
+            minAmount: z.string().optional().describe("Minimum overdue amount to include (e.g., 1000). Default: 0"),
+            daysOverdue: z.string().optional().describe("Minimum days past due to flag (e.g., 30). Default: 1"),
+        },
+    }, async ({ minAmount, daysOverdue }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Run a collections review with the following criteria:",
+                        minAmount ? `- Minimum overdue amount: $${minAmount}` : "- Include all overdue amounts",
+                        daysOverdue ? `- Minimum days past due: ${daysOverdue}` : "- Include all overdue invoices",
+                        "",
+                        "Follow these steps:",
+                        "1. Call get_invoice_aging_report to get the AR aging breakdown",
+                        "2. Call get_overdue_invoices to get detailed overdue invoice list",
+                        minAmount ? `   - Use minBalance: ${minAmount}` : "",
+                        "3. Call get_account_health_scorecard to identify at-risk accounts",
+                        "",
+                        "Format your response as:",
+                        "",
+                        "## AR Aging Summary",
+                        "Table with aging buckets (Current, 1-30, 31-60, 61-90, 90+), invoice count, and total balance per bucket",
+                        "",
+                        "## Top Overdue Accounts",
+                        "Table with account name, account number, total overdue, oldest invoice, days past due",
+                        "",
+                        "## At-Risk Accounts",
+                        "List accounts with low health scores and explain risk factors",
+                        "",
+                        "## Recommended Actions",
+                        "Prioritized list of collection actions based on amount and risk",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // Prompt 3: Subscription Health
+    server.registerPrompt("subscription-health", {
+        description: "Analyze subscription health: renewal pipeline, expiring subscriptions, " +
+            "recent churn, and revenue by product. Useful for monthly/quarterly reviews.",
+        argsSchema: {
+            daysAhead: z.string().optional().describe("Days to look ahead for expiring subscriptions (default: 30)"),
+            daysBack: z.string().optional().describe("Days to look back for cancelled subscriptions (default: 30)"),
+        },
+    }, async ({ daysAhead, daysBack }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Analyze subscription health with the following parameters:",
+                        `- Look ahead for expirations: ${daysAhead ?? "30"} days`,
+                        `- Look back for cancellations: ${daysBack ?? "30"} days`,
+                        "",
+                        "Follow these steps:",
+                        `1. Call get_expiring_subscriptions with daysAhead: ${daysAhead ?? "30"}`,
+                        `2. Call get_recently_cancelled_subscriptions with daysBack: ${daysBack ?? "30"}`,
+                        "3. Call get_revenue_by_product to see MRR breakdown",
+                        "",
+                        "Format your response as:",
+                        "",
+                        "## Renewal Pipeline",
+                        "Table of subscriptions expiring soon: account, subscription number, term end date, MRR, auto-renew status",
+                        "Total MRR at risk",
+                        "",
+                        "## Recent Churn",
+                        "Table of recently cancelled subscriptions: account, subscription number, cancelled date, lost MRR, products",
+                        "Total MRR lost",
+                        "",
+                        "## Revenue by Product",
+                        "Table: product name, subscription count, total MRR",
+                        "",
+                        "## Summary Metrics",
+                        "- Total MRR at risk (expiring soon, not auto-renewing)",
+                        "- Recent churn rate (cancelled MRR / total MRR)",
+                        "- Recommended actions for retention",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // Prompt 4: Product Analysis
+    server.registerPrompt("product-analysis", {
+        description: "Analyze a specific product's performance: accounts using it, " +
+            "revenue contribution, and invoice history.",
+        argsSchema: {
+            productName: z.string().describe("Product name to analyze (e.g., 'Security Analytics Log Retention 13 Months')"),
+        },
+    }, async ({ productName }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Analyze the product: "${productName}"`,
+                        "",
+                        "Follow these steps:",
+                        `1. Call find_accounts_by_product with productName: "${productName}" to find accounts using this product`,
+                        "2. Call get_revenue_by_product to see this product's MRR contribution vs others",
+                        `3. Call find_invoices_by_product with productName: "${productName}" to see invoice history`,
+                        "",
+                        "Format your response as:",
+                        "",
+                        "## Product Overview",
+                        "- Product name",
+                        "- Number of accounts using it",
+                        "- Total MRR from this product",
+                        "",
+                        "## Accounts Using This Product",
+                        "Table: account number, account name, subscription status, MRR",
+                        "",
+                        "## Revenue Contribution",
+                        "How this product's MRR compares to total MRR (percentage)",
+                        "",
+                        "## Recent Invoices",
+                        "Table: invoice number, account, date, charge amount",
+                        "",
+                        "## Insights",
+                        "- Growth or decline trends",
+                        "- Concentration risk (if few accounts)",
+                        "- Recommendations",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // Prompt 5: Month-End Close
+    server.registerPrompt("month-end-close", {
+        description: "Month-end close checklist: AR aging, overdue invoices, subscription changes, " +
+            "payment reconciliation, and revenue summary. Comprehensive financial review.",
+        argsSchema: {
+            month: z.string().optional().describe("Month to close in YYYY-MM format (e.g., 2024-12). Default: previous month"),
+        },
+    }, async ({ month }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Run the month-end close checklist${month ? ` for ${month}` : ""}.`,
+                        "",
+                        "Execute the following steps in order:",
+                        "",
+                        "### Step 1: AR Aging",
+                        "Call get_invoice_aging_report to get the current AR aging breakdown.",
+                        "",
+                        "### Step 2: Overdue Invoices",
+                        "Call get_overdue_invoices to list all overdue invoices.",
+                        "",
+                        "### Step 3: Payment Reconciliation",
+                        `Call get_payment_reconciliation${month ? ` with startDate and endDate covering ${month}` : " for the previous calendar month"}.`,
+                        "",
+                        "### Step 4: Subscription Changes",
+                        "Call get_recently_cancelled_subscriptions with daysBack: 31 for churn analysis.",
+                        "Call get_expiring_subscriptions with daysAhead: 30 for upcoming renewals.",
+                        "",
+                        "### Step 5: Revenue Summary",
+                        "Call get_revenue_by_product for MRR breakdown by product.",
+                        "",
+                        "### Step 6: Account Health",
+                        "Call get_account_health_scorecard to identify at-risk accounts.",
+                        "",
+                        "Format as a structured month-end report with:",
+                        "1. **AR Aging Summary** -- Aging buckets table",
+                        "2. **Overdue Invoice Details** -- Count, total, top overdue accounts",
+                        "3. **Payment Activity** -- Total collected, payment count, by status",
+                        "4. **Subscription Activity** -- New, cancelled, expiring, net MRR change",
+                        "5. **Revenue by Product** -- MRR breakdown table",
+                        "6. **Risk Assessment** -- At-risk accounts requiring attention",
+                        "7. **Action Items** -- Prioritized list of follow-ups",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

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

package/dist/resources.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Resource Definitions for Zuora Data Model & ZOQL Reference
+ *
+ * Static content that Claude reads to write better ad-hoc ZOQL queries.
+ * These resources expose Zuora's data model, relationships, syntax rules,
+ * and common query patterns so Claude can construct correct multi-step ZOQL
+ * without needing to guess field names or relationships.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA0czE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwGzD"}