@codespar/mcp-colppy 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# MCP Colppy
+
+MCP server for **Colppy** — Argentine cloud accounting platform with integrated AFIP electronic invoicing.
+
+## Quick Start
+
+```bash
+# Set your credentials
+export COLPPY_API_KEY="your-api-key"
+export COLPPY_COMPANY_ID="your-company-id"
+
+# Run via stdio
+npx tsx packages/argentina/colppy/src/index.ts
+
+# Run via HTTP
+npx tsx packages/argentina/colppy/src/index.ts --http
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `COLPPY_API_KEY` | Yes | API key from Colppy |
+| `COLPPY_COMPANY_ID` | Yes | Company identifier |
+| `MCP_HTTP` | No | Set to `"true"` to enable HTTP transport |
+| `MCP_PORT` | No | HTTP port (default: 3000) |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_customers` | List customers |
+| `create_customer` | Create a customer |
+| `list_products` | List products and services |
+| `create_invoice` | Create an invoice (integrates with AFIP) |
+| `list_invoices` | List invoices |
+| `get_balance` | Get account balance summary |
+| `list_accounts` | List chart of accounts (plan de cuentas) |
+| `create_payment` | Record a payment against an invoice |
+
+## Auth
+
+Uses **API key + session** authentication. The API key is sent with each request along with the company ID. Colppy uses a JSON-RPC style API where service and operation are specified in the request body.
+
+## API Reference
+
+- [Colppy API Documentation](https://www.colppy.com/api)
+
+---
+
+**Enterprise?** Contact us at [codespar.com](https://codespar.com) for dedicated support, custom integrations, and SLAs.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Colppy — Argentine cloud accounting + AFIP invoicing.
+ *
+ * Tools:
+ * - list_customers: List customers
+ * - create_customer: Create a customer
+ * - list_products: List products/services
+ * - create_invoice: Create an invoice (integrates with AFIP)
+ * - list_invoices: List invoices
+ * - get_balance: Get account balance
+ * - list_accounts: List chart of accounts
+ * - create_payment: Record a payment
+ *
+ * Environment:
+ *   COLPPY_API_KEY    — API key
+ *   COLPPY_COMPANY_ID — Company identifier
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Colppy — Argentine cloud accounting + AFIP invoicing.
+ *
+ * Tools:
+ * - list_customers: List customers
+ * - create_customer: Create a customer
+ * - list_products: List products/services
+ * - create_invoice: Create an invoice (integrates with AFIP)
+ * - list_invoices: List invoices
+ * - get_balance: Get account balance
+ * - list_accounts: List chart of accounts
+ * - create_payment: Record a payment
+ *
+ * Environment:
+ *   COLPPY_API_KEY    — API key
+ *   COLPPY_COMPANY_ID — Company identifier
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const API_KEY = process.env.COLPPY_API_KEY || "";
+const COMPANY_ID = process.env.COLPPY_COMPANY_ID || "";
+const BASE_URL = "https://login.colppy.com/lib/frontera2";
+async function colppyRequest(service, operation, params) {
+    const payload = {
+        service,
+        operation,
+        parameters: {
+            ...params,
+            sespiKey: API_KEY,
+            idEmpresa: COMPANY_ID,
+        },
+    };
+    const res = await fetch(BASE_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Colppy API ${res.status}: ${err}`);
+    }
+    return res.json();
+}
+const server = new Server({ name: "mcp-colppy", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "list_customers",
+            description: "List customers",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filter: { type: "string", description: "Search filter (name or tax ID)" },
+                    offset: { type: "number", description: "Pagination offset" },
+                    limit: { type: "number", description: "Results limit" },
+                },
+            },
+        },
+        {
+            name: "create_customer",
+            description: "Create a customer",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Customer name or business name" },
+                    tax_id: { type: "string", description: "CUIT/CUIL/DNI number" },
+                    tax_id_type: { type: "string", description: "Document type (CUIT, CUIL, DNI)" },
+                    tax_category: { type: "string", description: "Tax category (RI, Monotributo, Exento, ConsumidorFinal)" },
+                    email: { type: "string", description: "Email address" },
+                    phone: { type: "string", description: "Phone number" },
+                    address: { type: "string", description: "Street address" },
+                },
+                required: ["name", "tax_id"],
+            },
+        },
+        {
+            name: "list_products",
+            description: "List products and services",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filter: { type: "string", description: "Search filter" },
+                    offset: { type: "number", description: "Pagination offset" },
+                    limit: { type: "number", description: "Results limit" },
+                },
+            },
+        },
+        {
+            name: "create_invoice",
+            description: "Create an invoice (integrates with AFIP for electronic invoicing)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    customer_id: { type: "string", description: "Customer ID" },
+                    invoice_type: { type: "string", description: "Invoice type (A, B, C)" },
+                    point_of_sale: { type: "number", description: "Punto de venta" },
+                    items: {
+                        type: "array",
+                        description: "Invoice items",
+                        items: {
+                            type: "object",
+                            properties: {
+                                product_id: { type: "string", description: "Product ID" },
+                                description: { type: "string", description: "Description" },
+                                quantity: { type: "number", description: "Quantity" },
+                                unit_price: { type: "number", description: "Unit price" },
+                                iva_rate: { type: "number", description: "IVA rate (21, 10.5, 27, 0)" },
+                            },
+                            required: ["description", "quantity", "unit_price"],
+                        },
+                    },
+                    currency: { type: "string", description: "Currency (ARS, USD)" },
+                },
+                required: ["customer_id", "invoice_type", "items"],
+            },
+        },
+        {
+            name: "list_invoices",
+            description: "List invoices",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    date_from: { type: "string", description: "Start date (YYYY-MM-DD)" },
+                    date_to: { type: "string", description: "End date (YYYY-MM-DD)" },
+                    customer_id: { type: "string", description: "Filter by customer" },
+                    status: { type: "string", description: "Filter by status" },
+                    offset: { type: "number", description: "Pagination offset" },
+                    limit: { type: "number", description: "Results limit" },
+                },
+            },
+        },
+        {
+            name: "get_balance",
+            description: "Get account balance summary",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    date: { type: "string", description: "Balance date (YYYY-MM-DD)" },
+                },
+            },
+        },
+        {
+            name: "list_accounts",
+            description: "List chart of accounts (plan de cuentas)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filter: { type: "string", description: "Search filter" },
+                },
+            },
+        },
+        {
+            name: "create_payment",
+            description: "Record a payment against an invoice",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    invoice_id: { type: "string", description: "Invoice ID" },
+                    amount: { type: "number", description: "Payment amount" },
+                    payment_method: { type: "string", description: "Payment method (cash, bank_transfer, check, card)" },
+                    date: { type: "string", description: "Payment date (YYYY-MM-DD)" },
+                    reference: { type: "string", description: "Payment reference" },
+                },
+                required: ["invoice_id", "amount", "payment_method"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "list_customers": {
+                const params = {};
+                if (args?.filter)
+                    params.filter = args.filter;
+                if (args?.offset)
+                    params.offset = args.offset;
+                if (args?.limit)
+                    params.limit = args.limit;
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("cliente", "listar", params), null, 2) }] };
+            }
+            case "create_customer":
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("cliente", "crear", {
+                                razonSocial: args?.name,
+                                cuit: args?.tax_id,
+                                tipoDocumento: args?.tax_id_type,
+                                categoriaFiscal: args?.tax_category,
+                                email: args?.email,
+                                telefono: args?.phone,
+                                direccion: args?.address,
+                            }), null, 2) }] };
+            case "list_products": {
+                const params = {};
+                if (args?.filter)
+                    params.filter = args.filter;
+                if (args?.offset)
+                    params.offset = args.offset;
+                if (args?.limit)
+                    params.limit = args.limit;
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("producto", "listar", params), null, 2) }] };
+            }
+            case "create_invoice":
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("factura", "crear", {
+                                idCliente: args?.customer_id,
+                                tipoComprobante: args?.invoice_type,
+                                puntoVenta: args?.point_of_sale,
+                                items: args?.items,
+                                moneda: args?.currency,
+                            }), null, 2) }] };
+            case "list_invoices": {
+                const params = {};
+                if (args?.date_from)
+                    params.fechaDesde = args.date_from;
+                if (args?.date_to)
+                    params.fechaHasta = args.date_to;
+                if (args?.customer_id)
+                    params.idCliente = args.customer_id;
+                if (args?.status)
+                    params.estado = args.status;
+                if (args?.offset)
+                    params.offset = args.offset;
+                if (args?.limit)
+                    params.limit = args.limit;
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("factura", "listar", params), null, 2) }] };
+            }
+            case "get_balance": {
+                const params = {};
+                if (args?.date)
+                    params.fecha = args.date;
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("balance", "obtener", params), null, 2) }] };
+            }
+            case "list_accounts": {
+                const params = {};
+                if (args?.filter)
+                    params.filter = args.filter;
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("cuenta", "listar", params), null, 2) }] };
+            }
+            case "create_payment":
+                return { content: [{ type: "text", text: JSON.stringify(await colppyRequest("pago", "crear", {
+                                idFactura: args?.invoice_id,
+                                monto: args?.amount,
+                                metodoPago: args?.payment_method,
+                                fecha: args?.date,
+                                referencia: args?.reference,
+                            }), 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 (process.argv.includes("--http") || process.env.MCP_HTTP === "true") {
+        const { default: express } = await import("express");
+        const { randomUUID } = await import("node:crypto");
+        const app = express();
+        app.use(express.json());
+        const transports = new Map();
+        app.get("/health", (_req, res) => res.json({ status: "ok", sessions: transports.size }));
+        app.post("/mcp", async (req, res) => {
+            const sid = req.headers["mcp-session-id"];
+            if (sid && transports.has(sid)) {
+                await transports.get(sid).handleRequest(req, res, req.body);
+                return;
+            }
+            if (!sid && isInitializeRequest(req.body)) {
+                const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
+                t.onclose = () => { if (t.sessionId)
+                    transports.delete(t.sessionId); };
+                const s = new Server({ name: "mcp-colppy", version: "0.1.0" }, { capabilities: { tools: {} } });
+                server._requestHandlers.forEach((v, k) => s._requestHandlers.set(k, v));
+                server._notificationHandlers?.forEach((v, k) => s._notificationHandlers.set(k, v));
+                await s.connect(t);
+                await t.handleRequest(req, res, req.body);
+                return;
+            }
+            res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request" }, id: null });
+        });
+        app.get("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"]; if (sid && transports.has(sid))
+            await transports.get(sid).handleRequest(req, res);
+        else
+            res.status(400).send("Invalid session"); });
+        app.delete("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"]; if (sid && transports.has(sid))
+            await transports.get(sid).handleRequest(req, res);
+        else
+            res.status(400).send("Invalid session"); });
+        const port = Number(process.env.MCP_PORT) || 3000;
+        app.listen(port, () => { console.error(`MCP HTTP server on http://localhost:${port}/mcp`); });
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@codespar/mcp-colppy",
+  "version": "0.1.0",
+  "description": "MCP server for Colppy — Argentine cloud accounting + AFIP invoicing",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-colppy": "dist/index.js"
+  },
+  "files": ["dist"],
+  "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": ["colppy", "accounting", "argentina", "afip", "invoicing", "mcp"],
+  "mcpName": "io.github.codespar/mcp-colppy"
+}