@codespar/mcp-siigo 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# MCP Siigo
+
+MCP server for **Siigo** — Colombian accounting platform with integrated DIAN electronic invoicing.
+
+## Quick Start
+
+```bash
+# Set your credentials
+export SIIGO_API_KEY="your-api-key"
+export SIIGO_ACCESS_TOKEN="your-access-token"
+
+# Run via stdio
+npx tsx packages/colombia/siigo/src/index.ts
+
+# Run via HTTP
+npx tsx packages/colombia/siigo/src/index.ts --http
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SIIGO_API_KEY` | Yes | API key from Siigo |
+| `SIIGO_ACCESS_TOKEN` | Yes | Bearer access token |
+| `MCP_HTTP` | No | Set to `"true"` to enable HTTP transport |
+| `MCP_PORT` | No | HTTP port (default: 3000) |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_invoice` | Create an invoice (DIAN electronic invoice) |
+| `get_invoice` | Get invoice details by ID |
+| `list_invoices` | List invoices |
+| `create_credit_note` | Create a credit note |
+| `list_customers` | List customers |
+| `create_customer` | Create a customer |
+| `list_products` | List products |
+| `create_product` | Create a product |
+| `list_taxes` | List available tax types |
+| `list_payment_methods` | List payment methods |
+
+## Auth
+
+Uses **Bearer token** authentication. Obtain your access token from the Siigo developer portal.
+
+## API Reference
+
+- [Siigo API Docs](https://siigodeveloper.siigo.com/)
+
+---
+
+**Enterprise?** Contact us at [codespar.com](https://codespar.com) for dedicated support, custom integrations, and SLAs.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Siigo — Colombian accounting + DIAN e-invoicing.
+ *
+ * Tools:
+ * - create_invoice: Create an invoice (DIAN electronic invoice)
+ * - get_invoice: Get invoice by ID
+ * - list_invoices: List invoices
+ * - create_credit_note: Create a credit note
+ * - list_customers: List customers
+ * - create_customer: Create a customer
+ * - list_products: List products
+ * - create_product: Create a product
+ * - list_taxes: List available tax types
+ * - list_payment_methods: List payment methods
+ *
+ * Environment:
+ *   SIIGO_API_KEY      — API key
+ *   SIIGO_ACCESS_TOKEN — Access token (Bearer)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Siigo — Colombian accounting + DIAN e-invoicing.
+ *
+ * Tools:
+ * - create_invoice: Create an invoice (DIAN electronic invoice)
+ * - get_invoice: Get invoice by ID
+ * - list_invoices: List invoices
+ * - create_credit_note: Create a credit note
+ * - list_customers: List customers
+ * - create_customer: Create a customer
+ * - list_products: List products
+ * - create_product: Create a product
+ * - list_taxes: List available tax types
+ * - list_payment_methods: List payment methods
+ *
+ * Environment:
+ *   SIIGO_API_KEY      — API key
+ *   SIIGO_ACCESS_TOKEN — Access token (Bearer)
+ */
+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 ACCESS_TOKEN = process.env.SIIGO_ACCESS_TOKEN || "";
+const BASE_URL = "https://api.siigo.com/v1";
+async function siigoRequest(method, path, body) {
+    const headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "Authorization": `Bearer ${ACCESS_TOKEN}`,
+    };
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Siigo API ${res.status}: ${err}`);
+    }
+    return res.json();
+}
+const server = new Server({ name: "mcp-siigo", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "create_invoice",
+            description: "Create an invoice (DIAN electronic invoice)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    document: {
+                        type: "object",
+                        description: "Document type",
+                        properties: { id: { type: "number", description: "Document type ID" } },
+                        required: ["id"],
+                    },
+                    date: { type: "string", description: "Invoice date (YYYY-MM-DD)" },
+                    customer: {
+                        type: "object",
+                        description: "Customer reference",
+                        properties: {
+                            identification: { type: "string", description: "Customer NIT or CC" },
+                            branch_office: { type: "number", description: "Branch office (default 0)" },
+                        },
+                        required: ["identification"],
+                    },
+                    items: {
+                        type: "array",
+                        description: "Invoice items",
+                        items: {
+                            type: "object",
+                            properties: {
+                                code: { type: "string", description: "Product code" },
+                                description: { type: "string", description: "Description" },
+                                quantity: { type: "number", description: "Quantity" },
+                                price: { type: "number", description: "Unit price" },
+                                discount: { type: "number", description: "Discount percentage" },
+                                taxes: {
+                                    type: "array",
+                                    description: "Taxes",
+                                    items: {
+                                        type: "object",
+                                        properties: {
+                                            id: { type: "number", description: "Tax ID" },
+                                            name: { type: "string", description: "Tax name" },
+                                            percentage: { type: "number", description: "Tax percentage" },
+                                        },
+                                    },
+                                },
+                            },
+                            required: ["code", "quantity", "price"],
+                        },
+                    },
+                    payments: {
+                        type: "array",
+                        description: "Payment methods",
+                        items: {
+                            type: "object",
+                            properties: {
+                                id: { type: "number", description: "Payment method ID" },
+                                value: { type: "number", description: "Payment amount" },
+                            },
+                            required: ["id", "value"],
+                        },
+                    },
+                },
+                required: ["document", "date", "customer", "items", "payments"],
+            },
+        },
+        {
+            name: "get_invoice",
+            description: "Get invoice details by ID",
+            inputSchema: {
+                type: "object",
+                properties: { invoiceId: { type: "string", description: "Invoice ID" } },
+                required: ["invoiceId"],
+            },
+        },
+        {
+            name: "list_invoices",
+            description: "List invoices",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    page: { type: "number", description: "Page number" },
+                    page_size: { type: "number", description: "Page size (max 100)" },
+                    date_start: { type: "string", description: "Start date (YYYY-MM-DD)" },
+                    date_end: { type: "string", description: "End date (YYYY-MM-DD)" },
+                },
+            },
+        },
+        {
+            name: "create_credit_note",
+            description: "Create a credit note against an invoice",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    document: {
+                        type: "object",
+                        description: "Document type",
+                        properties: { id: { type: "number", description: "Document type ID for credit notes" } },
+                        required: ["id"],
+                    },
+                    date: { type: "string", description: "Credit note date (YYYY-MM-DD)" },
+                    customer: {
+                        type: "object",
+                        description: "Customer reference",
+                        properties: { identification: { type: "string", description: "Customer NIT or CC" } },
+                        required: ["identification"],
+                    },
+                    items: {
+                        type: "array",
+                        description: "Items to credit",
+                        items: {
+                            type: "object",
+                            properties: {
+                                code: { type: "string", description: "Product code" },
+                                quantity: { type: "number", description: "Quantity" },
+                                price: { type: "number", description: "Unit price" },
+                            },
+                            required: ["code", "quantity", "price"],
+                        },
+                    },
+                    reason: { type: "string", description: "Reason for the credit note" },
+                },
+                required: ["document", "date", "customer", "items"],
+            },
+        },
+        {
+            name: "list_customers",
+            description: "List customers",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    page: { type: "number", description: "Page number" },
+                    page_size: { type: "number", description: "Page size" },
+                    identification: { type: "string", description: "Filter by NIT/CC" },
+                },
+            },
+        },
+        {
+            name: "create_customer",
+            description: "Create a customer",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: { type: "string", description: "Customer type (Customer, Supplier, Other)" },
+                    person_type: { type: "string", description: "Person type (Person, Company)" },
+                    id_type: { type: "string", description: "ID type (13=CC, 31=NIT, 22=CE)" },
+                    identification: { type: "string", description: "NIT or CC number" },
+                    name: { type: "array", description: "Name array [first_name, last_name]", items: { type: "string" } },
+                    commercial_name: { type: "string", description: "Commercial/business name" },
+                    contacts: {
+                        type: "array",
+                        description: "Contact info",
+                        items: {
+                            type: "object",
+                            properties: {
+                                first_name: { type: "string", description: "First name" },
+                                last_name: { type: "string", description: "Last name" },
+                                email: { type: "string", description: "Email" },
+                                phone: { type: "string", description: "Phone" },
+                            },
+                        },
+                    },
+                    address: {
+                        type: "object",
+                        description: "Address",
+                        properties: {
+                            address: { type: "string", description: "Street address" },
+                            city: { type: "object", properties: { country_code: { type: "string" }, state_code: { type: "string" }, city_code: { type: "string" } } },
+                        },
+                    },
+                },
+                required: ["type", "person_type", "id_type", "identification", "name"],
+            },
+        },
+        {
+            name: "list_products",
+            description: "List products",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    page: { type: "number", description: "Page number" },
+                    page_size: { type: "number", description: "Page size" },
+                    code: { type: "string", description: "Filter by product code" },
+                },
+            },
+        },
+        {
+            name: "create_product",
+            description: "Create a product",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: { type: "string", description: "Product code" },
+                    name: { type: "string", description: "Product name" },
+                    account_group: { type: "number", description: "Account group ID" },
+                    type: { type: "string", description: "Product type (Product, Service)" },
+                    stock_control: { type: "boolean", description: "Enable stock control" },
+                    unit: { type: "string", description: "Unit of measure" },
+                    taxes: {
+                        type: "array",
+                        description: "Tax configuration",
+                        items: {
+                            type: "object",
+                            properties: {
+                                id: { type: "number", description: "Tax ID" },
+                            },
+                        },
+                    },
+                    prices: {
+                        type: "array",
+                        description: "Price list",
+                        items: {
+                            type: "object",
+                            properties: {
+                                currency_code: { type: "string", description: "Currency (COP)" },
+                                price_list: { type: "array", items: { type: "object", properties: { position: { type: "number" }, value: { type: "number" } } } },
+                            },
+                        },
+                    },
+                },
+                required: ["code", "name"],
+            },
+        },
+        {
+            name: "list_taxes",
+            description: "List available tax types",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "list_payment_methods",
+            description: "List available payment methods",
+            inputSchema: { type: "object", properties: {} },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "create_invoice":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("POST", "/invoices", {
+                                document: args?.document,
+                                date: args?.date,
+                                customer: args?.customer,
+                                items: args?.items,
+                                payments: args?.payments,
+                            }), null, 2) }] };
+            case "get_invoice":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("GET", `/invoices/${args?.invoiceId}`), null, 2) }] };
+            case "list_invoices": {
+                const params = new URLSearchParams();
+                if (args?.page)
+                    params.set("page", String(args.page));
+                if (args?.page_size)
+                    params.set("page_size", String(args.page_size));
+                if (args?.date_start)
+                    params.set("date_start", args.date_start);
+                if (args?.date_end)
+                    params.set("date_end", args.date_end);
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("GET", `/invoices?${params}`), null, 2) }] };
+            }
+            case "create_credit_note":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("POST", "/credit-notes", {
+                                document: args?.document,
+                                date: args?.date,
+                                customer: args?.customer,
+                                items: args?.items,
+                                reason: args?.reason,
+                            }), null, 2) }] };
+            case "list_customers": {
+                const params = new URLSearchParams();
+                if (args?.page)
+                    params.set("page", String(args.page));
+                if (args?.page_size)
+                    params.set("page_size", String(args.page_size));
+                if (args?.identification)
+                    params.set("identification", args.identification);
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("GET", `/customers?${params}`), null, 2) }] };
+            }
+            case "create_customer":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("POST", "/customers", {
+                                type: args?.type,
+                                person_type: args?.person_type,
+                                id_type: args?.id_type,
+                                identification: args?.identification,
+                                name: args?.name,
+                                commercial_name: args?.commercial_name,
+                                contacts: args?.contacts,
+                                address: args?.address,
+                            }), null, 2) }] };
+            case "list_products": {
+                const params = new URLSearchParams();
+                if (args?.page)
+                    params.set("page", String(args.page));
+                if (args?.page_size)
+                    params.set("page_size", String(args.page_size));
+                if (args?.code)
+                    params.set("code", args.code);
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("GET", `/products?${params}`), null, 2) }] };
+            }
+            case "create_product":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("POST", "/products", {
+                                code: args?.code,
+                                name: args?.name,
+                                account_group: args?.account_group,
+                                type: args?.type,
+                                stock_control: args?.stock_control,
+                                unit: args?.unit,
+                                taxes: args?.taxes,
+                                prices: args?.prices,
+                            }), null, 2) }] };
+            case "list_taxes":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("GET", "/taxes"), null, 2) }] };
+            case "list_payment_methods":
+                return { content: [{ type: "text", text: JSON.stringify(await siigoRequest("GET", "/payment-types"), 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-siigo", 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-siigo",
+  "version": "0.1.0",
+  "description": "MCP server for Siigo — Colombian accounting + DIAN e-invoicing",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-siigo": "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": ["siigo", "accounting", "colombia", "dian", "e-invoicing", "mcp"],
+  "mcpName": "io.github.codespar/mcp-siigo"
+}