@calixpay/mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calix Pay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# Calix Pay MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let an AI agent accept payments through **Calix Pay** as native tools — create hosted checkout sessions, charge cards and ACH, and fetch the in-app tokenization config. Works with Claude Desktop, Cursor, and any MCP-compatible client.
+
+Calix Pay is a Stripe-style payments API for apps, platforms, marketplaces, and high-risk/specialty businesses. White-label, developer-first, AI-ready.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `create_checkout_session` | Create a hosted checkout URL (one-time or subscription). Simplest, zero-PCI. |
+| `create_charge` | Charge a tokenized card (token from Calix Pay.js). Idempotent. |
+| `create_ach_charge` | Charge a bank account via ACH. Idempotent. |
+| `get_client_config` | Get the Calix Pay.js tokenization key + script URL for in-browser tokenization. |
+
+## Setup
+
+You need a Calix Pay API key from your dashboard → **Developers → API keys**.
+- `sk_test_…` = **sandbox** (no real money) — use while building.
+- `sk_live_…` = **live** (real charges) — swap in for production, no other changes.
+
+### Install
+
+```bash
+cd mcp
+npm install
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "calixpay": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/index.mjs"],
+      "env": { "CALIXPAY_API_KEY": "sk_test_your_key" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "calixpay": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/index.mjs"],
+      "env": { "CALIXPAY_API_KEY": "sk_test_your_key" }
+    }
+  }
+}
+```
+
+Restart the client, and your agent can call the Calix Pay tools directly — e.g. "create a $29.99 checkout session for a Pro plan and give me the URL."
+
+## Environment
+
+| Var | Required | Default |
+| --- | --- | --- |
+| `CALIXPAY_API_KEY` | yes | — |
+| `CALIXPAY_API_BASE` | no | `https://api.calixpay.co/api/v1` |
+
+## Notes
+
+- Keep your `sk_live_` key private — treat it like a password. The server reads it from the environment; it is never logged.
+- Charges are automatically sent with a unique idempotency key, so a retried tool call never double-charges.
+- Full REST reference: <https://calixpay.co/openapi.json> · integration guide: <https://calixpay.co/llms-full.txt>

package/index.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Calix Pay MCP server.
+ *
+ * Exposes Calix Pay's payment API as MCP tools so an AI agent (Claude Desktop,
+ * Cursor, etc.) can create checkout sessions, charge cards/ACH, and fetch the
+ * in-app tokenization config — all with the merchant's own API key.
+ *
+ * Config (environment):
+ *   CALIXPAY_API_KEY   required — your secret key (sk_test_… sandbox, sk_live_… live)
+ *   CALIXPAY_API_BASE  optional — defaults to https://api.calixpay.co/api/v1
+ *
+ * The key decides the mode: sk_test_ = sandbox (no real money), sk_live_ = real.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+
+const API_BASE = (process.env.CALIXPAY_API_BASE || 'https://api.calixpay.co/api/v1').replace(/\/$/, '');
+const API_KEY = process.env.CALIXPAY_API_KEY || '';
+
+async function call(method, path, { body, idempotent } = {}) {
+  if (!API_KEY) {
+    return { ok: false, text: 'CALIXPAY_API_KEY is not set. Add your Calix Pay secret key (sk_test_… or sk_live_…) to the server environment.' };
+  }
+  const headers = { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' };
+  if (idempotent) headers['Idempotency-Key'] = randomUUID();
+  let res, json;
+  try {
+    res = await fetch(`${API_BASE}${path}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
+    const raw = await res.text();
+    try { json = JSON.parse(raw); } catch { json = raw; }
+  } catch (err) {
+    return { ok: false, text: `Request failed: ${err?.message || err}` };
+  }
+  const text = typeof json === 'string' ? json : JSON.stringify(json, null, 2);
+  return { ok: res.ok, text: res.ok ? text : `HTTP ${res.status}: ${text}` };
+}
+
+const result = (r) => ({ content: [{ type: 'text', text: r.text }], isError: !r.ok });
+
+const server = new McpServer({ name: 'calixpay', version: '1.0.0' });
+
+server.tool(
+  'create_checkout_session',
+  'Create a Calix Pay hosted checkout session and get a URL to redirect the customer to. Use for the simplest, zero-PCI flow. mode "payment" for one-time, "subscription" for recurring.',
+  {
+    amount: z.number().positive().optional().describe('Amount in dollars (one-time) — or use planId.'),
+    planId: z.string().optional().describe('A saved plan id (for subscriptions).'),
+    mode: z.enum(['payment', 'subscription']).default('payment'),
+    productName: z.string().optional(),
+    currency: z.string().default('USD'),
+    email: z.string().email().optional(),
+    clientReferenceId: z.string().optional().describe('Your order id — echoed back on the webhook.'),
+    successUrl: z.string().url().optional(),
+    cancelUrl: z.string().url().optional(),
+  },
+  async (args) => result(await call('POST', '/checkout/sessions', { body: args })),
+);
+
+server.tool(
+  'create_charge',
+  'Charge a tokenized card. Pass a one-time paymentToken from Calix Pay.js (never a raw card number). Idempotent automatically.',
+  {
+    amount: z.number().positive().describe('Amount in dollars.'),
+    paymentToken: z.string().describe('One-time token from Calix Pay.js.'),
+    email: z.string().email().optional(),
+    description: z.string().optional(),
+  },
+  async ({ amount, paymentToken, email, description }) =>
+    result(await call('POST', '/charges', {
+      idempotent: true,
+      body: { amount, paymentToken, description, customerInfo: email ? { email } : undefined },
+    })),
+);
+
+server.tool(
+  'create_ach_charge',
+  'Charge a bank account via ACH (no card). Idempotent automatically.',
+  {
+    amount: z.number().positive().describe('Amount in dollars.'),
+    routingNumber: z.string(),
+    accountNumber: z.string(),
+    accountHolderName: z.string(),
+    accountType: z.enum(['checking', 'savings']).default('checking'),
+    email: z.string().email().optional(),
+  },
+  async ({ amount, routingNumber, accountNumber, accountHolderName, accountType, email }) =>
+    result(await call('POST', '/charges', {
+      idempotent: true,
+      body: {
+        amount, paymentMethod: 'ach',
+        paymentDetails: { routingNumber, accountNumber, accountHolderName, accountType },
+        customerInfo: email ? { email } : undefined,
+      },
+    })),
+);
+
+server.tool(
+  'get_client_config',
+  'Get the Calix Pay.js tokenization key + script URL for in-browser card tokenization (PCI SAQ-A). Load these in a checkout page to tokenize a card, then charge the token with create_charge.',
+  {},
+  async () => result(await call('GET', '/client-config')),
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Calix Pay MCP server running (base ${API_BASE}, key ${API_KEY ? API_KEY.slice(0, 8) + '…' : 'NOT SET'}).`);

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@calixpay/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Calix Pay MCP server — let an AI agent accept payments (checkout, charges, ACH, tokenization) via Calix Pay.",
+  "type": "module",
+  "bin": { "calixpay-mcp": "./index.mjs" },
+  "main": "./index.mjs",
+  "files": ["index.mjs", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "keywords": ["calixpay", "payments", "mcp", "model-context-protocol", "stripe-alternative", "high-risk", "vibe-coding"],
+  "license": "MIT",
+  "author": "Calix Pay",
+  "homepage": "https://calixpay.co",
+  "repository": { "type": "git", "url": "https://github.com/GetAgentPulse/calixpay", "directory": "mcp" },
+  "bugs": { "url": "https://calixpay.co" },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.0",
+    "zod": "^3.23.8"
+  }
+}