@growpanel/mcp-server 2.1.0

package/README.md

@@ -0,0 +1,137 @@
+# GrowPanel MCP Server
+
+MCP server for [GrowPanel](https://growpanel.io) subscription analytics. Connects AI assistants (Claude, Cursor, Windsurf, etc.) to your GrowPanel data via the Model Context Protocol.
+
+**14 tools** covering reports, customers, plans, settings, webhooks, billing, team, and more. Plus a generic API passthrough that automatically supports new API features.
+
+## Installation
+
+```bash
+npm install -g @growpanel/mcp-server
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+    "mcpServers": {
+        "growpanel": {
+            "command": "growpanel-mcp",
+            "env": {
+                "GROWPANEL_API_KEY": "your-api-key-here"
+            }
+        }
+    }
+}
+```
+
+### Cursor / Other MCP Clients
+
+Most MCP clients support a similar configuration. Set the command to `growpanel-mcp` and provide the `GROWPANEL_API_KEY` environment variable.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GROWPANEL_API_KEY` | Your GrowPanel API key (required) | — |
+| `GROWPANEL_API_URL` | API base URL | `https://api.growpanel.io` |
+
+For backward compatibility, `GROWPANEL_API_TOKEN` is also accepted.
+
+Get your API key at [app.growpanel.io](https://app.growpanel.io) → Settings → API Keys.
+
+## Available Tools
+
+### Analytics
+
+| Tool | Description |
+|------|-------------|
+| `get_report` | Fetch any analytics report by name (mrr, summary, cohort, leads, cashflow, etc.) |
+
+The `get_report` tool accepts any report name — new reports added to the API work automatically.
+
+**Known reports:** mrr, mrr-table, summary, cmrr-summary, movement-table, map, cohort, leads, leads-table, leads-days, leads-summary, transactions, transactions-table, transactions-detail, transactions-summary, invoices-detail, churn-scheduled, churn-scheduled-movements, churn-scheduled-summary, customer-concentration, cashflow-failed-payments, cashflow-failed-payments-summary, cashflow-refunds, cashflow-refunds-table, cashflow-failure-rate, cashflow-outstanding-unpaid, custom-variables
+
+### Customers & Plans
+
+| Tool | Description |
+|------|-------------|
+| `list_customers` | List customers with MRR and subscription details |
+| `get_customer` | Get detailed info for a specific customer |
+| `resync_customer` | Trigger a data resync from the payment provider |
+| `list_plans` | List all subscription plans and plan groups |
+
+### Data Management
+
+| Tool | Description |
+|------|-------------|
+| `manage_data` | CRUD operations on customers, plans, plan-groups, data-sources, invoices |
+| `export_csv` | Export customers or MRR movements as CSV |
+
+### Settings & Integrations
+
+| Tool | Description |
+|------|-------------|
+| `manage_settings` | Get/update account and integration settings |
+| `manage_webhooks` | Manage webhook subscriptions (list, create, delete, verify, sample) |
+
+### Account Management
+
+| Tool | Description |
+|------|-------------|
+| `manage_account` | Get, update, or delete the account |
+| `manage_billing` | Billing details, invoices, subscriptions, payment methods |
+| `manage_team` | Team members: list, invite, edit roles, remove |
+| `manage_api_keys` | API key management: list, create, update, delete |
+
+### Generic Passthrough
+
+| Tool | Description |
+|------|-------------|
+| `api_request` | Call any API endpoint directly (method + path + params/body) |
+
+The `api_request` tool supports any API endpoint. New features added to the GrowPanel API are immediately available through this tool without needing an MCP server update.
+
+## Example Prompts
+
+Once connected, you can ask your AI assistant:
+
+- "What's my current MRR?"
+- "Show me MRR trends for the last 6 months"
+- "List my top customers by revenue"
+- "What's my churn rate?"
+- "Show me the cohort retention analysis"
+- "How many leads converted this quarter?"
+- "List all my webhook subscriptions"
+- "What are my current settings?"
+
+## Self-Updating Architecture
+
+The MCP server uses the same dynamic architecture as the [GrowPanel CLI](https://www.npmjs.com/package/@growpanel/cli):
+
+- **`get_report`** accepts any report name and passes it through to `/reports/<name>`. New reports work automatically.
+- **`api_request`** can call any API endpoint. New API features work on day one.
+- Named tools (`manage_data`, `manage_settings`, etc.) provide better descriptions for AI understanding, but the passthrough ensures nothing is missed.
+
+## Development
+
+```bash
+npm install
+npm run dev          # Run from source via tsx
+npm run build        # Compile TypeScript
+npm run typecheck    # Type checking only
+npm start            # Run built version
+```
+
+## Requirements
+
+- Node.js 20+
+- GrowPanel account with API key
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/server.js";

package/dist/api.d.ts

@@ -0,0 +1,9 @@
+export declare function callApi(options: {
+    method: string;
+    path: string;
+    params?: Record<string, string>;
+    body?: unknown;
+}): Promise<unknown>;
+export declare function unwrap(data: unknown): unknown;
+declare function filterParams(obj: Record<string, unknown>): Record<string, string>;
+export { filterParams };

package/dist/api.js

@@ -0,0 +1,54 @@
+const DEFAULT_API_URL = 'https://api.growpanel.io';
+export async function callApi(options) {
+    const baseUrl = (process.env.GROWPANEL_API_URL || DEFAULT_API_URL).replace(/\/$/, '');
+    const apiKey = process.env.GROWPANEL_API_KEY || process.env.GROWPANEL_API_TOKEN;
+    if (!apiKey) {
+        throw new Error('API key not configured. Set GROWPANEL_API_KEY environment variable. ' +
+            'Get your key at https://app.growpanel.io → Settings → API Keys.');
+    }
+    const url = new URL(options.path, baseUrl);
+    if (options.params) {
+        for (const [key, value] of Object.entries(options.params)) {
+            if (value !== undefined && value !== '') {
+                url.searchParams.set(key, value);
+            }
+        }
+    }
+    const headers = {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    const res = await fetch(url.toString(), {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    if (!res.ok) {
+        const errorText = await res.text();
+        throw new Error(`API error ${res.status}: ${errorText}`);
+    }
+    if (res.status === 204) {
+        return { success: true };
+    }
+    const contentType = res.headers.get('content-type') || '';
+    if (contentType.includes('text/csv') || contentType.includes('text/plain')) {
+        return await res.text();
+    }
+    return await res.json();
+}
+export function unwrap(data) {
+    if (data && typeof data === 'object' && 'result' in data) {
+        return data.result;
+    }
+    return data;
+}
+function filterParams(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined && value !== null && value !== '') {
+            result[key] = String(value);
+        }
+    }
+    return result;
+}
+export { filterParams };

package/dist/money_scale.d.ts

@@ -0,0 +1 @@
+export declare const scaleMoneyFields: (value: unknown) => unknown;

package/dist/money_scale.js

@@ -0,0 +1,76 @@
+// Pre-scale monetary values in tool results before the AI client sees them.
+//
+// GrowPanel stores most amounts in the smallest currency unit (cents/øre/…),
+// so a display value is the raw ÷ 100. A handful of "zero-decimal" currencies
+// (JPY, KRW, ISK, VND, HUF, …) have no subunit — the raw value IS the display
+// value and must NOT be divided. We detect the containing currency from the
+// nearest `currency` key in scope and act accordingly.
+//
+// Without this, the AI client routinely treats raw cents as dollars and quotes
+// numbers ~100× too high. Prompting alone can't be relied on; doing it in the
+// tool layer is the robust fix.
+//
+// Mirrors the same logic used by the hosted MCP server (growpanel-mcp/src/
+// helpers/money_scale.js) and the in-app AI chat
+// (growpanel-api/src/controllers/chat/v2/tools/_money_scale.js). Keep all
+// three in sync if you add new amount fields.
+const ZERO_DECIMAL_CURRENCIES = new Set([
+    'bif', 'clp', 'djf', 'gnf', 'isk', 'jpy', 'kmf', 'krw', 'mga', 'pyg',
+    'rwf', 'ugx', 'vnd', 'vuv', 'xaf', 'xof', 'xpf', 'huf',
+]);
+const MONEY_EXPLICIT = new Set([
+    'new', 'expansion', 'contraction', 'churn', 'reactivation',
+    'mrr_diff', 'net_mrr_diff', 'fx_adjustment', 'total_mrr', 'total_arr',
+    'arpa', 'asp', 'ltv',
+    'net_amount', 'month_sub', 'year_sub', 'one_time', 'metered',
+    'discount', 'refund', 'tax', 'fee', 'fx_loss',
+    'failed_amount', 'recovered', 'still_unpaid', 'churned',
+    'scheduled_churn_mrr',
+    'cmrr_current', 'cmrr_30', 'cmrr_60', 'cmrr_180', 'cmrr_365',
+    'mrr', 'amount', 'original_amount',
+    'total_paid_customer_currency', 'total_paid_base_currency',
+    'source_mrr',
+    'mrr_change', 'mrr_change_base_currency', 'mrr_change_customer_currency',
+]);
+const NOT_MONEY_RE = /(_count|_counts|_customers?|_rate|_rates|_pct|_percent|_percentage|_days|_num|_ratio|_change_pct|_diff_pct|_id)$/i;
+const MONEY_HINT_RE = /^(mrr|arr|cmrr|ltv|arpa|asp|cac|gmv|revenue|amount|paid|charged|refunded|collected|owed|earned|invoiced|billed|churned|recovered|discount|fee|tax|gross|net)_|_(mrr|arr|ltv|amount|paid|charged|refunded|collected|revenue|owed|earned|invoiced|billed|churned|recovered|fee|tax|discount|gross|net)(_|$)/i;
+const looksLikeMoneyKey = (key) => {
+    if (!key)
+        return false;
+    if (MONEY_EXPLICIT.has(key))
+        return true;
+    if (NOT_MONEY_RE.test(key))
+        return false;
+    return MONEY_HINT_RE.test(key);
+};
+const isZeroDecimal = (code) => typeof code === 'string' && ZERO_DECIMAL_CURRENCIES.has(code.trim().toLowerCase());
+const scaleNumber = (n) => {
+    if (typeof n !== 'number' || !isFinite(n))
+        return n;
+    return Math.round(n) / 100;
+};
+const walk = (value, currencyInScope) => {
+    if (value == null)
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => walk(v, currencyInScope));
+    if (typeof value !== 'object')
+        return value;
+    const obj = value;
+    const localCurrency = typeof obj.currency === 'string' ? obj.currency : currencyInScope;
+    const skip = isZeroDecimal(localCurrency);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (looksLikeMoneyKey(k) && typeof v === 'number' && !skip) {
+            out[k] = scaleNumber(v);
+        }
+        else if (v && typeof v === 'object') {
+            out[k] = walk(v, localCurrency);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+};
+export const scaleMoneyFields = (value) => walk(value, null);

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,63 @@
+import dotenv from 'dotenv';
+dotenv.config();
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { tools } from './tools.js';
+import { scaleMoneyFields } from './money_scale.js';
+const server = new Server({
+    name: 'GrowPanel MCP Server',
+    version: '2.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Register tools/list handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    };
+});
+// Register tools/call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = tools.find((t) => t.name === name);
+    if (!tool) {
+        throw new Error(`Unknown tool: ${name}. Available tools: ${tools.map((t) => t.name).join(', ')}`);
+    }
+    try {
+        const raw = await tool.handler(args || {});
+        // Pre-scale monetary fields (cents → display units) so the AI client
+        // doesn't quote raw cents as if they were dollars. CSV/text returns
+        // pass through untouched.
+        const result = typeof raw === 'string' ? raw : scaleMoneyFields(raw);
+        const text = typeof result === 'string'
+            ? result
+            : JSON.stringify(result, null, 2);
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Start stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('GrowPanel MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Failed to start MCP server:', error);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,12 @@
+interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (params: Record<string, any>) => Promise<unknown>;
+}
+export declare const tools: ToolDef[];
+export {};

package/dist/tools.js

@@ -0,0 +1,470 @@
+import { callApi, unwrap, filterParams } from './api.js';
+const KNOWN_REPORTS = [
+    'mrr', 'mrr-growth', 'mrr-growth-table', 'mrr-table', 'mrr-table-subtypes', 'summary', 'cmrr-summary',
+    'movement-table', 'map', 'cohort',
+    // retention is the source of truth for churn, retention, NRR, GRR, LTV, customer_lifetime.
+    // The mrr report no longer exposes those fields — query retention instead.
+    'retention',
+    'leads', 'leads-table', 'leads-days', 'leads-summary',
+    'transactions', 'transactions-table', 'transactions-detail', 'transactions-summary',
+    'invoices-detail',
+    'churn-scheduled', 'churn-scheduled-movements', 'churn-scheduled-summary',
+    'customer-concentration',
+    'cashflow-failed-payments', 'cashflow-failed-payments-summary',
+    'cashflow-failed-payments-detail', 'cashflow-failed-payments-table',
+    'cashflow-refunds', 'cashflow-refunds-table', 'cashflow-refunds-detail',
+    'cashflow-failure-rate', 'cashflow-failure-rate-summary',
+    'cashflow-outstanding-unpaid',
+    'custom-variables',
+];
+const REPORT_FILTER_PROPERTIES = {
+    date: { type: 'string', description: 'Date range in yyyyMMdd-yyyyMMdd format (e.g., 20240101-20241231)' },
+    interval: { type: 'string', enum: ['day', 'week', 'month', 'quarter', 'year'], description: 'Aggregation interval (default: month)' },
+    currency: { type: 'string', description: 'Filter by currency code (e.g., usd, eur)' },
+    region: { type: 'string', description: 'Filter by region' },
+    plan: { type: 'string', description: 'Filter by plan group ID' },
+    country: { type: 'string', description: 'Filter by ISO country code' },
+    data_source: { type: 'string', description: 'Filter by data source ID' },
+    breakdown: { type: 'string', description: 'Group results by a dimension. Supported on mrr, retention, cohort, leads, leads-table, transactions (cashflow), transactions-table, cashflow-refunds, churn-reasons, churn-scheduled. Common values: plan, currency, payment_method, country, region, market, age, data_source, billing_freq, pricing_model. Custom variables: custom_<key>.' },
+    category: { type: 'string', description: 'Filter to specific movement types (space-separated): new, expansion, reactivation, contraction, churn. Used by mrr-movements and mrr-growth reports.' },
+};
+export const tools = [
+    // ─── Analytics (core) ────────────────────────────────────────────
+    {
+        name: 'get_report',
+        description: `Fetch any GrowPanel analytics report by name. This is the primary tool for subscription analytics.\n\nKnown reports: ${KNOWN_REPORTS.join(', ')}\n\nAny report name is accepted — new API reports work automatically without MCP server updates.\n\nAll monetary values are in the account's base currency. The response includes a \`currency\` field indicating which currency is used (e.g., "usd", "eur", "dkk").`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Report name (e.g., mrr, summary, cohort, leads, cashflow-failed-payments)' },
+                ...REPORT_FILTER_PROPERTIES,
+            },
+            required: ['name'],
+        },
+        handler: async (params) => {
+            const { name, ...filters } = params;
+            const data = await callApi({ method: 'GET', path: `/reports/${name}`, params: filterParams(filters) });
+            return data;
+        },
+    },
+    // ─── Customers ───────────────────────────────────────────────────
+    {
+        name: 'list_customers',
+        description: 'List all customers with their subscription details and MRR. Supports pagination.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                date: { type: 'string', description: 'Date range in yyyyMMdd-yyyyMMdd format' },
+                limit: { type: 'string', description: 'Maximum number of results (default: 100)' },
+                offset: { type: 'string', description: 'Pagination offset' },
+            },
+        },
+        handler: async (params) => {
+            const data = await callApi({ method: 'GET', path: '/customers', params: filterParams(params) });
+            return unwrap(data);
+        },
+    },
+    {
+        name: 'get_customer',
+        description: 'Get detailed information for a specific customer by ID, including MRR, plans, and subscription history.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Customer ID' },
+            },
+            required: ['id'],
+        },
+        handler: async (params) => {
+            const data = await callApi({ method: 'GET', path: `/customers/${params.id}` });
+            return unwrap(data);
+        },
+    },
+    {
+        name: 'resync_customer',
+        description: 'Trigger a data resync for a specific customer from the payment provider. Admin/owner only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Customer ID to resync' },
+            },
+            required: ['id'],
+        },
+        handler: async (params) => {
+            const data = await callApi({ method: 'POST', path: `/customers/${params.id}/resync` });
+            return unwrap(data);
+        },
+    },
+    // ─── Plans ───────────────────────────────────────────────────────
+    {
+        name: 'list_plans',
+        description: 'List all subscription plans with their plan groups, pricing, and customer counts.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+        handler: async () => {
+            const data = await callApi({ method: 'GET', path: '/plans' });
+            return unwrap(data);
+        },
+    },
+    // ─── Data CRUD ───────────────────────────────────────────────────
+    {
+        name: 'manage_data',
+        description: `Generic CRUD operations on data resources.\n\nResources: customers, plans, plan-groups, data-sources, invoices\n\nStandard actions: list, get, create, update, delete\nData source actions: reset, connect, full-import, progress, abort\nPlan group actions: delete-multiple, ai-suggest, merge`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                resource: { type: 'string', enum: ['customers', 'plans', 'plan-groups', 'data-sources', 'invoices'], description: 'Resource type' },
+                action: {
+                    type: 'string',
+                    enum: ['list', 'get', 'create', 'update', 'delete', 'reset', 'connect', 'full-import', 'progress', 'abort', 'delete-multiple', 'ai-suggest', 'merge'],
+                    description: 'Operation to perform',
+                },
+                id: { type: 'string', description: 'Resource ID (required for get, update, delete, and data-source special actions)' },
+                body: { type: 'object', description: 'Request body (for create, update, and special actions)' },
+                data_source: { type: 'string', description: 'Filter by data source ID (for list action)' },
+            },
+            required: ['resource', 'action'],
+        },
+        handler: async (params) => {
+            const { resource, action, id, body, data_source } = params;
+            let data;
+            switch (action) {
+                case 'list':
+                    data = await callApi({ method: 'GET', path: `/data/${resource}`, params: filterParams({ data_source }) });
+                    break;
+                case 'get':
+                    data = await callApi({ method: 'GET', path: `/data/${resource}/${id}` });
+                    break;
+                case 'create':
+                    data = await callApi({ method: 'POST', path: `/data/${resource}`, body });
+                    break;
+                case 'update':
+                    data = await callApi({ method: 'PUT', path: `/data/${resource}/${id}`, body });
+                    break;
+                case 'delete':
+                    data = await callApi({ method: 'DELETE', path: `/data/${resource}/${id}` });
+                    break;
+                // Data source special actions
+                case 'reset':
+                case 'connect':
+                case 'full-import':
+                case 'abort':
+                    data = await callApi({ method: 'POST', path: `/data/${resource}/${id}/${action}`, body });
+                    break;
+                case 'progress':
+                    data = await callApi({ method: 'GET', path: `/data/${resource}/${id}/progress` });
+                    break;
+                // Plan group special actions
+                case 'delete-multiple':
+                case 'ai-suggest':
+                case 'merge':
+                    data = await callApi({ method: 'POST', path: `/data/${resource}/${action}`, body });
+                    break;
+                default:
+                    throw new Error(`Unknown action: ${action}`);
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── Exports ─────────────────────────────────────────────────────
+    {
+        name: 'export_csv',
+        description: 'Export data as CSV. Available exports: customers (all customers with details), mrr-movements (all MRR changes), mrr-growth (per-month-per-day cumulative MRR change in long format, ideal for cohort/pacing analysis).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', enum: ['customers', 'mrr-movements', 'mrr-growth'], description: 'Export type' },
+                date: { type: 'string', description: 'Date range in yyyyMMdd-yyyyMMdd format' },
+                category: { type: 'string', description: 'For mrr-growth: filter to specific movement types (space-separated): new, expansion, reactivation, contraction, churn' },
+            },
+            required: ['type'],
+        },
+        handler: async (params) => {
+            const { type, date, category } = params;
+            const filename = `${type}.csv`;
+            const data = await callApi({ method: 'GET', path: `/exports/${filename}`, params: filterParams({ date, category }) });
+            return data;
+        },
+    },
+    // ─── Settings ────────────────────────────────────────────────────
+    {
+        name: 'manage_settings',
+        description: `Get or update account settings and integration settings.\n\nFor general settings: action=get or action=update with body.\nFor integration settings: set the integration parameter.\n\nIntegrations: notifications, stripe, hubspot, webhook, slack, teams, looker-studio`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'update'], description: 'get to read settings, update to modify' },
+                integration: {
+                    type: 'string',
+                    enum: ['notifications', 'stripe', 'hubspot', 'webhook', 'slack', 'teams', 'looker-studio'],
+                    description: 'Integration name (omit for general account settings)',
+                },
+                body: { type: 'object', description: 'Settings to update (required for update action)' },
+            },
+            required: ['action'],
+        },
+        handler: async (params) => {
+            const { action, integration, body } = params;
+            const path = integration ? `/settings/${integration}` : '/settings';
+            let data;
+            if (action === 'get') {
+                data = await callApi({ method: 'GET', path });
+            }
+            else {
+                // Use PUT for notifications, POST for everything else
+                const method = integration === 'notifications' ? 'PUT' : 'POST';
+                data = await callApi({ method, path, body });
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── Webhooks ────────────────────────────────────────────────────
+    {
+        name: 'manage_webhooks',
+        description: 'Manage webhook subscriptions for real-time event notifications.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'get', 'create', 'delete', 'verify', 'sample'], description: 'Webhook operation' },
+                id: { type: 'string', description: 'Webhook ID (for get/delete)' },
+                event: { type: 'string', description: 'Event type name (for sample, e.g., customer.created)' },
+                body: { type: 'object', description: 'Webhook configuration (for create: url, events array)' },
+            },
+            required: ['action'],
+        },
+        handler: async (params) => {
+            const { action, id, event, body } = params;
+            let data;
+            switch (action) {
+                case 'list':
+                    data = await callApi({ method: 'GET', path: '/integrations/webhooks' });
+                    break;
+                case 'get':
+                    data = await callApi({ method: 'GET', path: `/integrations/webhooks/${id}` });
+                    break;
+                case 'create':
+                    data = await callApi({ method: 'POST', path: '/integrations/webhooks', body });
+                    break;
+                case 'delete':
+                    data = await callApi({ method: 'DELETE', path: `/integrations/webhooks/${id}` });
+                    break;
+                case 'verify':
+                    data = await callApi({ method: 'GET', path: '/integrations/verify' });
+                    break;
+                case 'sample':
+                    data = await callApi({ method: 'GET', path: `/integrations/sample/${event}` });
+                    break;
+                default:
+                    throw new Error(`Unknown webhook action: ${action}`);
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── Account ─────────────────────────────────────────────────────
+    {
+        name: 'manage_account',
+        description: 'Get, update, or delete the GrowPanel account.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'update', 'delete'], description: 'Account operation' },
+                body: { type: 'object', description: 'Account data to update (for update action)' },
+            },
+            required: ['action'],
+        },
+        handler: async (params) => {
+            const { action, body } = params;
+            let data;
+            switch (action) {
+                case 'get':
+                    data = await callApi({ method: 'GET', path: '/account' });
+                    break;
+                case 'update':
+                    data = await callApi({ method: 'POST', path: '/account', body });
+                    break;
+                case 'delete':
+                    data = await callApi({ method: 'DELETE', path: '/account' });
+                    break;
+                default:
+                    throw new Error(`Unknown account action: ${action}`);
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── Billing ─────────────────────────────────────────────────────
+    {
+        name: 'manage_billing',
+        description: 'Manage billing, subscriptions, invoices, and payment methods.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: [
+                        'details', 'invoices', 'portal', 'subscribe', 'check_vat',
+                        'address', 'setup', 'preview_change', 'change_plan',
+                        'undo_cancellation', 'delete_card',
+                    ],
+                    description: 'Billing operation',
+                },
+                body: { type: 'object', description: 'Request body (for subscribe, address, preview_change, change_plan)' },
+                card_id: { type: 'string', description: 'Card ID (for delete_card action)' },
+                vat_number: { type: 'string', description: 'VAT number (for check_vat action)' },
+            },
+            required: ['action'],
+        },
+        handler: async (params) => {
+            const { action, body, card_id, vat_number } = params;
+            let data;
+            switch (action) {
+                case 'details':
+                    data = await callApi({ method: 'GET', path: '/account/billing' });
+                    break;
+                case 'invoices':
+                    data = await callApi({ method: 'GET', path: '/account/billing/invoices' });
+                    break;
+                case 'portal':
+                    data = await callApi({ method: 'GET', path: '/account/billing/portal' });
+                    break;
+                case 'subscribe':
+                    data = await callApi({ method: 'POST', path: '/account/billing/subscribe', body });
+                    break;
+                case 'check_vat':
+                    data = await callApi({ method: 'GET', path: '/account/billing/check-vat', params: filterParams({ vat_number }) });
+                    break;
+                case 'address':
+                    data = await callApi({ method: 'POST', path: '/account/billing/address', body });
+                    break;
+                case 'setup':
+                    data = await callApi({ method: 'POST', path: '/account/billing/setup' });
+                    break;
+                case 'preview_change':
+                    data = await callApi({ method: 'POST', path: '/account/billing/preview-change', body });
+                    break;
+                case 'change_plan':
+                    data = await callApi({ method: 'POST', path: '/account/billing/change-plan', body });
+                    break;
+                case 'undo_cancellation':
+                    data = await callApi({ method: 'POST', path: '/account/billing/undo-cancellation' });
+                    break;
+                case 'delete_card':
+                    data = await callApi({ method: 'DELETE', path: `/account/billing/cards/${card_id}` });
+                    break;
+                default:
+                    throw new Error(`Unknown billing action: ${action}`);
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── Team ────────────────────────────────────────────────────────
+    {
+        name: 'manage_team',
+        description: 'Manage team members: list, edit roles, remove, invite, and manage invitations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'edit', 'remove', 'invite', 'revoke_invite', 'resend_invite'],
+                    description: 'Team operation',
+                },
+                user_id: { type: 'string', description: 'User ID (for edit/remove)' },
+                email: { type: 'string', description: 'Email address (for revoke_invite/resend_invite)' },
+                body: { type: 'object', description: 'Request body (for edit: role; for invite: email, role)' },
+            },
+            required: ['action'],
+        },
+        handler: async (params) => {
+            const { action, user_id, email, body } = params;
+            let data;
+            switch (action) {
+                case 'list':
+                    data = await callApi({ method: 'GET', path: '/account/team' });
+                    break;
+                case 'edit':
+                    data = await callApi({ method: 'PUT', path: `/account/team/${user_id}`, body });
+                    break;
+                case 'remove':
+                    data = await callApi({ method: 'DELETE', path: `/account/team/${user_id}` });
+                    break;
+                case 'invite':
+                    data = await callApi({ method: 'POST', path: '/account/team/invite', body });
+                    break;
+                case 'revoke_invite':
+                    data = await callApi({ method: 'DELETE', path: `/account/team/invites/${email}` });
+                    break;
+                case 'resend_invite':
+                    data = await callApi({ method: 'POST', path: `/account/team/resend/${email}` });
+                    break;
+                default:
+                    throw new Error(`Unknown team action: ${action}`);
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── API Keys ────────────────────────────────────────────────────
+    {
+        name: 'manage_api_keys',
+        description: 'Manage API keys: list, create, update, and delete.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'create', 'update', 'delete'], description: 'API key operation' },
+                id: { type: 'string', description: 'API key ID (for update/delete)' },
+                body: { type: 'object', description: 'API key data (for create/update: name, permissions)' },
+            },
+            required: ['action'],
+        },
+        handler: async (params) => {
+            const { action, id, body } = params;
+            let data;
+            switch (action) {
+                case 'list':
+                    data = await callApi({ method: 'GET', path: '/account/api-keys' });
+                    break;
+                case 'create':
+                    data = await callApi({ method: 'POST', path: '/account/api-keys', body });
+                    break;
+                case 'update':
+                    data = await callApi({ method: 'PUT', path: `/account/api-keys/${id}`, body });
+                    break;
+                case 'delete':
+                    data = await callApi({ method: 'DELETE', path: `/account/api-keys/${id}` });
+                    break;
+                default:
+                    throw new Error(`Unknown api-keys action: ${action}`);
+            }
+            return unwrap(data);
+        },
+    },
+    // ─── Generic Passthrough ─────────────────────────────────────────
+    {
+        name: 'api_request',
+        description: 'Generic API passthrough for any GrowPanel API endpoint. Use this for endpoints not covered by other tools, or when new API features are added. Any valid API path works — this tool makes the MCP server automatically support new features.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: 'HTTP method' },
+                path: { type: 'string', description: 'API path starting with / (e.g., /reports/mrr, /data/customers)' },
+                params: {
+                    type: 'object',
+                    description: 'Query parameters as key-value pairs (for GET requests)',
+                    additionalProperties: { type: 'string' },
+                },
+                body: { type: 'object', description: 'Request body (for POST/PUT requests)' },
+            },
+            required: ['method', 'path'],
+        },
+        handler: async (params) => {
+            const { method, path, params: queryParams, body } = params;
+            const data = await callApi({
+                method,
+                path,
+                params: queryParams ? filterParams(queryParams) : undefined,
+                body,
+            });
+            return unwrap(data);
+        },
+    },
+];

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@growpanel/mcp-server",
+    "version": "2.1.0",
+    "description": "MCP server for GrowPanel SaaS subscription analytics API - 14 tools covering reports, customers, settings, and more",
+    "main": "dist/server.js",
+    "type": "module",
+    "bin": {
+        "growpanel-mcp": "bin/cli.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsx src/server.ts",
+        "start": "node dist/server.js",
+        "typecheck": "tsc --noEmit"
+    },
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "dependencies": {
+        "@growpanel/sdk": "^0.1.4",
+        "@modelcontextprotocol/sdk": "^1.17.4",
+        "dotenv": "^16.3.1",
+        "zod": "^3.22.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.17.0",
+        "tsx": "^4.19.0",
+        "typescript": "^5.3.0"
+    },
+    "files": [
+        "dist/**/*",
+        "bin/**/*",
+        "package.json",
+        "README.md"
+    ],
+    "keywords": [
+        "mcp",
+        "growpanel",
+        "ai-tools",
+        "saas-metrics",
+        "subscription-analytics",
+        "mrr",
+        "churn",
+        "recurring-revenue"
+    ],
+    "author": "GrowPanel ApS",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/growpanel/growpanel-mcp-server.git"
+    }
+}