linkpay-mcp 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# LinkPay MCP Server
+
+Manage your LinkPay virtual cards directly from Claude, Cursor, Windsurf, and other AI assistants.
+
+## What it does
+
+Issue cards, check balances, top up, view transactions — all through natural language in your AI tool. No dashboard clicking needed.
+
+## Quick start
+
+### 1. Get your API key
+
+Go to [LinkPay Dashboard](https://linkpay.com) → Settings → API Keys.
+
+### 2. Add to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "linkpay": {
+      "command": "npx",
+      "args": ["-y", "linkpay-mcp"],
+      "env": {
+        "LINKPAY_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 3. Add to Cursor
+
+Edit `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "linkpay": {
+      "command": "npx",
+      "args": ["-y", "linkpay-mcp"],
+      "env": {
+        "LINKPAY_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 4. Use it
+
+Just ask your AI assistant:
+
+- "Show me my card balances"
+- "Issue 3 new USD Visa cards labeled 'Google Ads'"
+- "Top up card ending in 4521 with $200"
+- "Show me last 20 transactions"
+- "How much did I spend on Replit this month?"
+
+## Available tools
+
+| Tool | Description |
+|---|---|
+| `get_user` | Get account info |
+| `get_balances` | View all balances and deposit addresses |
+| `get_plan` | See current fee plan and limits |
+| `list_card_types` | Available card types (network, currency, fees) |
+| `list_cards` | List all cards with balances |
+| `issue_card` | Issue a new virtual card |
+| `get_card_credentials` | Get card number, CVV, expiry |
+| `top_up_card` | Fund a card from your account |
+| `withdraw_from_card` | Pull funds from card back to account |
+| `transfer_funds` | Any transfer (account-to-card, team transfers, etc.) |
+| `get_operations` | Transaction history (all or per-card) |
+| `create_withdrawal` | Crypto withdrawal |
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `LINKPAY_API_KEY` | Yes | Your LinkPay API key |
+| `LINKPAY_BASE_URL` | No | API base URL (default: `https://api.linkpay.com`) |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { LinkPayClient, LinkPayError } from "./linkpay-client.js";
+const API_KEY = process.env.LINKPAY_API_KEY;
+const BASE_URL = process.env.LINKPAY_BASE_URL || "https://api.linkpay.com";
+if (!API_KEY) {
+    console.error("LINKPAY_API_KEY environment variable is required");
+    process.exit(1);
+}
+const client = new LinkPayClient({ apiKey: API_KEY, baseUrl: BASE_URL });
+function errorResult(err) {
+    if (err instanceof LinkPayError) {
+        return { content: [{ type: "text", text: `API error ${err.status}: ${err.body}` }], isError: true };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+}
+function jsonResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+const server = new McpServer({
+    name: "linkpay",
+    version: "0.1.0",
+});
+// --- Account ---
+server.tool("get_user", "Get current LinkPay account info (UUID, email, name)", {}, async () => {
+    try {
+        return jsonResult(await client.getUser());
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("get_balances", "Get all account balances with deposit addresses", {}, async () => {
+    try {
+        return jsonResult(await client.getBalances());
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("get_plan", "Get current fee plan, limits, and fees", {}, async () => {
+    try {
+        return jsonResult(await client.getPlanData());
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+// --- Cards ---
+server.tool("list_card_types", "List available card types (network, currency, fees)", {}, async () => {
+    try {
+        return jsonResult(await client.getCardTypes());
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("list_cards", "List your cards with balances and status. Supports pagination.", {
+    page: z.number().optional().describe("Page number (default 1)"),
+    limit: z.number().optional().describe("Cards per page (default 50, max 100)"),
+}, async ({ page, limit }) => {
+    try {
+        return jsonResult(await client.getCards(page ?? 1, limit ?? 50));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("issue_card", "Issue a new virtual card. Use list_card_types first to get valid cardTypeId values.", {
+    cardTypeId: z.string().describe("Card type ID from list_card_types"),
+    label: z.string().optional().describe("Optional label for the card (e.g. 'Google Ads US')"),
+}, async ({ cardTypeId, label }) => {
+    try {
+        return jsonResult(await client.issueCard({ cardTypeId, label }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("get_card_credentials", "Get full card number, CVV, and expiry for a card. Use carefully — contains sensitive data.", {
+    cardUuid: z.string().describe("Card UUID"),
+}, async ({ cardUuid }) => {
+    try {
+        return jsonResult(await client.getCardCredentials(cardUuid));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+// --- Transfers ---
+server.tool("top_up_card", "Transfer funds from your account to a card", {
+    cardUuid: z.string().describe("Target card UUID"),
+    amount: z.string().describe("Amount to transfer (e.g. '100.00')"),
+    currency: z.string().describe("Currency code (e.g. 'USD')"),
+    fromAccountUuid: z.string().describe("Source account UUID (get from get_balances or get_user)"),
+}, async ({ cardUuid, amount, currency, fromAccountUuid }) => {
+    try {
+        return jsonResult(await client.transferFunds({
+            type: "ACCOUNT_TO_CARD",
+            fromUuid: fromAccountUuid,
+            toUuid: cardUuid,
+            amount,
+            currency,
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("withdraw_from_card", "Transfer funds from a card back to your account", {
+    cardUuid: z.string().describe("Source card UUID"),
+    amount: z.string().describe("Amount to withdraw (e.g. '50.00')"),
+    currency: z.string().describe("Currency code (e.g. 'USD')"),
+    toAccountUuid: z.string().describe("Destination account UUID"),
+}, async ({ cardUuid, amount, currency, toAccountUuid }) => {
+    try {
+        return jsonResult(await client.transferFunds({
+            type: "CARD_TO_ACCOUNT",
+            fromUuid: cardUuid,
+            toUuid: toAccountUuid,
+            amount,
+            currency,
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.tool("transfer_funds", "Transfer funds between accounts or cards. Supports all transfer types: ACCOUNT_TO_CARD, CARD_TO_ACCOUNT, ACCOUNT_TO_ACCOUNT, and team transfers.", {
+    type: z
+        .enum([
+        "ACCOUNT_TO_CARD",
+        "CARD_TO_ACCOUNT",
+        "ACCOUNT_TO_ACCOUNT",
+        "TEAM_ACCOUNT_TO_TEAM_MEMBER_ACCOUNT",
+        "TEAM_MEMBER_ACCOUNT_TO_TEAM_ACCOUNT",
+        "TEAM_MEMBER_ACCOUNT_TO_TEAM_MEMBER_ACCOUNT",
+        "TEAM_MEMBER_ACCOUNT_TO_TEAM_MEMBER_CARD",
+    ])
+        .describe("Transfer type"),
+    fromUuid: z.string().describe("Source UUID (account or card)"),
+    toUuid: z.string().describe("Destination UUID (account or card)"),
+    amount: z.string().describe("Amount (e.g. '100.00')"),
+    currency: z.string().describe("Currency code (e.g. 'USD')"),
+}, async (params) => {
+    try {
+        return jsonResult(await client.transferFunds(params));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+// --- Operations ---
+server.tool("get_operations", "Get transaction history. Filter by card or get all operations.", {
+    cardUuid: z.string().optional().describe("Filter by card UUID"),
+    page: z.number().optional().describe("Page number (default 1)"),
+    limit: z.number().optional().describe("Results per page (default 50)"),
+}, async ({ cardUuid, page, limit }) => {
+    try {
+        return jsonResult(await client.getOperations({
+            cardUuid,
+            page: page ?? 1,
+            limit: limit ?? 50,
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+// --- Withdrawals ---
+server.tool("create_withdrawal", "Create a crypto withdrawal request from your account", {
+    accountUuid: z.string().describe("Source account UUID"),
+    address: z.string().describe("Destination crypto address"),
+    amount: z.string().describe("Amount to withdraw"),
+    currency: z.string().describe("Currency (e.g. 'USDT')"),
+    network: z.string().optional().describe("Network (e.g. 'TRC20', 'ERC20')"),
+}, async ({ accountUuid, address, amount, currency, network }) => {
+    try {
+        return jsonResult(await client.createWithdrawRequest({ accountUuid, address, amount, currency, network }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/linkpay-client.d.ts

@@ -0,0 +1,106 @@
+export interface LinkPayConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+export interface LinkPayBalance {
+    currency: string;
+    amount: string;
+    depositAddress?: string;
+}
+export interface LinkPayCard {
+    uuid: string;
+    type: string;
+    status: string;
+    lastFour: string;
+    balance: string;
+    currency: string;
+    expiryMonth: number;
+    expiryYear: number;
+    label?: string;
+}
+export interface LinkPayCardCredentials {
+    cardNumber: string;
+    cvv: string;
+    expiryMonth: number;
+    expiryYear: number;
+}
+export interface LinkPayCardType {
+    id: string;
+    name: string;
+    network: string;
+    currency: string;
+    issueFee: string;
+    monthlyFee: string;
+}
+export type TransferType = "ACCOUNT_TO_CARD" | "CARD_TO_ACCOUNT" | "ACCOUNT_TO_ACCOUNT" | "TEAM_ACCOUNT_TO_TEAM_MEMBER_ACCOUNT" | "TEAM_MEMBER_ACCOUNT_TO_TEAM_ACCOUNT" | "TEAM_MEMBER_ACCOUNT_TO_TEAM_MEMBER_ACCOUNT" | "TEAM_MEMBER_ACCOUNT_TO_TEAM_MEMBER_CARD";
+export interface LinkPayOperation {
+    uuid: string;
+    type: string;
+    amount: string;
+    currency: string;
+    status: string;
+    merchantName?: string;
+    createdAt: string;
+    cardUuid?: string;
+}
+export interface LinkPayTransferRequest {
+    type: TransferType;
+    fromUuid: string;
+    toUuid: string;
+    amount: string;
+    currency: string;
+}
+export interface LinkPayWithdrawRequest {
+    accountUuid: string;
+    address: string;
+    amount: string;
+    currency: string;
+    network?: string;
+}
+export interface LinkPayPaginatedResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+}
+export declare class LinkPayError extends Error {
+    status: number;
+    body: string;
+    path: string;
+    constructor(status: number, body: string, path: string);
+}
+export declare class LinkPayClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: LinkPayConfig);
+    private request;
+    getUser(): Promise<{
+        uuid: string;
+        email: string;
+        name: string;
+    }>;
+    getBalances(): Promise<LinkPayBalance[]>;
+    getCardTypes(): Promise<LinkPayCardType[]>;
+    getCards(page?: number, limit?: number): Promise<LinkPayPaginatedResponse<LinkPayCard>>;
+    issueCard(params: {
+        cardTypeId: string;
+        label?: string;
+    }): Promise<LinkPayCard>;
+    getCardCredentials(cardUuid: string): Promise<LinkPayCardCredentials>;
+    transferFunds(params: LinkPayTransferRequest): Promise<{
+        uuid: string;
+    }>;
+    getOperations(params: {
+        page?: number;
+        limit?: number;
+        cardUuid?: string;
+    }): Promise<LinkPayPaginatedResponse<LinkPayOperation>>;
+    createWithdrawRequest(params: LinkPayWithdrawRequest): Promise<{
+        uuid: string;
+    }>;
+    getPlanData(): Promise<{
+        plan: string;
+        limits: Record<string, unknown>;
+        fees: Record<string, unknown>;
+    }>;
+}

package/dist/linkpay-client.js

@@ -0,0 +1,73 @@
+export class LinkPayError extends Error {
+    status;
+    body;
+    path;
+    constructor(status, body, path) {
+        super(`LinkPay API error ${status} on ${path}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.path = path;
+        this.name = "LinkPayError";
+    }
+}
+export class LinkPayClient {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                "api-key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new LinkPayError(res.status, text, path);
+        }
+        return res.json();
+    }
+    async getUser() {
+        return this.request("GET", "/getUser");
+    }
+    async getBalances() {
+        return this.request("GET", "/getBalances");
+    }
+    async getCardTypes() {
+        return this.request("GET", "/getCardTypes");
+    }
+    async getCards(page = 1, limit = 50) {
+        return this.request("GET", `/getCards?page=${page}&limit=${limit}`);
+    }
+    async issueCard(params) {
+        return this.request("POST", "/issueCard", params);
+    }
+    async getCardCredentials(cardUuid) {
+        return this.request("GET", `/getCardCredentials?cardUuid=${cardUuid}`);
+    }
+    async transferFunds(params) {
+        return this.request("POST", "/transferFunds", params);
+    }
+    async getOperations(params) {
+        const query = new URLSearchParams();
+        if (params.page)
+            query.set("page", String(params.page));
+        if (params.limit)
+            query.set("limit", String(params.limit));
+        if (params.cardUuid)
+            query.set("cardUuid", params.cardUuid);
+        return this.request("GET", `/getOperations?${query}`);
+    }
+    async createWithdrawRequest(params) {
+        return this.request("POST", "/createWithdrawRequest", params);
+    }
+    async getPlanData() {
+        return this.request("GET", "/getPlanData");
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "linkpay-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for LinkPay card management — issue, manage, and monitor virtual cards from Claude, Cursor, and other AI assistants",
+  "main": "dist/index.js",
+  "bin": {
+    "linkpay-mcp": "dist/index.js"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pnplsrcrr/linkpay-mcp.git"
+  },
+  "homepage": "https://github.com/pnplsrcrr/linkpay-mcp#readme",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "linkpay",
+    "virtual-cards",
+    "card-issuing",
+    "ai",
+    "claude",
+    "cursor",
+    "windsurf"
+  ],
+  "author": "LinkPay",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}