@facturador-mcp-sii.cl/mcp 0.2.0

package/README.md

@@ -0,0 +1,113 @@
+# Facturador Pulsando — Servidor MCP
+
+Servidor [Model Context Protocol](https://modelcontextprotocol.io) para la API de
+**facturación electrónica del SII de Chile** de Facturador Pulsando. Conecta un
+agente de IA (Claude Desktop, Claude Code, Cursor, etc.) directamente a tu
+facturación: emitir y consultar DTE, consultar el padrón del SII y ver folios,
+en lenguaje natural.
+
+> *"Emite una boleta de $5.000 por consultoría"* · *"¿Cuántas facturas rechazadas
+> tengo este mes y por qué?"* · *"Valida el RUT 76.354.771-K y crea una factura."*
+
+## Herramientas expuestas
+
+| Herramienta | Qué hace | Scope de la key |
+|---|---|---|
+| `emitir_dte` | Emite factura/boleta/NC/ND/guía (con Idempotency-Key automática) | `dte:create` |
+| `consultar_dte` | Detalle y estado SII de un DTE | `dte:read` |
+| `listar_dtes` | Lista/filtra DTE (reportes) | `dte:read` |
+| `consultar_contribuyente` | Padrón SII por RUT (razón social + giros) | `dte:read` |
+| `estado_folios` | Folios (CAF) disponibles por tipo | `caf:read` |
+| `documentos_recibidos` | Documentos que te emitieron (intercambio) | `recepcion:read` |
+
+## Instalación
+
+```bash
+npm install
+npm run build
+```
+
+## Configuración (Claude Desktop / Claude Code / Cursor)
+
+Agrega a tu config de MCP (en Claude Desktop: `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "facturador-pulsando": {
+      "command": "node",
+      "args": ["/ruta/absoluta/a/facturador-mcp/dist/index.js"],
+      "env": {
+        "PULSANDO_API_KEY": "sk_test_...",
+        "PULSANDO_BASE_URL": "https://api.facturador.pulsandotech.cl/api/public/v1"
+      }
+    }
+  }
+}
+```
+
+Una vez publicado en npm, también:
+
+```json
+{
+  "mcpServers": {
+    "facturador-pulsando": {
+      "command": "npx",
+      "args": ["-y", "@facturador-mcp-sii.cl/mcp"],
+      "env": { "PULSANDO_API_KEY": "sk_test_..." }
+    }
+  }
+}
+```
+
+## Variables de entorno
+
+| Variable | Obligatoria | Default |
+|---|---|---|
+| `PULSANDO_API_KEY` | Sí | — (`sk_test_...` para pruebas / `sk_live_...` producción) |
+| `PULSANDO_BASE_URL` | No | `https://api.facturador.pulsandotech.cl/api/public/v1` |
+
+## Seguridad
+
+- El agente actúa con **los permisos (scopes) de la key** que le entregues. Para
+  pruebas usa una `sk_test_` (ambiente de certificación, documentos no válidos).
+- Da a la key **solo los scopes** que el agente necesite.
+- La key va en el `env` del servidor MCP (tu máquina/servidor), nunca en el chat.
+
+## Servidor remoto (Streamable HTTP)
+
+Además del stdio local, este paquete incluye un servidor **HTTP remoto**
+(`src/http.ts`, Streamable HTTP, **stateless**) ya desplegado en Railway:
+
+- **Endpoint:** `https://facturador-mcp-production.up.railway.app/mcp`
+- **Healthcheck:** `GET /health`
+- **Auth:** cada request trae la API Key del usuario en
+  `Authorization: Bearer sk_live_xxx` (o `X-Api-Key`). El agente actúa con esa
+  llave → paywall y scopes del tenant se respetan. Sin llave → `401`.
+
+Ejecutarlo localmente:
+
+```bash
+npm run build
+PORT=8080 npm run start:http
+```
+
+Añadirlo como **custom connector remoto** (Claude Code, Cursor, MCP Inspector):
+apunta la URL `https://facturador-mcp-production.up.railway.app/mcp` y pasa tu
+API Key como Bearer token.
+
+Desplegar en Railway (ya hecho; para re-deploy):
+
+```bash
+railway up --service facturador-mcp   # usa railway.json (start: node dist/http.js)
+```
+
+### Directorio de conectores de claude.ai (OAuth 2.1)
+
+Para aparecer en el **directorio** de conectores de claude.ai se exige **OAuth 2.1
+(PKCE)** en vez de Bearer manual: el usuario conecta su cuenta Pulsando y autoriza.
+Eso requiere que el backend (Laravel) actúe como Authorization Server. Ver
+`docs/api/AI-INTEGRATION.md` → "OAuth para el directorio" para el plan.
+
+## Licencia
+MIT · soporte@pulsandotech.cl

package/dist/http.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Servidor MCP de Facturador Pulsando — transporte HTTP remoto (Streamable HTTP).
+ *
+ * Pensado para desplegarse (ej. Railway) y conectarse como "custom connector"
+ * remoto. Modo STATELESS: cada request crea su propio server+transport, así
+ * escala horizontalmente sin estado de sesión.
+ *
+ * Autenticación: cada request trae la API Key del usuario en el header
+ *   Authorization: Bearer sk_live_xxx   (o X-Api-Key: sk_live_xxx)
+ * El agente actúa con esa llave → el paywall y los scopes del tenant se respetan.
+ * (Para el DIRECTORIO de conectores de claude.ai se requiere además OAuth 2.1;
+ *  ver README → "Despliegue remoto / OAuth".)
+ *
+ * Config:
+ *   PORT               puerto HTTP (Railway lo inyecta)
+ *   PULSANDO_BASE_URL  base de la API (opcional)
+ */
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { buildServer, DEFAULT_BASE_URL } from "./server.js";
+import { mountOAuth, resolveToken } from "./oauth.js";
+const PORT = Number(process.env.PORT ?? 8080);
+const BASE_URL = (process.env.PULSANDO_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+/**
+ * Resuelve la API Key efectiva de un request:
+ *  - Bearer que es un access_token OAuth → la llave mapeada (flujo claude.ai).
+ *  - Bearer que es una API Key cruda sk_... → se usa directo (conector manual).
+ *  - Header X-Api-Key: sk_... → directo.
+ */
+function extractApiKey(req) {
+    const auth = req.header("authorization") ?? "";
+    const m = auth.match(/^Bearer\s+(.+)$/i);
+    if (m) {
+        const bearer = m[1].trim();
+        const mapped = resolveToken(bearer);
+        if (mapped)
+            return mapped;
+        if (bearer.startsWith("sk_"))
+            return bearer;
+    }
+    const x = req.header("x-api-key");
+    return x && x.startsWith("sk_") ? x.trim() : null;
+}
+const app = express();
+app.use(express.json({ limit: "1mb" }));
+// OAuth (/authorize, /token) y el form de consentimiento usan x-www-form-urlencoded.
+app.use(express.urlencoded({ extended: false }));
+// Endpoints OAuth 2.1 (metadata, DCR, authorize, token) para claude.ai.
+mountOAuth(app, BASE_URL);
+// Healthcheck (Railway).
+app.get("/health", (_req, res) => res.json({ ok: true, service: "facturador-mcp" }));
+app.post("/mcp", async (req, res) => {
+    const apiKey = extractApiKey(req);
+    if (!apiKey) {
+        // Advertir el Authorization Server para que el cliente (claude.ai) inicie OAuth.
+        const proto = req.headers["x-forwarded-proto"] || req.protocol;
+        const base = process.env.PUBLIC_URL?.replace(/\/$/, "") || `${proto}://${req.get("host")}`;
+        res.setHeader("WWW-Authenticate", `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource"`);
+        res.status(401).json({
+            jsonrpc: "2.0",
+            error: { code: -32001, message: "No autorizado. Usa OAuth o Authorization: Bearer sk_..." },
+            id: null,
+        });
+        return;
+    }
+    try {
+        const server = buildServer(apiKey, BASE_URL);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            transport.close();
+            server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    }
+    catch (e) {
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: `Error interno: ${e.message}` },
+                id: null,
+            });
+        }
+    }
+});
+// En modo stateless no hay sesiones que reabrir/cerrar por GET/DELETE.
+const methodNotAllowed = (_req, res) => res.status(405).json({
+    jsonrpc: "2.0",
+    error: { code: -32000, message: "Method not allowed (servidor stateless)." },
+    id: null,
+});
+app.get("/mcp", methodNotAllowed);
+app.delete("/mcp", methodNotAllowed);
+app.listen(PORT, () => {
+    console.error(`[facturador-mcp] HTTP MCP escuchando en :${PORT} (POST /mcp)`);
+});

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Servidor MCP de Facturador Pulsando — transporte STDIO (uso local:
+ * Claude Desktop / Claude Code / Cursor). Para el transporte remoto ver http.ts.
+ *
+ * Config por variables de entorno:
+ *   PULSANDO_API_KEY   (obligatoria)  sk_test_... o sk_live_...
+ *   PULSANDO_BASE_URL  (opcional)     default api.facturador.pulsandotech.cl
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer, DEFAULT_BASE_URL } from "./server.js";
+const API_KEY = process.env.PULSANDO_API_KEY;
+const BASE_URL = (process.env.PULSANDO_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+if (!API_KEY) {
+    console.error("[facturador-mcp] Falta PULSANDO_API_KEY (sk_test_... o sk_live_...).");
+    process.exit(1);
+}
+const server = buildServer(API_KEY, BASE_URL);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[facturador-mcp] servidor MCP listo (stdio).");

package/dist/oauth.js

@@ -0,0 +1,180 @@
+import { createHash, randomBytes } from "node:crypto";
+const clients = new Map();
+const codes = new Map();
+const tokens = new Map();
+const CODE_TTL_MS = 5 * 60 * 1000;
+const TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const rand = (n = 32) => b64url(randomBytes(n));
+/** Verifica el PKCE S256: base64url(sha256(verifier)) === challenge. */
+function verifyPkce(verifier, challenge) {
+    const hash = b64url(createHash("sha256").update(verifier).digest());
+    return hash === challenge;
+}
+/** Valida una API Key contra la API real (no-401 = llave válida). */
+async function validateApiKey(apiKey, baseUrl) {
+    try {
+        const res = await fetch(`${baseUrl}/dte?per_page=1`, {
+            headers: { "X-Api-Key": apiKey, Accept: "application/json" },
+        });
+        // 401 = llave inválida/inactiva. 200/403 (sin scope) = llave válida.
+        return res.status !== 401;
+    }
+    catch {
+        return false;
+    }
+}
+/** Devuelve la API Key mapeada a un access token válido, o null. */
+export function resolveToken(accessToken) {
+    const t = tokens.get(accessToken);
+    if (!t)
+        return null;
+    if (Date.now() > t.expiresAt) {
+        tokens.delete(accessToken);
+        return null;
+    }
+    return t.apiKey;
+}
+/** URL pública del servidor (para issuer/endpoints del metadata). */
+function publicBaseUrl(req) {
+    const envUrl = process.env.PUBLIC_URL;
+    if (envUrl)
+        return envUrl.replace(/\/$/, "");
+    const proto = req.headers["x-forwarded-proto"] || req.protocol;
+    return `${proto}://${req.get("host")}`;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+/**
+ * Monta los endpoints OAuth en la app Express. `apiBaseUrl` es la API de Pulsando.
+ */
+export function mountOAuth(app, apiBaseUrl) {
+    // ── Metadata: Protected Resource (RFC 9728) ──────────────────────────────
+    app.get("/.well-known/oauth-protected-resource", (req, res) => {
+        const base = publicBaseUrl(req);
+        res.json({
+            resource: `${base}/mcp`,
+            authorization_servers: [base],
+            bearer_methods_supported: ["header"],
+        });
+    });
+    // ── Metadata: Authorization Server (RFC 8414) ────────────────────────────
+    app.get("/.well-known/oauth-authorization-server", (req, res) => {
+        const base = publicBaseUrl(req);
+        res.json({
+            issuer: base,
+            authorization_endpoint: `${base}/authorize`,
+            token_endpoint: `${base}/token`,
+            registration_endpoint: `${base}/register`,
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code"],
+            code_challenge_methods_supported: ["S256"],
+            token_endpoint_auth_methods_supported: ["none"],
+            scopes_supported: ["mcp"],
+        });
+    });
+    // ── Dynamic Client Registration (RFC 7591) ───────────────────────────────
+    app.post("/register", (req, res) => {
+        const redirectUris = Array.isArray(req.body?.redirect_uris)
+            ? req.body.redirect_uris
+            : [];
+        const clientId = `mcp-${rand(12)}`;
+        clients.set(clientId, { client_id: clientId, redirect_uris: redirectUris });
+        res.status(201).json({
+            client_id: clientId,
+            redirect_uris: redirectUris,
+            token_endpoint_auth_method: "none",
+            grant_types: ["authorization_code"],
+            response_types: ["code"],
+        });
+    });
+    // ── /authorize: muestra la pantalla de consentimiento ────────────────────
+    app.get("/authorize", (req, res) => {
+        const { client_id, redirect_uri, state, code_challenge, code_challenge_method } = req.query;
+        if (!client_id || !redirect_uri || !code_challenge) {
+            res.status(400).send("Faltan parámetros OAuth (client_id, redirect_uri, code_challenge).");
+            return;
+        }
+        if ((code_challenge_method ?? "S256") !== "S256") {
+            res.status(400).send("Solo se soporta code_challenge_method=S256.");
+            return;
+        }
+        const html = `<!doctype html><html lang="es"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Conectar Facturador Pulsando</title>
+<style>body{font-family:system-ui,sans-serif;background:#0b1220;color:#e2e8f0;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+.card{background:#111a2e;border:1px solid #1e293b;border-radius:16px;padding:32px;max-width:420px;width:90%}
+h1{font-size:20px;margin:0 0 8px}p{color:#94a3b8;font-size:14px;line-height:1.5}
+input{width:100%;box-sizing:border-box;padding:12px;margin:16px 0;border-radius:8px;border:1px solid #334155;background:#0b1220;color:#e2e8f0;font-family:monospace}
+button{width:100%;padding:12px;border:0;border-radius:8px;background:#22c55e;color:#052e16;font-weight:700;font-size:15px;cursor:pointer}
+.hint{font-size:12px;color:#64748b;margin-top:12px}</style></head>
+<body><form class="card" method="POST" action="/authorize">
+<h1>Conectar con Facturador Pulsando</h1>
+<p>Autoriza a tu asistente de IA a emitir y consultar DTE en tu nombre. Pega tu <b>API Key</b> de Pulsando (usa <code>sk_test_</code> para probar).</p>
+<input type="password" name="api_key" placeholder="sk_live_... o sk_test_..." autocomplete="off" required>
+<input type="hidden" name="client_id" value="${escapeHtml(client_id)}">
+<input type="hidden" name="redirect_uri" value="${escapeHtml(redirect_uri)}">
+<input type="hidden" name="state" value="${escapeHtml(state ?? "")}">
+<input type="hidden" name="code_challenge" value="${escapeHtml(code_challenge)}">
+<button type="submit">Autorizar</button>
+<p class="hint">La llave se guarda cifrada en nuestro servidor y tu asistente nunca la ve. Puedes revocarla desde el portal.</p>
+</form></body></html>`;
+        res.type("html").send(html);
+    });
+    // ── /authorize (POST): valida la API Key y emite el code ─────────────────
+    app.post("/authorize", async (req, res) => {
+        const { api_key, client_id, redirect_uri, state, code_challenge } = req.body ?? {};
+        if (!api_key || !client_id || !redirect_uri || !code_challenge) {
+            res.status(400).send("Solicitud inválida.");
+            return;
+        }
+        const valid = await validateApiKey(String(api_key), apiBaseUrl);
+        if (!valid) {
+            res.status(401).type("html").send('<p style="font-family:system-ui">API Key inválida o inactiva. <a href="javascript:history.back()">Volver</a></p>');
+            return;
+        }
+        const code = rand(24);
+        codes.set(code, {
+            apiKey: String(api_key),
+            clientId: String(client_id),
+            redirectUri: String(redirect_uri),
+            codeChallenge: String(code_challenge),
+            expiresAt: Date.now() + CODE_TTL_MS,
+        });
+        const sep = String(redirect_uri).includes("?") ? "&" : "?";
+        const url = `${redirect_uri}${sep}code=${encodeURIComponent(code)}${state ? `&state=${encodeURIComponent(String(state))}` : ""}`;
+        res.redirect(url);
+    });
+    // ── /token: intercambia code + PKCE por access_token ─────────────────────
+    app.post("/token", (req, res) => {
+        const { grant_type, code, code_verifier, redirect_uri } = req.body ?? {};
+        if (grant_type !== "authorization_code") {
+            res.status(400).json({ error: "unsupported_grant_type" });
+            return;
+        }
+        const entry = code ? codes.get(String(code)) : undefined;
+        if (!entry || Date.now() > entry.expiresAt) {
+            codes.delete(String(code));
+            res.status(400).json({ error: "invalid_grant" });
+            return;
+        }
+        if (redirect_uri && redirect_uri !== entry.redirectUri) {
+            res.status(400).json({ error: "invalid_grant", error_description: "redirect_uri mismatch" });
+            return;
+        }
+        if (!code_verifier || !verifyPkce(String(code_verifier), entry.codeChallenge)) {
+            res.status(400).json({ error: "invalid_grant", error_description: "PKCE verification failed" });
+            return;
+        }
+        codes.delete(String(code)); // un solo uso
+        const accessToken = rand(32);
+        tokens.set(accessToken, { apiKey: entry.apiKey, expiresAt: Date.now() + TOKEN_TTL_MS });
+        res.json({
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: Math.floor(TOKEN_TTL_MS / 1000),
+            scope: "mcp",
+        });
+    });
+}

package/dist/server.js

@@ -0,0 +1,194 @@
+/**
+ * Fábrica del servidor MCP de Facturador Pulsando.
+ *
+ * Define las herramientas una sola vez y las comparte entre el transporte stdio
+ * (uso local, index.ts) y el transporte HTTP remoto (http.ts). La API Key se
+ * inyecta por parámetro: en stdio viene del env; en remoto, del header
+ * Authorization de cada request (cada usuario usa su propia llave → el paywall
+ * y los scopes se respetan por tenant).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+export const DEFAULT_BASE_URL = "https://api.facturador.pulsandotech.cl/api/public/v1";
+/** Cliente HTTP mínimo contra la API con el header X-Api-Key. */
+function makeApi(apiKey, baseUrl) {
+    return async function api(method, path, opts = {}) {
+        const headers = {
+            "X-Api-Key": apiKey,
+            Accept: "application/json",
+            // Marca el tráfico como originado por el MCP (agentes de IA) para que la
+            // plataforma lo atribuya en métricas/monetización (source=mcp).
+            "X-Client": "facturador-mcp/0.2.0",
+            "User-Agent": "facturador-mcp/0.2.0",
+        };
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (opts.idempotencyKey)
+            headers["Idempotency-Key"] = opts.idempotencyKey;
+        const res = await fetch(`${baseUrl}${path}`, {
+            method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+        const text = await res.text();
+        let pretty = text;
+        try {
+            pretty = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            /* respuesta no-JSON: se devuelve tal cual */
+        }
+        const replayed = res.headers.get("Idempotent-Replayed") === "true";
+        return `HTTP ${res.status}${replayed ? " (idempotent-replayed)" : ""}\n${pretty}`;
+    };
+}
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const fail = (text) => ({
+    content: [{ type: "text", text }],
+    isError: true,
+});
+// ── Esquemas reutilizables ──────────────────────────────────────────────────
+const receptor = z
+    .object({
+    rut: z.string().describe("RUT sin puntos ni DV, ej '12345678'"),
+    dv: z.string().describe("Dígito verificador, ej '5' o 'K'"),
+    razon_social: z.string(),
+    giro: z.string().optional(),
+    direccion: z.string().optional(),
+    comuna: z.string().optional(),
+    ciudad: z.string().optional(),
+    email: z.string().optional(),
+})
+    .describe("Receptor. Opcional en boletas (39/41) y NC/ND de boleta.");
+const item = z.object({
+    nombre: z.string().describe("Descripción, máx 80 caracteres"),
+    cantidad: z.number().optional(),
+    precio_unitario: z.number().int().optional(),
+    monto_item: z.number().int().describe("Monto de la línea, entero CLP"),
+});
+const totales = z.object({
+    monto_neto: z.number().int().optional(),
+    monto_iva: z.number().int().optional(),
+    monto_exento: z.number().int().optional(),
+    monto_total: z.number().int(),
+    tasa_iva: z.number().optional(),
+});
+const referencia = z.object({
+    tipo_dte_ref: z.number().int(),
+    folio_ref: z.number().int(),
+    fecha_ref: z.string().describe("YYYY-MM-DD"),
+    razon_ref: z.string().optional(),
+});
+const qs = (args) => new URLSearchParams(Object.entries(args)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => [k, String(v)])).toString();
+/**
+ * Construye un McpServer con todas las herramientas, usando la API Key dada.
+ */
+export function buildServer(apiKey, baseUrl = DEFAULT_BASE_URL) {
+    const api = makeApi(apiKey, baseUrl);
+    const server = new McpServer({ name: "facturador-pulsando", version: "0.2.0" });
+    server.tool("emitir_dte", "Emite un DTE al SII de Chile (factura 33/34, boleta 39/41, guía 52, ND 56, NC 61). " +
+        "NO envíes el emisor (se toma de la empresa dueña de la API Key). Asíncrono: " +
+        "responde folio y estado 'pendiente'. Idempotency-Key automática.", {
+        tipo_dte: z.number().int(),
+        fecha_emision: z.string().describe("YYYY-MM-DD, no futura (hora Chile)"),
+        receptor: receptor.optional(),
+        items: z.array(item).min(1).describe("Facturas/NC: montos NETOS. Boletas: CON IVA."),
+        totales,
+        referencias: z.array(referencia).optional().describe("Obligatorio en NC/ND 56/61"),
+        ind_traslado: z.number().int().optional().describe("Solo guía 52"),
+        incluir_pdf: z.boolean().optional(),
+    }, async (args) => {
+        try {
+            const { incluir_pdf, ...body } = args;
+            const path = "/dte" + (incluir_pdf ? "?incluir=pdf" : "");
+            return ok(await api("POST", path, { body, idempotencyKey: randomUUID() }));
+        }
+        catch (e) {
+            return fail(`Error al emitir: ${e.message}`);
+        }
+    });
+    server.tool("consultar_dte", "Consulta detalle y estado SII de un DTE por id (incluye detalle_sii si fue rechazado).", { id: z.number().int() }, async ({ id }) => {
+        try {
+            return ok(await api("GET", `/dte/${id}`));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    server.tool("listar_dtes", "Lista/filtra DTE emitidos (reportes). Ej: facturas rechazadas del mes.", {
+        q: z.string().optional(),
+        tipo_dte: z.string().optional().describe("Un tipo o CSV '33,34'"),
+        estado_local: z.string().optional(),
+        desde: z.string().optional(),
+        hasta: z.string().optional(),
+        per_page: z.number().int().optional(),
+        page: z.number().int().optional(),
+    }, async (args) => {
+        try {
+            const q = qs(args);
+            return ok(await api("GET", `/dte${q ? `?${q}` : ""}`));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    server.tool("consultar_contribuyente", "Padrón SII por RUT (razón social + giros). Para autocompletar/validar el receptor.", { rut: z.string().describe("Con o sin puntos y DV, ej '76354771-K'") }, async ({ rut }) => {
+        try {
+            return ok(await api("GET", `/contribuyentes/${encodeURIComponent(rut)}`));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    server.tool("estado_folios", "Estado de folios (CAF) por tipo: próximo folio, disponibles y alertas.", {}, async () => {
+        try {
+            return ok(await api("GET", "/caf/status"));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    server.tool("documentos_recibidos", "Lista documentos que otros te emitieron (intercambio). Requiere scope recepcion:read.", {
+        pendientes: z.boolean().optional(),
+        rut_emisor: z.string().optional(),
+        per_page: z.number().int().optional(),
+    }, async (args) => {
+        try {
+            const q = qs(args);
+            return ok(await api("GET", `/dte/recibidos${q ? `?${q}` : ""}`));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    server.tool("sincronizar_rcv", "Encola la sincronización del Registro de Compras y Ventas (RCV) del SII para un " +
+        "periodo (YYYYMM) y operación (compra/venta/ambas). Requiere scope rcv:read.", {
+        periodo: z.string().describe("YYYYMM, ej '202607'"),
+        operacion: z.enum(["compra", "venta", "ambas"]).optional(),
+    }, async (args) => {
+        try {
+            return ok(await api("POST", "/rcv/sincronizar", { body: args }));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    server.tool("listar_rcv", "Lee el RCV ya sincronizado (compras/ventas del SII). Filtros: periodo, operacion, tipo_dte.", {
+        periodo: z.string().optional().describe("YYYYMM"),
+        operacion: z.enum(["compra", "venta"]).optional(),
+        tipo_dte: z.number().int().optional(),
+        per_page: z.number().int().optional(),
+    }, async (args) => {
+        try {
+            const q = qs(args);
+            return ok(await api("GET", `/rcv${q ? `?${q}` : ""}`));
+        }
+        catch (e) {
+            return fail(`Error: ${e.message}`);
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@facturador-mcp-sii.cl/mcp",
+  "version": "0.2.0",
+  "description": "Servidor MCP para la API de facturación electrónica SII Chile de Facturador Pulsando. Conecta un agente de IA (Claude, etc.) a la emisión y consulta de DTE.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sii",
+    "chile",
+    "factura-electronica",
+    "dte",
+    "boleta-electronica",
+    "facturacion",
+    "claude"
+  ],
+  "license": "MIT",
+  "author": "Pulsando Tech",
+  "homepage": "https://www.pulsandotech.cl",
+  "type": "module",
+  "bin": {
+    "facturador-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "express": "^4.19.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.14.0",
+    "@types/express": "^4.17.21"
+  }
+}