pacioli: Instructions file for Claude Code

Pacioli — Holded MCP Server + Skill PGC

Nombrado en honor a Luca Pacioli (1447–1517), padre de la contabilidad por partida doble.

Qué es esto

MCP server read-only (stdio) que conecta Claude Code con la API de Holded. Acompañado de una skill del Plan General Contable español (PGC 2007).

Stack

• Node.js + TypeScript (ESM, target ES2022, module Node16)
• @modelcontextprotocol/sdk v1.26.0 — MCP server
• zod@4 — validación de schemas de tools
• Build output: dist/

Arquitectura

MCP Server

• Entry point: src/index.ts → crea transporte stdio y conecta el server
• Server: src/server.ts → exporta createServer() que instancia McpServer + HoldedClient
• Cada fichero de tools exporta registerTools(server, client):
  • src/tools/accounting.ts → 2 tools (list_accounts, list_daily_ledger)
  • src/tools/invoicing.ts → 5 tools (list_documents, get_document, list_contacts, get_contact, get_taxes)
  • src/tools/treasury.ts → 2 tools (list_treasuries, list_payments)
  • src/tools/reports.ts → 3 tools (get_balance_sheet, get_profit_loss, get_vat_summary)

Holded Client (src/holded/)

• client.ts — Clase HoldedClient. Auth via header key: <apiKey>. Timeout 30s. Retry 3x backoff.
• types.ts — Interfaces TS para respuestas de Holded.
• endpoints.ts — Constantes de URLs. Base: https://api.holded.com/api

API de Holded — Particularidades

• Auth: header key: <apiKey> (NO Authorization, NO Bearer)
• Fechas: se envían como timestamps Unix en params starttmp/endtmp
• Paginación: limit/offset query params
• Cuentas contables: /api/accounting/v1/chartofaccounts (NO /accounts)
• Documentos extra params: paid (0/1/2), sort, contactid

Patrón de registro de tools

Cada fichero de tools exporta una función:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { HoldedClient } from "../holded/client.js";

export function registerTools(server: McpServer, client: HoldedClient): void {
  server.registerTool("holded_tool_name", {
    description: "Descripción en español",
    inputSchema: { param: z.string().optional().describe("Descripción") },
  }, async ({ param }) => {
    try {
      const data = await client.someMethod(param);
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
    }
  });
}