# mcp-xubio

Un servidor MCP que expone la API de contabilidad de [Xubio](https://xubio.com) como
herramientas para Claude, así podés consultar clientes, facturas, productos y saldos hablando
en lenguaje natural en vez de navegar la interfaz web.

> **¿Sos contador y solo querés instalarlo?** Guía paso a paso con capturas y descarga en un
> clic: **https://ignacio-llabot.github.io/mcp-xubio/**

**Solo lectura.** Las 52 herramientas son endpoints `GET`. Los endpoints de escritura de Xubio
crean comprobantes fiscales reales y piden el CAE a la AFIP — esos quedan deliberadamente afuera.

## Requisitos

- Una cuenta de Xubio en el **plan PLUS o superior** — la API no está disponible en planes menores
- Para *usarlo*: Claude Desktop (trae su propio Node — no hay que instalar nada más)
- Para *armar el bundle*: Node 18+ (desarrollado sobre 22.19)

## Instalación para usuarios finales (contadores) — sin terminal, sin Node

Distribuí el único archivo `mcp-xubio.mcpb` (se arma más abajo). El usuario:

1. Hace doble clic en `mcp-xubio.mcpb` → Claude Desktop abre el diálogo de instalación.
2. Pega su **Client ID** y su **Secret ID** en el formulario (se obtienen en Xubio:
   Configuración → Integraciones → API de Xubio → Nueva App Cliente — requiere el plan PLUS).
3. Hace clic en **Instalar**.

Claude Desktop trae su propio Node.js, así que no hay nada que instalar ni ningún archivo de
configuración que editar. Las credenciales van directo al llavero (keychain) del sistema desde
el formulario — nunca a un archivo de texto. Si Windows SmartScreen advierte sobre un bundle sin
firmar descargado de la web, hacé clic en **Más información → Ejecutar de todas formas**; alojá
el archivo en un lugar de confianza para evitar la advertencia.

### Armar el bundle `.mcpb` (mantenedor, una vez por release)

```bash
npm install
npm run bundle     # tsc → dist, después mcpb pack → mcp-xubio.mcpb
```

`manifest.json` declara los dos campos de credenciales como el formulario de instalación. El
bundle se verifica desempaquetándolo y corriendo `dist/index.js` de forma autónoma.

## Instalación para desarrolladores (Claude Code / CLI)

```bash
npm install
npm run build
```

## Credenciales

En Xubio: **Configuración → Integraciones → API de Xubio → Nueva App Cliente**. Obtenés un
`Client_id` y un `Secret_id`.

El servidor las lee del entorno y **nunca las escribe en disco**:

| Variable | Requerida | Significado |
|---|---|---|
| `XUBIO_CLIENT_ID` | sí, al momento de llamar | Client_id de la app de Xubio |
| `XUBIO_SECRET_ID` | sí, al momento de llamar | Secret_id de la app de Xubio |
| `XUBIO_TOOLS` | no | `operationId`s separados por coma. Acota el set de herramientas. Vacío = sin filtro. |

Las credenciales solo hacen falta cuando una herramienta se **llama**. El servidor arranca y
responde `tools/list` sin ellas, que es lo que permite que toda la suite de tests corra offline.

## Registrar en Claude (CLI)

```bash
claude mcp add xubio \
  --env XUBIO_CLIENT_ID=... \
  --env XUBIO_SECRET_ID=... \
  -- node /ruta/absoluta/a/mcp-xubio/dist/index.js
```

52 herramientas ocupan bastante contexto en cada sesión. Si usás solo algunas, acotá:

```bash
--env XUBIO_TOOLS=getClienteBeans,getFacturaVentaBeans,getProductoVentaBeans
```

> En Claude Code, las herramientas MCP se difieren por defecto (tool search): solo se cargan
> los nombres hasta que Claude las busca, así que el costo de contexto real es mínimo y no hace
> falta filtrar. En Claude Desktop, filtrar con `XUBIO_TOOLS` sí reduce lo que se envía.

## Qué obtenés

Los nombres de las herramientas son los `operationId` del spec; las descripciones vienen
directo de Xubio:

```
getClienteBeans                 Obtiene todos los Clientes
getFacturaVentaBeans            Obtiene listado de Facturas de Venta
getAsientoContableManualBeans   Obtiene listado de Asientos Contables Manuales
getEmpresaBean                  Obtiene los datos de Mi Empresa
```

Listarlas todas:

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| node dist/index.js \
| node -e "let s='';process.stdin.setEncoding('utf8').on('data',d=>s+=d).on('end',()=>{const r=s.trim().split('\n').map(JSON.parse).find(m=>m.id===2);r.result.tools.forEach(t=>console.log(t.name))})"
```

En Windows PowerShell, escribí los frames a un archivo y redirigí en vez de pipear —
PowerShell 5.1 antepone un BOM UTF-8 al stdin de un comando nativo, lo que corrompe el
primer frame.

## Prueba en vivo

```bash
export XUBIO_CLIENT_ID='...' XUBIO_SECRET_ID='...'
# después llamá getClienteBeans desde cualquier cliente MCP
```

Fallas esperables que conviene reconocer:

| Respuesta | Causa |
|---|---|
| `XUBIO_CLIENT_ID / XUBIO_SECRET_ID are not set` | Al entorno del servidor le faltan. Ojo: un cliente MCP de escritorio no hereda tu shell interactiva. |
| `HTTP 400: {"error":"invalid_client"}` | Las credenciales están seteadas pero son incorrectas. |
| `HTTP 403` | Normalmente, una cuenta por debajo del plan PLUS. |

## Cómo funciona

`src/index.ts` tiene ~172 líneas. Las herramientas se **generan al arrancar** desde un
`swagger.json` incluido en el repo — una herramienta por operación `GET`, mapeando los tipos de
parámetro de Swagger a un esquema Zod. Nada se escribe a mano por endpoint, así que un endpoint
nuevo de Xubio aparece simplemente refrescando el spec:

```bash
curl -o swagger.json https://xubio.com/API/1.1/swagger.json
npm test
```

El spec se commitea en vez de descargarse en tiempo de ejecución: la lista de herramientas queda
determinística, el servidor no depende de la red al arrancar, y un cambio en la API de Xubio
aparece como un diff revisable.

## Tests

```bash
npm test        # compila, después corre node --test (30 tests, sin framework)
npx tsc --noEmit
```

Todo es offline — el intercambio de token y las llamadas a la API se testean contra mocks de
`node:test`. Lo único que los mocks no pueden probar es una vuelta completa con credenciales
reales; para eso está la prueba en vivo de arriba.

## Límites conocidos

Marcados en el código con comentarios, cada uno indicando su camino de mejora:

- **Paginación.** `/comprobanteVentaBean` y `/comprobanteCompraBean` paginan mediante headers
  HTTP que Xubio documenta solo en prosa y no declara como parámetros de Swagger, así que el
  generador no puede verlos. Obtenés una única página sin paginar por llamada.
- **Forma de las respuestas.** El spec declara las respuestas de listado como un único objeto,
  pero la API devuelve un array. El JSON se pasa tal cual, así que el desajuste no cuesta nada —
  no lo "arregles" validando contra el esquema declarado.
- **Concurrencia.** Llamadas iniciales simultáneas pueden generar cada una un token. Es inocuo
  (todos los tokens son válidos, gana el último) y no amerita un lock hasta que aparezca en la
  práctica.

## Aviso

Proyecto no oficial, hecho por la comunidad. **Sin afiliación, respaldo ni soporte de Xubio.**
"Xubio" y las marcas relacionadas pertenecen a su respectivo dueño. El `swagger.json` incluido
es la propia especificación pública de la API de Xubio, incorporada solo para que la lista de
herramientas quede determinística — refrescala desde el endpoint oficial (ver *Cómo funciona*).
Usalo bajo tu propia responsabilidad: accede a tus datos contables reales. Es solo lectura, pero
siguen siendo tus datos.

## Licencia

MIT — ver [LICENSE](LICENSE).