@codespar/mcp-circle 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @codespar/mcp-circle
+
+> MCP server for **Circle** — USDC stablecoin payments, payouts, transfers, and wallets
+
+[![npm](https://img.shields.io/npm/v/@codespar/mcp-circle)](https://www.npmjs.com/package/@codespar/mcp-circle)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "circle": {
+      "command": "npx",
+      "args": ["-y", "@codespar/mcp-circle"],
+      "env": {
+        "CIRCLE_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add circle -- npx @codespar/mcp-circle
+```
+
+### Cursor / VS Code
+
+Add to `.cursor/mcp.json` or `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "circle": {
+      "command": "npx",
+      "args": ["-y", "@codespar/mcp-circle"],
+      "env": {
+        "CIRCLE_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_wallet` | Create a new Circle wallet |
+| `get_wallet` | Get wallet details by ID |
+| `create_payment` | Accept a USDC payment via Circle |
+| `get_payment` | Get payment details by ID |
+| `create_payout` | Create a payout from Circle (USDC to fiat) |
+| `get_payout` | Get payout details by ID |
+| `create_transfer` | Create a USDC transfer between Circle wallets |
+| `get_transfer` | Get transfer details by ID |
+| `get_balance` | Get account balance |
+| `list_transactions` | List transactions with optional filters |
+
+## Authentication
+
+Circle uses a Bearer API key for authentication.
+
+## Sandbox / Testing
+
+Circle provides a sandbox at `api-sandbox.circle.com`. Use a sandbox API key for testing.
+
+### Get your credentials
+
+1. Go to [Circle Developer Portal](https://developers.circle.com)
+2. Create a developer account
+3. Generate a sandbox API key
+4. Set the `CIRCLE_API_KEY` environment variable
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CIRCLE_API_KEY` | Yes | API key from Circle |
+
+## Roadmap
+
+### v0.2 (planned)
+- `create_card_payment` — Create a card payment
+- `create_wire_payment` — Create a wire transfer payment
+- `create_ach_payment` — Create an ACH payment
+- `get_settlement` — Get settlement details
+- `list_settlements` — List settlements with filters
+
+### v0.3 (planned)
+- `smart_contract_calls` — Execute smart contract calls
+- `cross_chain_transfers` — Transfer assets across blockchains
+
+Want to contribute? [Open a PR](https://github.com/codespar/mcp-dev-brasil) or [request a tool](https://github.com/codespar/mcp-dev-brasil/issues).
+
+## Links
+
+- [Circle Website](https://circle.com)
+- [Circle API Documentation](https://developers.circle.com)
+- [MCP Dev Brasil](https://github.com/codespar/mcp-dev-brasil)
+- [Landing Page](https://codespar.dev/mcp)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Circle — USDC stablecoin infrastructure.
+ *
+ * Tools:
+ * - create_wallet: Create a new Circle wallet
+ * - get_wallet: Get wallet details by ID
+ * - create_payment: Accept a USDC payment
+ * - get_payment: Get payment details by ID
+ * - create_payout: Create a payout (USDC to fiat)
+ * - get_payout: Get payout details by ID
+ * - create_transfer: Create a USDC transfer between wallets
+ * - get_transfer: Get transfer details by ID
+ * - get_balance: Get wallet balance
+ * - list_transactions: List transactions with filters
+ *
+ * Environment:
+ *   CIRCLE_API_KEY — API key from https://www.circle.com/
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const API_KEY = process.env.CIRCLE_API_KEY || "";
+const BASE_URL = "https://api.circle.com/v1";
+async function circleRequest(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${API_KEY}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Circle API ${res.status}: ${err}`);
+    }
+    return res.json();
+}
+const server = new Server({ name: "mcp-circle", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "create_wallet",
+            description: "Create a new Circle wallet",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+                    description: { type: "string", description: "Wallet description" },
+                },
+                required: ["idempotencyKey"],
+            },
+        },
+        {
+            name: "get_wallet",
+            description: "Get wallet details by ID",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Wallet ID" },
+                },
+                required: ["id"],
+            },
+        },
+        {
+            name: "create_payment",
+            description: "Accept a USDC payment via Circle",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+                    amount: { type: "object", properties: { amount: { type: "string", description: "Amount (e.g. '10.00')" }, currency: { type: "string", description: "Currency (USD)" } }, required: ["amount", "currency"], description: "Payment amount" },
+                    source: { type: "object", properties: { id: { type: "string", description: "Source ID" }, type: { type: "string", description: "Source type (e.g. card, ach)" } }, required: ["id", "type"], description: "Payment source" },
+                    description: { type: "string", description: "Payment description" },
+                },
+                required: ["idempotencyKey", "amount", "source"],
+            },
+        },
+        {
+            name: "get_payment",
+            description: "Get payment details by ID",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Payment ID" },
+                },
+                required: ["id"],
+            },
+        },
+        {
+            name: "create_payout",
+            description: "Create a payout from Circle (USDC to fiat)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+                    amount: { type: "object", properties: { amount: { type: "string", description: "Amount" }, currency: { type: "string", description: "Currency (USD)" } }, required: ["amount", "currency"], description: "Payout amount" },
+                    destination: { type: "object", properties: { id: { type: "string", description: "Destination ID (bank account)" }, type: { type: "string", description: "Destination type (e.g. wire)" } }, required: ["id", "type"], description: "Payout destination" },
+                },
+                required: ["idempotencyKey", "amount", "destination"],
+            },
+        },
+        {
+            name: "get_payout",
+            description: "Get payout details by ID",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Payout ID" },
+                },
+                required: ["id"],
+            },
+        },
+        {
+            name: "create_transfer",
+            description: "Create a USDC transfer between Circle wallets",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+                    amount: { type: "object", properties: { amount: { type: "string", description: "Amount" }, currency: { type: "string", description: "Currency (USD)" } }, required: ["amount", "currency"], description: "Transfer amount" },
+                    source: { type: "object", properties: { id: { type: "string", description: "Source wallet ID" }, type: { type: "string", description: "Source type (wallet)" } }, required: ["id", "type"], description: "Transfer source" },
+                    destination: { type: "object", properties: { id: { type: "string", description: "Destination wallet ID" }, type: { type: "string", description: "Destination type (wallet, blockchain)" } }, required: ["id", "type"], description: "Transfer destination" },
+                },
+                required: ["idempotencyKey", "amount", "source", "destination"],
+            },
+        },
+        {
+            name: "get_transfer",
+            description: "Get transfer details by ID",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Transfer ID" },
+                },
+                required: ["id"],
+            },
+        },
+        {
+            name: "get_balance",
+            description: "Get account balance",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "list_transactions",
+            description: "List transactions with optional filters",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: { type: "string", enum: ["payment", "payout", "transfer"], description: "Filter by transaction type" },
+                    status: { type: "string", enum: ["pending", "confirmed", "complete", "failed"], description: "Filter by status" },
+                    from: { type: "string", description: "Start date (ISO 8601)" },
+                    to: { type: "string", description: "End date (ISO 8601)" },
+                    pageSize: { type: "number", description: "Number of results per page" },
+                    pageBefore: { type: "string", description: "Cursor for previous page" },
+                    pageAfter: { type: "string", description: "Cursor for next page" },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "create_wallet":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/wallets", args), null, 2) }] };
+            case "get_wallet":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/wallets/${args?.id}`), null, 2) }] };
+            case "create_payment":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/payments", args), null, 2) }] };
+            case "get_payment":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/payments/${args?.id}`), null, 2) }] };
+            case "create_payout":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/payouts", args), null, 2) }] };
+            case "get_payout":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/payouts/${args?.id}`), null, 2) }] };
+            case "create_transfer":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/transfers", args), null, 2) }] };
+            case "get_transfer":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/transfers/${args?.id}`), null, 2) }] };
+            case "get_balance":
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", "/balances"), null, 2) }] };
+            case "list_transactions": {
+                const params = new URLSearchParams();
+                if (args?.type)
+                    params.set("type", String(args.type));
+                if (args?.status)
+                    params.set("status", String(args.status));
+                if (args?.from)
+                    params.set("from", String(args.from));
+                if (args?.to)
+                    params.set("to", String(args.to));
+                if (args?.pageSize)
+                    params.set("pageSize", String(args.pageSize));
+                if (args?.pageBefore)
+                    params.set("pageBefore", String(args.pageBefore));
+                if (args?.pageAfter)
+                    params.set("pageAfter", String(args.pageAfter));
+                return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/transactions?${params}`), null, 2) }] };
+            }
+            default:
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+        }
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+});
+async function main() {
+    if (!API_KEY) {
+        console.error("CIRCLE_API_KEY environment variable is required");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@codespar/mcp-circle",
+  "version": "0.1.0",
+  "description": "MCP server for Circle — USDC payments, wallets, payouts, transfers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "mcp-circle": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "circle",
+    "usdc",
+    "crypto",
+    "stablecoin",
+    "payments"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server for Circle — USDC stablecoin infrastructure.
+ *
+ * Tools:
+ * - create_wallet: Create a new Circle wallet
+ * - get_wallet: Get wallet details by ID
+ * - create_payment: Accept a USDC payment
+ * - get_payment: Get payment details by ID
+ * - create_payout: Create a payout (USDC to fiat)
+ * - get_payout: Get payout details by ID
+ * - create_transfer: Create a USDC transfer between wallets
+ * - get_transfer: Get transfer details by ID
+ * - get_balance: Get wallet balance
+ * - list_transactions: List transactions with filters
+ *
+ * Environment:
+ *   CIRCLE_API_KEY — API key from https://www.circle.com/
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_KEY = process.env.CIRCLE_API_KEY || "";
+const BASE_URL = "https://api.circle.com/v1";
+
+async function circleRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${API_KEY}`,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Circle API ${res.status}: ${err}`);
+  }
+  return res.json();
+}
+
+const server = new Server(
+  { name: "mcp-circle", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "create_wallet",
+      description: "Create a new Circle wallet",
+      inputSchema: {
+        type: "object",
+        properties: {
+          idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+          description: { type: "string", description: "Wallet description" },
+        },
+        required: ["idempotencyKey"],
+      },
+    },
+    {
+      name: "get_wallet",
+      description: "Get wallet details by ID",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Wallet ID" },
+        },
+        required: ["id"],
+      },
+    },
+    {
+      name: "create_payment",
+      description: "Accept a USDC payment via Circle",
+      inputSchema: {
+        type: "object",
+        properties: {
+          idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+          amount: { type: "object", properties: { amount: { type: "string", description: "Amount (e.g. '10.00')" }, currency: { type: "string", description: "Currency (USD)" } }, required: ["amount", "currency"], description: "Payment amount" },
+          source: { type: "object", properties: { id: { type: "string", description: "Source ID" }, type: { type: "string", description: "Source type (e.g. card, ach)" } }, required: ["id", "type"], description: "Payment source" },
+          description: { type: "string", description: "Payment description" },
+        },
+        required: ["idempotencyKey", "amount", "source"],
+      },
+    },
+    {
+      name: "get_payment",
+      description: "Get payment details by ID",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Payment ID" },
+        },
+        required: ["id"],
+      },
+    },
+    {
+      name: "create_payout",
+      description: "Create a payout from Circle (USDC to fiat)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+          amount: { type: "object", properties: { amount: { type: "string", description: "Amount" }, currency: { type: "string", description: "Currency (USD)" } }, required: ["amount", "currency"], description: "Payout amount" },
+          destination: { type: "object", properties: { id: { type: "string", description: "Destination ID (bank account)" }, type: { type: "string", description: "Destination type (e.g. wire)" } }, required: ["id", "type"], description: "Payout destination" },
+        },
+        required: ["idempotencyKey", "amount", "destination"],
+      },
+    },
+    {
+      name: "get_payout",
+      description: "Get payout details by ID",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Payout ID" },
+        },
+        required: ["id"],
+      },
+    },
+    {
+      name: "create_transfer",
+      description: "Create a USDC transfer between Circle wallets",
+      inputSchema: {
+        type: "object",
+        properties: {
+          idempotencyKey: { type: "string", description: "Unique idempotency key (UUID)" },
+          amount: { type: "object", properties: { amount: { type: "string", description: "Amount" }, currency: { type: "string", description: "Currency (USD)" } }, required: ["amount", "currency"], description: "Transfer amount" },
+          source: { type: "object", properties: { id: { type: "string", description: "Source wallet ID" }, type: { type: "string", description: "Source type (wallet)" } }, required: ["id", "type"], description: "Transfer source" },
+          destination: { type: "object", properties: { id: { type: "string", description: "Destination wallet ID" }, type: { type: "string", description: "Destination type (wallet, blockchain)" } }, required: ["id", "type"], description: "Transfer destination" },
+        },
+        required: ["idempotencyKey", "amount", "source", "destination"],
+      },
+    },
+    {
+      name: "get_transfer",
+      description: "Get transfer details by ID",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Transfer ID" },
+        },
+        required: ["id"],
+      },
+    },
+    {
+      name: "get_balance",
+      description: "Get account balance",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "list_transactions",
+      description: "List transactions with optional filters",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", enum: ["payment", "payout", "transfer"], description: "Filter by transaction type" },
+          status: { type: "string", enum: ["pending", "confirmed", "complete", "failed"], description: "Filter by status" },
+          from: { type: "string", description: "Start date (ISO 8601)" },
+          to: { type: "string", description: "End date (ISO 8601)" },
+          pageSize: { type: "number", description: "Number of results per page" },
+          pageBefore: { type: "string", description: "Cursor for previous page" },
+          pageAfter: { type: "string", description: "Cursor for next page" },
+        },
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "create_wallet":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/wallets", args), null, 2) }] };
+      case "get_wallet":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/wallets/${args?.id}`), null, 2) }] };
+      case "create_payment":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/payments", args), null, 2) }] };
+      case "get_payment":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/payments/${args?.id}`), null, 2) }] };
+      case "create_payout":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/payouts", args), null, 2) }] };
+      case "get_payout":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/payouts/${args?.id}`), null, 2) }] };
+      case "create_transfer":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("POST", "/transfers", args), null, 2) }] };
+      case "get_transfer":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/transfers/${args?.id}`), null, 2) }] };
+      case "get_balance":
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", "/balances"), null, 2) }] };
+      case "list_transactions": {
+        const params = new URLSearchParams();
+        if (args?.type) params.set("type", String(args.type));
+        if (args?.status) params.set("status", String(args.status));
+        if (args?.from) params.set("from", String(args.from));
+        if (args?.to) params.set("to", String(args.to));
+        if (args?.pageSize) params.set("pageSize", String(args.pageSize));
+        if (args?.pageBefore) params.set("pageBefore", String(args.pageBefore));
+        if (args?.pageAfter) params.set("pageAfter", String(args.pageAfter));
+        return { content: [{ type: "text", text: JSON.stringify(await circleRequest("GET", `/transactions?${params}`), null, 2) }] };
+      }
+      default:
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+  } catch (err) {
+    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+  }
+});
+
+async function main() {
+  if (!API_KEY) {
+    console.error("CIRCLE_API_KEY environment variable is required");
+    process.exit(1);
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}