@rhinosaas/rebillia-mcp-server 1.0.6

package/dist/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Rebillia MCP Server
+ * Model Context Protocol server for Rebillia API integration
+ */
+import "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 RebilliaClient from "./client.js";
+import { registerResources } from "./resources/api-docs.js";
+import { executeTool, getToolDefinitions } from "./tools/index.js";
+// ============================================================================
+// Environment Configuration
+// ============================================================================
+const REBILLIA_API_KEY = process.env.REBILLIA_API_KEY;
+if (!REBILLIA_API_KEY) {
+    throw new Error("REBILLIA_API_KEY environment variable is required");
+}
+const REBILLIA_API_URL = process.env.REBILLIA_API_URL || "https://api.rebillia.com/v1";
+// ============================================================================
+// Initialize Rebillia Client
+// ============================================================================
+const rebilliaClient = new RebilliaClient(REBILLIA_API_KEY, REBILLIA_API_URL);
+// ============================================================================
+// Initialize MCP Server
+// ============================================================================
+const server = new Server({
+    name: "rebillia-mcp-server",
+    version: "1.0",
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+// ============================================================================
+// Resources (rebillia://docs/* – overview, models, subscription-statuses, charge-types)
+// ============================================================================
+registerResources(server, rebilliaClient);
+// ============================================================================
+// Handle tools/list
+// ============================================================================
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: getToolDefinitions(),
+    };
+});
+// ============================================================================
+// Handle tools/call
+// ============================================================================
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const result = await executeTool(name, args, rebilliaClient);
+        if (result) {
+            return result;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unknown tool: ${name}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Start Server
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Rebillia MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});
+//# 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/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.d.ts.map

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

package/dist/prompts/index.js

@@ -0,0 +1,3 @@
+export {};
+// Prompt implementations
+//# sourceMappingURL=index.js.map

package/dist/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":";AAAA,yBAAyB"}

package/dist/resources/api-docs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Rebillia API documentation resources for MCP.
+ * All docs are self-contained; do not fetch external URLs (e.g. apiguide.rebillia.com).
+ * Backend reference: RebilliaServer PublicAPI
+ */
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare const RESOURCE_URI_PREFIX = "rebillia://api/";
+export declare const DOCS_URI_PREFIX = "rebillia://docs/";
+export interface ApiResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    text: string;
+}
+/** Doc keys supported by get_api_docs tool */
+export declare const DOC_KEYS: readonly ["overview", "models", "subscription-statuses", "charge-types", "gateways"];
+export type DocKey = (typeof DOC_KEYS)[number];
+/** Get documentation markdown by key (for get_api_docs tool). Returns null if key unknown. */
+export declare function getDocContent(doc: DocKey): string | null;
+/** MCP resource URI for countries list (id, code, name). Use for discoverability of valid countryCode values. */
+export declare const GLOBALS_COUNTRIES_URI = "rebillia://globals/countries";
+/** MCP resource URI for global gateways list (gblGatewayId, name, requiredFields). Use before create_gateway. */
+export declare const GLOBALS_GATEWAYS_URI = "rebillia://globals/gateways";
+/**
+ * Register API documentation resources (and optionally globals/countries) with the MCP server.
+ * Pass client to enable the rebillia://globals/countries resource (fetched from upstream).
+ */
+export declare function registerResources(server: Server, client?: InstanceType<typeof import("../client.js").default>): void;
+export declare const apiResources: ApiResource[];
+//# sourceMappingURL=api-docs.d.ts.map

package/dist/resources/api-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-docs.d.ts","sourceRoot":"","sources":["../../src/resources/api-docs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAMxE,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AACrD,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAyRD,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,sFAAuF,CAAC;AAC7G,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIxD;AAED,iHAAiH;AACjH,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,iHAAiH;AACjH,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAwBlE;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,CAAC,cAAc,cAAc,EAAE,OAAO,CAAC,GAC3D,IAAI,CA6CN;AAMD,eAAO,MAAM,YAAY,EAAE,WAAW,EA6DrC,CAAC"}

package/dist/resources/api-docs.js

@@ -0,0 +1,425 @@
+/**
+ * Rebillia API documentation resources for MCP.
+ * All docs are self-contained; do not fetch external URLs (e.g. apiguide.rebillia.com).
+ * Backend reference: RebilliaServer PublicAPI
+ */
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+export const RESOURCE_URI_PREFIX = "rebillia://api/";
+export const DOCS_URI_PREFIX = "rebillia://docs/";
+/** Four API documentation resources (rebillia://docs/*) for MCP Inspector Resources tab */
+const docResources = [
+    {
+        uri: `${DOCS_URI_PREFIX}overview`,
+        name: "Overview documentation",
+        description: "Rebillia API overview – read this first. Base URLs, authentication, pagination, date format, amount handling. Main entry point for Rebillia API docs.",
+        mimeType: "text/markdown",
+        text: `# Rebillia Public API – Overview documentation
+
+**This is the Rebillia API overview.** All reference material is in these MCP resources (rebillia://docs/*). Do not fetch external URLs; use \`resources/read\` with the URIs below. The rest of this document and the other docs contain everything needed.
+
+## Base URLs
+
+| Environment | Base URL |
+|-------------|----------|
+| Production | \`https://api.rebillia.com/v1\` |
+| Sandbox | \`https://sandboxapi.rebillia.com/v1\` |
+
+Override with \`REBILLIA_API_URL\` (include \`/v1\`).
+
+## Authentication
+
+- **Header:** \`X-AUTH-TOKEN\` (required) – your Rebillia API key
+- **Content-Type:** \`application/json\` for request bodies
+- Missing or invalid key returns \`401 Unauthorized\`
+
+## Pagination
+
+List endpoints return a paginated shape:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`currentPageNumber\` | number | Current page (1-based) |
+| \`itemsPerPage\` | number | Page size |
+| \`totalItems\` | number | Total count |
+| \`totalPages\` | number | Total pages |
+| \`data\` | array | Items for the page |
+
+**Common query params:** \`pageNo\` (default 1), \`itemPerPage\` (default 25, max 250).
+
+## Date / time format
+
+- Use **ISO 8601** when the API expects a datetime (e.g. \`newDateTime\` for bill runs): \`YYYY-MM-DDTHH:MM:SS\` or with timezone \`YYYY-MM-DDTHH:MM:SSZ\`.
+- Date-only fields often use \`YYYY-MM-DD\` (e.g. \`effectiveStartDate\`, \`dateDue\`).
+
+## Amount handling
+
+- **Invoice charge / transaction amounts:** Many endpoints use amounts in **cents** (e.g. \`5500\` = $55.00). Check per endpoint.
+- **Refund (transactions):** \`amount\` in **cents** (e.g. \`250\` = $2.50).
+- **Invoice detail line items (create):** \`amount\` as **dollar string** (e.g. \`"20.00"\`) or number in cents (converted to dollars by the tool).
+- **Shipping:** \`orderAmount\` in company currency units; \`weight\` per company metrics (oz, kg, etc.).
+
+## Other documentation resources
+
+**Do not fetch external URLs.** Use only these MCP resources. Read them via MCP \`resources/read\` with the URI:
+
+| Resource | URI | Contents |
+|----------|-----|----------|
+| **Overview** (this doc) | \`rebillia://docs/overview\` | Base URLs, auth, pagination, dates, amounts |
+| Data models | \`rebillia://docs/models\` | Domain model hierarchy and relationships |
+| Subscription statuses | \`rebillia://docs/subscription-statuses\` | active, paused, archived, requestPayment |
+| Charge types | \`rebillia://docs/charge-types\` | chargeType, chargeModel, billingPeriod, billingTiming |
+| Gateways | \`rebillia://docs/gateways\` | list_global_gateways + create_gateway flow (gblGatewayId, setting) |
+`,
+    },
+    {
+        uri: `${DOCS_URI_PREFIX}models`,
+        name: "rebillia-data-models",
+        description: "Domain model hierarchy and relationships",
+        mimeType: "text/markdown",
+        text: `# Rebillia – Domain model hierarchy and relationships
+
+High-level domain model for the Rebillia Public API (aligned with RebilliaServer entities and normalizers).
+
+## Company-scoped entities
+
+- **Company** – Tenant; all data is scoped by company (via API key).
+- **Company currency** – Currency used by the company (linked to Gbl currency); has conversion rate, fixed rate; can be default.
+- **Company gateway** – Payment gateway configuration (Stripe, etc.); has credentials (setting), display name, card types.
+- **Company integration** – Integration instance (e.g. BigCommerce, Shopify, Avalara, SMTP) per company; has section/type (ecommerce, tax, shipping, etc.).
+- **Company filter** – Saved filter (display name, section, rules) for list views (invoices, subscriptions, customers, etc.).
+
+## Core billing hierarchy
+
+\`\`\`
+Company
+  ├── Customers
+  │     ├── Address book (billing/shipping)
+  │     ├── Payment methods (customer payment method)
+  │     ├── Invoices (customer-scoped)
+  │     └── Subscriptions
+  ├── Products
+  │     └── Product rate plans
+  │           └── Product rate plan charges (chargeType, chargeModel, tiers)
+  ├── Subscriptions (customer + company currency + optional gateway)
+  │     ├── Rate plans (product rate plan, charges, quantity)
+  │     └── Rate plan charges (quantity, tier, billing period)
+  ├── Invoices (customer, currency, gateway; line items, transactions)
+  │     └── Transactions (payment/refund/void)
+  ├── Bill runs (scheduled runs; target date/time)
+  ├── Currencies (company currencies; default)
+  └── Gateways (company gateways; test connection)
+\`\`\`
+
+## Key relationships
+
+- **Subscription** → Customer, Company currency, optional Company gateway, optional payment method; contains **Rate plans** (product rate plan ref + rate plan charges).
+- **Invoice** → Customer, Company currency/gateway; has **Detail** (line items) and **Transactions**.
+- **Transaction** → Invoice (or standalone); amount, status, payment type (e.g. thirdPartyPaymentProvider).
+- **Product rate plan** → Product; has **Product rate plan charges** (charge type, model, billing period, tiers).
+- **Filter** → Section (e.g. subscriptions, invoices, customers); **Rules** (attribute, operator, setting values).
+`,
+    },
+    {
+        uri: `${DOCS_URI_PREFIX}subscription-statuses`,
+        name: "rebillia-subscription-statuses",
+        description: "Status guide (active, paused, archived, requestPayment)",
+        mimeType: "text/markdown",
+        text: `# Rebillia – Subscription statuses
+
+Subscription status values used by the Rebillia Public API (Subscription entity / SubscriptionValidator).
+
+## Status values
+
+| Status | Value | Description |
+|--------|--------|-------------|
+| **Active** | \`active\` | Subscription is active; billing and charges apply per schedule. |
+| **Paused** | \`paused\` | Subscription is paused; billing suspended until resumed. |
+| **Archived** | \`archived\` | Subscription is ended/archived; no longer active. |
+| **Request payment** | \`requestPayment\` | Payment is requested (e.g. awaiting payment). |
+
+## Usage
+
+- **List/filter:** Use \`status\` query param (e.g. \`GET /subscriptions?status=active\`).
+- **Update status:** \`PUT /subscriptions/{id}\` or dedicated status endpoint with body \`{ "status": "archived" }\` (or \`active\`, \`paused\`, \`requestPayment\` as allowed by the API).
+- **Create:** New subscriptions are typically created in \`active\` or as per API rules.
+
+## Allowed transitions
+
+- Check RebilliaServer \`SubscriptionValidator\` and subscription service for allowed status transitions (e.g. \`active\` → \`paused\`, \`active\` → \`archived\`, \`requestPayment\` → \`active\`).
+`,
+    },
+    {
+        uri: `${DOCS_URI_PREFIX}charge-types`,
+        name: "rebillia-charge-types",
+        description: "Charge type reference (chargeType, chargeModel, billingPeriod, billingTiming enums)",
+        mimeType: "text/markdown",
+        text: `# Rebillia – Charge type reference
+
+Enums for rate plan charges and product rate plan charges (RebilliaServer PublicAPI / entity constants).
+
+## chargeType
+
+| Value | Description |
+|-------|-------------|
+| \`oneTime\` | One-time charge |
+| \`recurring\` | Recurring charge (billing period applies) |
+| \`usage\` | Usage-based charge |
+
+## chargeModel
+
+| Value | Description |
+|-------|-------------|
+| \`flatFee\` | Flat fee pricing |
+| \`perUnit\` | Per-unit pricing |
+| \`tiered\` | Tiered pricing (charge tiers) |
+| \`volume\` | Volume pricing |
+| \`overage\` | Overage pricing |
+
+## billingPeriod
+
+Used for recurring charges (e.g. \`recurring\` chargeType).
+
+| Value | Description |
+|-------|-------------|
+| \`day\` | Daily |
+| \`week\` | Weekly |
+| \`month\` | Monthly |
+| \`quarter\` | Quarterly |
+| \`year\` | Yearly |
+
+## billingTiming
+
+| Value | Description |
+|-------|-------------|
+| \`inAdvance\` | Billed in advance of the period |
+| \`inArrears\` | Billed in arrears (after the period) |
+
+## Typical usage
+
+- **Create rate plan charge:** \`chargeType\`, \`chargeModel\`, \`billCycleType\`, \`category\`, \`chargeTier\` (array), \`taxable\`, \`weight\`, \`endDateCondition\`; for recurring, \`billingPeriod\` and \`billingTiming\` (and alignment) apply.
+- **Subscription rate plan charges:** Inherit from product rate plan charge; quantity and overrides per subscription.
+`,
+    },
+    {
+        uri: `${DOCS_URI_PREFIX}gateways`,
+        name: "rebillia-gateways",
+        description: "Gateway creation flow: list_global_gateways and create_gateway (gblGatewayId, setting)",
+        mimeType: "text/markdown",
+        text: `# Rebillia – Gateway creation (list_global_gateways + create_gateway)
+
+Use the MCP tools to discover available gateway types and their required credentials, then create a company gateway.
+
+## list_global_gateways
+
+**Tool:** \`list_global_gateways\`  
+**Endpoint:** \`GET /globals/gateways\` (no \`/v1\` prefix, same as \`/globals/countries\`).
+
+Returns available global gateway types (e.g. Stripe, Braintree). Each item includes:
+
+| Field | Description |
+|-------|-------------|
+| \`gblGatewayId\` | Use this as \`gblGatewayId\` in \`create_gateway\`. |
+| \`name\` | Human-readable gateway name. |
+| \`keyName\` | Internal key (e.g. \`stripe\`, \`braintree\`). |
+| \`requiredFields\` | Array of setting key names (e.g. \`publicKey\`, \`privateKey\`, \`merchantId\`). Build the \`setting\` object with these keys. |
+| \`fieldDetails\` | Optional array of \`{ keyName, displayName }\` for better UX when prompting for credentials. |
+
+## create_gateway
+
+**Tool:** \`create_gateway\`  
+**Endpoint:** \`POST /v1/gateways\`.
+
+**Required:** \`gblGatewayId\`, \`setting\` (object with credential key-value pairs).  
+**Optional:** \`displayName\`, \`card\` (array of card type IDs), \`paymentMethod\`.
+
+The \`setting\` object must contain one key per \`requiredFields\` from the chosen global gateway. Keys are the field names (e.g. \`publicKey\`, \`privateKey\`); values are strings or numbers (your API keys, merchant ID, etc.).
+
+## Example flow
+
+1. **Call \`list_global_gateways\`** – no parameters.
+2. **Pick a gateway** – e.g. Stripe or Braintree from the returned list. Note its \`gblGatewayId\` and \`requiredFields\` (or \`fieldDetails\`).
+3. **Build \`setting\`** – create an object with one entry per required field:
+   - Keys = \`requiredFields\` (e.g. \`publicKey\`, \`privateKey\`).
+   - Values = the user's or company's credential values (strings/numbers).
+4. **Call \`create_gateway\`** with \`gblGatewayId\` from step 2 and the \`setting\` object from step 3. Optionally set \`displayName\`.
+
+Example (pseudo):
+
+\`\`\`
+list_global_gateways() → e.g. { gblGatewayId: 1, name: "Stripe", requiredFields: ["publicKey", "privateKey"] }
+create_gateway({ gblGatewayId: 1, setting: { publicKey: "pk_...", privateKey: "sk_..." } })
+\`\`\`
+
+No hardcoded gateway IDs or credential field names are needed; everything is discovered via \`list_global_gateways\`.
+`,
+    },
+];
+/** List shape for MCP resources/list */
+function getDocResourcesList() {
+    return docResources.map(({ uri, name, description, mimeType }) => ({
+        uri,
+        name,
+        description,
+        mimeType,
+    }));
+}
+/** Read one resource by URI; returns MCP contents or null */
+function getDocResourceContent(uri) {
+    const resource = docResources.find((r) => r.uri === uri);
+    if (!resource)
+        return null;
+    return {
+        contents: [
+            {
+                uri: resource.uri,
+                mimeType: resource.mimeType,
+                text: resource.text,
+            },
+        ],
+    };
+}
+/** Doc keys supported by get_api_docs tool */
+export const DOC_KEYS = ["overview", "models", "subscription-statuses", "charge-types", "gateways"];
+/** Get documentation markdown by key (for get_api_docs tool). Returns null if key unknown. */
+export function getDocContent(doc) {
+    const uri = `${DOCS_URI_PREFIX}${doc}`;
+    const resource = docResources.find((r) => r.uri === uri);
+    return resource ? resource.text : null;
+}
+/** MCP resource URI for countries list (id, code, name). Use for discoverability of valid countryCode values. */
+export const GLOBALS_COUNTRIES_URI = "rebillia://globals/countries";
+/** MCP resource URI for global gateways list (gblGatewayId, name, requiredFields). Use before create_gateway. */
+export const GLOBALS_GATEWAYS_URI = "rebillia://globals/gateways";
+/** List of resources including optional globals (countries, gateways) when client is provided */
+function getResourcesList(client) {
+    const list = getDocResourcesList();
+    if (client) {
+        list.push({
+            uri: GLOBALS_COUNTRIES_URI,
+            name: "Countries",
+            description: "Supported countries (id, code, name). Use code (ISO 3166-1 alpha-2) as countryCode in address tools.",
+            mimeType: "application/json",
+        }, {
+            uri: GLOBALS_GATEWAYS_URI,
+            name: "Global gateways",
+            description: "Available gateway types (gblGatewayId, name, keyName, requiredFields, fieldDetails). Use with create_gateway.",
+            mimeType: "application/json",
+        });
+    }
+    return list;
+}
+/**
+ * Register API documentation resources (and optionally globals/countries) with the MCP server.
+ * Pass client to enable the rebillia://globals/countries resource (fetched from upstream).
+ */
+export function registerResources(server, client) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return { resources: getResourcesList(client) };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        if (uri === GLOBALS_COUNTRIES_URI) {
+            if (!client) {
+                throw new Error(`Resource not available: ${uri} (no API client)`);
+            }
+            const { getCountries } = await import("../services/countryResolverService.js");
+            const countries = await getCountries(client);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(countries, null, 2),
+                    },
+                ],
+            };
+        }
+        if (uri === GLOBALS_GATEWAYS_URI) {
+            if (!client) {
+                throw new Error(`Resource not available: ${uri} (no API client)`);
+            }
+            const { listGlobalGateways } = await import("../services/globalGatewayService.js");
+            const gateways = await listGlobalGateways(client);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(gateways, null, 2),
+                    },
+                ],
+            };
+        }
+        const result = getDocResourceContent(uri);
+        if (!result) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        return result;
+    });
+}
+// ============================================================================
+// Legacy api resources (rebillia://api/*) – kept for backward compatibility
+// ============================================================================
+export const apiResources = [
+    {
+        uri: `${RESOURCE_URI_PREFIX}overview`,
+        name: "Rebillia API Overview",
+        description: "Introduction to the Rebillia Public API and where to find the full reference",
+        mimeType: "text/markdown",
+        text: `# Rebillia Public API – Overview
+
+The **Rebillia Public API** lets you manage customers, subscriptions, invoices, payments, and related billing data.
+
+## Documentation
+
+Use the MCP resources (rebillia://docs/overview, models, subscription-statuses, charge-types). Do not fetch external sites.
+
+## Base URL
+
+- Production: \`https://api.rebillia.com/v1\`
+- Override with \`REBILLIA_API_URL\` if using another environment.
+
+## Authentication
+
+All requests use the **X-AUTH-TOKEN** header with your API key.
+
+## Pagination
+
+List endpoints return: \`currentPageNumber\`, \`itemsPerPage\`, \`totalItems\`, \`totalPages\`, \`data\`.
+Common query params: \`pageNo\` (default 1), \`itemPerPage\` (default 25, max 250).
+`,
+    },
+    {
+        uri: `${RESOURCE_URI_PREFIX}authentication`,
+        name: "Authentication",
+        description: "How to authenticate requests to the Rebillia Public API",
+        mimeType: "text/markdown",
+        text: `# Rebillia API – Authentication
+
+- **Header:** \`X-AUTH-TOKEN\` (required)
+- **Content-Type:** \`application/json\` for request bodies
+`,
+    },
+    {
+        uri: `${RESOURCE_URI_PREFIX}customers`,
+        name: "Customers API",
+        description: "List, get, and create customers",
+        mimeType: "text/markdown",
+        text: `# Rebillia API – Customers. Base path: \`/v1/customers\`. Use MCP resources (rebillia://docs/*) for reference; do not fetch external URLs.`,
+    },
+    {
+        uri: `${RESOURCE_URI_PREFIX}subscriptions`,
+        name: "Subscriptions API",
+        description: "Subscriptions, rate plans, and rate plan charges",
+        mimeType: "text/markdown",
+        text: `# Rebillia API – Subscriptions. Base path: \`/v1/subscriptions\`. Use MCP resources (rebillia://docs/*) for reference; do not fetch external URLs.`,
+    },
+    {
+        uri: `${RESOURCE_URI_PREFIX}invoices`,
+        name: "Invoices API",
+        description: "Invoices, details, and payment status",
+        mimeType: "text/markdown",
+        text: `# Rebillia API – Invoices. Base path: \`/v1/invoices\`. Use MCP resources (rebillia://docs/*) for reference; do not fetch external URLs.`,
+    },
+];
+//# sourceMappingURL=api-docs.js.map

package/dist/resources/api-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-docs.js","sourceRoot":"","sources":["../../src/resources/api-docs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oCAAoC,CAAC;AAE5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAUlD,2FAA2F;AAC3F,MAAM,YAAY,GAAkB;IAClC;QACE,GAAG,EAAE,GAAG,eAAe,UAAU;QACjC,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EAAE,uJAAuJ;QACpK,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDT;KACE;IACD;QACE,GAAG,EAAE,GAAG,eAAe,QAAQ;QAC/B,IAAI,EAAE,sBAAsB;QAC5B,WAAW,EAAE,0CAA0C;QACvD,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCT;KACE;IACD;QACE,GAAG,EAAE,GAAG,eAAe,uBAAuB;QAC9C,IAAI,EAAE,gCAAgC;QACtC,WAAW,EAAE,yDAAyD;QACtE,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;CAsBT;KACE;IACD;QACE,GAAG,EAAE,GAAG,eAAe,cAAc;QACrC,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,qFAAqF;QAClG,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CT;KACE;IACD;QACE,GAAG,EAAE,GAAG,eAAe,UAAU;QACjC,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,wFAAwF;QACrG,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CT;KACE;CACF,CAAC;AAEF,wCAAwC;AACxC,SAAS,mBAAmB;IAM1B,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;QACjE,GAAG;QACH,IAAI;QACJ,WAAW;QACX,QAAQ;KACT,CAAC,CAAC,CAAC;AACN,CAAC;AAED,6DAA6D;AAC7D,SAAS,qBAAqB,CAAC,GAAW;IACxC,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACzD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI;aACpB;SACF;KACF,CAAC;AACJ,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,uBAAuB,EAAE,cAAc,EAAE,UAAU,CAAU,CAAC;AAG7G,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,GAAG,GAAG,GAAG,eAAe,GAAG,GAAG,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACzD,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED,iHAAiH;AACjH,MAAM,CAAC,MAAM,qBAAqB,GAAG,8BAA8B,CAAC;AAEpE,iHAAiH;AACjH,MAAM,CAAC,MAAM,oBAAoB,GAAG,6BAA6B,CAAC;AAElE,iGAAiG;AACjG,SAAS,gBAAgB,CAAC,MAA4D;IACpF,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;IACnC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,CAAC,IAAI,CACP;YACE,GAAG,EAAE,qBAAqB;YAC1B,IAAI,EAAE,WAAW;YACjB,WAAW,EAAE,sGAAsG;YACnH,QAAQ,EAAE,kBAAkB;SAC7B,EACD;YACE,GAAG,EAAE,oBAAoB;YACzB,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,+GAA+G;YAC5H,QAAQ,EAAE,kBAAkB;SAC7B,CACF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAA4D;IAE5D,MAAM,CAAC,iBAAiB,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE;QAC9D,OAAO,EAAE,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,yBAAyB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACpE,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;QAC/B,IAAI,GAAG,KAAK,qBAAqB,EAAE,CAAC;YAClC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,kBAAkB,CAAC,CAAC;YACpE,CAAC;YACD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,uCAAuC,CAAC,CAAC;YAC/E,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;YAC7C,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG;wBACH,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;qBACzC;iBACF;aACF,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,KAAK,oBAAoB,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,kBAAkB,CAAC,CAAC;YACpE,CAAC;YACD,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,qCAAqC,CAAC,CAAC;YACnF,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG;wBACH,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;qBACxC;iBACF;aACF,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAkB;IACzC;QACE,GAAG,EAAE,GAAG,mBAAmB,UAAU;QACrC,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,8EAA8E;QAC3F,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;CAqBT;KACE;IACD;QACE,GAAG,EAAE,GAAG,mBAAmB,gBAAgB;QAC3C,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,yDAAyD;QACtE,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE;;;;CAIT;KACE;IACD;QACE,GAAG,EAAE,GAAG,mBAAmB,WAAW;QACtC,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,iCAAiC;QAC9C,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE,4IAA4I;KACnJ;IACD;QACE,GAAG,EAAE,GAAG,mBAAmB,eAAe;QAC1C,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,kDAAkD;QAC/D,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE,oJAAoJ;KAC3J;IACD;QACE,GAAG,EAAE,GAAG,mBAAmB,UAAU;QACrC,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,uCAAuC;QACpD,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE,0IAA0I;KACjJ;CACF,CAAC"}

package/dist/resources/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rebillia MCP resources – API documentation for understanding the Rebillia Public API.
+ * Content is derived from https://apiguide.rebillia.com/
+ */
+export type { ApiResource } from "./api-docs.js";
+/** List all available API documentation resources */
+export declare function listResources(): Array<{
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}>;
+/** Read a resource by URI. Returns contents array for MCP or null if not found. */
+export declare function readResource(uri: string): {
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+} | null;
+export { RESOURCE_URI_PREFIX, apiResources } from "./api-docs.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/resources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,qDAAqD;AACrD,wBAAgB,aAAa,IAAI,KAAK,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAOD;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IACzC,QAAQ,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE,GAAG,IAAI,CAYP;AAED,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/resources/index.js

@@ -0,0 +1,31 @@
+/**
+ * Rebillia MCP resources – API documentation for understanding the Rebillia Public API.
+ * Content is derived from https://apiguide.rebillia.com/
+ */
+import { apiResources } from "./api-docs.js";
+/** List all available API documentation resources */
+export function listResources() {
+    return apiResources.map(({ uri, name, description, mimeType }) => ({
+        uri,
+        name,
+        description,
+        mimeType,
+    }));
+}
+/** Read a resource by URI. Returns contents array for MCP or null if not found. */
+export function readResource(uri) {
+    const resource = apiResources.find((r) => r.uri === uri);
+    if (!resource)
+        return null;
+    return {
+        contents: [
+            {
+                uri: resource.uri,
+                mimeType: resource.mimeType,
+                text: resource.text,
+            },
+        ],
+    };
+}
+export { RESOURCE_URI_PREFIX, apiResources } from "./api-docs.js";
+//# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAuB,MAAM,eAAe,CAAC;AAIlE,qDAAqD;AACrD,MAAM,UAAU,aAAa;IAM3B,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;QACjE,GAAG;QACH,IAAI;QACJ,WAAW;QACX,QAAQ;KACT,CAAC,CAAC,CAAC;AACN,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,GAAW;IAGtC,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACzD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI;aACpB;SACF;KACF,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}