io.github.nubiia-dev/mcp-freematica

mcp-freematica

MCP server que expone operaciones del API REST de Freemática (ERP: facturación, cartera, proveedores, contabilidad, personal) para ser consumidas por asistentes de IA como Claude.

Built and maintained by Nubiia — automatización e integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así para tu empresa? Escríbenos en nubiia.es.

Stack

• TypeScript + Node.js ≥20
• @modelcontextprotocol/sdk (stdio + Streamable HTTP transports)
• Express + axios + zod
• pino (logging estructurado)
• Vitest + nock para tests

Tools expuestas

Tools de escritura (requieren FREEMATICA_ENABLE_WRITES=true)

Por defecto el servidor es de solo lectura. Con FREEMATICA_ENABLE_WRITES=true se registran además estas tools de creación y actualización. No existe ninguna tool de borrado. Todas las escrituras dejan log de auditoría (operación + endpoint + campos a nivel info; body completo a nivel debug).

Filtros tipados (FIQL interno)

El MCP expone parámetros tipados con zod al consumidor (Claude/LLM). Internamente, el cliente los traduce a sintaxis FIQL antes de llamar al API de Freemática. El consumidor nunca ve ni escribe FIQL.

Ejemplo

// El LLM llama:
freematica_list_cartera_clientes({
  empresa: '0001',
  fechaDocDesde: '2026-01-01',
  estado: 'pendiente',
});

// El MCP construye internamente (valores siempre entre comillas simples):
// rquery=CARCL_EMP=='0001';CARCL_FECDOC=ge='2026-01-01';CARCL_SITCAR=='1'

Ventajas del patrón

• El LLM solo necesita conocer los parámetros tipados con nombres semánticos en español.
• La complejidad de la sintaxis FIQL queda encapsulada en el adapter interno (src/clients/fiql-builder.ts).
• Los errores de validación son claros: "empresa debe ser string", no "FIQL parse error".
• Los filtros booleanos (soloImpagados: true) se traducen automáticamente al operador FIQL correcto.

Más ejemplos

// Facturas pendientes de traspaso a contabilidad:
freematica_list_facturas_cabecera({
  empresa: '0001',
  traspasadoContabilidad: false,
});
// → rquery=FVC_CODEMP=='0001';FVC_TRASP_CONTAB=='0'

// Proveedor por nombre EXACTO (el API no soporta búsqueda parcial: =lk=
// responde 400 y los wildcards % devuelven 0 resultados). El filtro activo
// de proveedores post-filtra las bajas en cliente (FIQL no tiene IS NULL):
freematica_list_proveedores({
  nombre: 'LEJIAS PONS S.A.',
  activo: true,
});
// → rquery=NOMBRE_PRO=='LEJIAS PONS S.A.'

Modos de transporte

El binario soporta dos transportes seleccionables. La selección sigue este orden de precedencia:

1. CLI flag: --transport=<modo>
2. Variable de entorno: MCP_TRANSPORT=<modo>
3. Default: stdio

Configurar en Claude Desktop (stdio)

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "freematica": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-freematica"],
      "env": {
        "FREEMATICA_AUTH_TOKEN": "...",
        "FREEMATICA_AUTH_COMPANY": "...",
        "FREEMATICA_AUTH_ORGANIZATION": "...",
        "FREEMATICA_AUTH_APP": "...",
        "FREEMATICA_AUTH_SESSION": "..."
      }
    }
  }
}

Reinicia Claude Desktop y las tools de freematica_* aparecerán disponibles.

Configurar en Claude Code (stdio)

claude mcp add freematica npx -y @nubiia/mcp-freematica \
  -e FREEMATICA_AUTH_TOKEN=... \
  -e FREEMATICA_AUTH_COMPANY=... \
  -e FREEMATICA_AUTH_ORGANIZATION=... \
  -e FREEMATICA_AUTH_APP=... \
  -e FREEMATICA_AUTH_SESSION=...

Configurar en Nubiia (HTTP)

Setear MCP_TRANSPORT=http en las variables de entorno del proceso, junto a las 5 FREEMATICA_AUTH_*. Resto de variables (puerto, origins) opcionales — ver tabla en "Configuración avanzada".

Datos maestros disponibles

La tool freematica_get_master_data acepta un parámetro catalog con uno de los 24 valores siguientes. Cada uno mapea a un endpoint específico de Freemática.

Respuesta: { catalog, items, count, total }. Patrón típico de uso: llamar primero al catálogo correspondiente cuando otra tool devuelva IDs crípticos para resolverlos a nombres humanos.

Paginación

Todas las tools freematica_list_* aceptan dos parámetros opcionales:

• page (int, ≥1, default 1): página a recuperar, 1-indexed.
• items (int, 1..50, default 20): items por página.

La respuesta incluye siempre total (total de elementos en el dataset) para que el LLM pueda iterar páginas.

El parámetro está bloqueado en page >= 1 porque el API real de Freemática trata page=0 como "devuelve TODO el dataset" (varios MB en endpoints grandes como clientes). Verificado empíricamente.

IDs opacos en endpoints de detalle

Las tools freematica_get_* requieren un id que NO es el código natural (COD_CLI, ID_OPORTUNIDAD) sino el campo idReg que aparece en los items del listado correspondiente. Es un string opaco base64 como MV9fMTAwMA==.

Si pasas un código natural, el API responde not_found.

Patrón típico de uso desde el LLM:

1. freematica_list_clientes(page=1, items=20) → encontrar el cliente que interesa.
2. Tomar el campo idReg de ese item.
3. freematica_get_cliente(id="<idReg>") → detalle completo.

Configuración

El servidor lee toda su configuración de variables de entorno al arrancar. Si falta alguna obligatoria, el proceso muere con un mensaje claro listando qué falta — no acepta requests hasta que la configuración sea válida.

Variables de entorno obligatorias

Configuración avanzada

Variables de entorno opcionales para tuning de comportamiento en producción:

De dónde salen las credenciales x-auth-*

Las 5 credenciales x-auth-* son preexistentes — el Postman collection de Freemática no expone un endpoint de login, así que estas credenciales se obtienen fuera de banda (típicamente por el departamento de IT de Freemática o tu integrador).

• Pide los 5 valores al responsable técnico de Freemática (o recupéralos de tu gestor de secretos si ya están provisionados).
• NO comitees credenciales reales. El repositorio tiene .env.* en .gitignore (excepto .env.example).
• Si las credenciales caducan, el MCP devolverá invalid_token en todas las llamadas. Renovarlas implica reiniciar el proceso (no hay refresh automático).

Configuración en Nubiia (producción)

Nubiia despliega el servidor MCP y se encarga de inyectar las variables de entorno. En el panel de Nubiia:

1. Crea un MCP server apuntando a la URL del contenedor desplegado (por ejemplo https://freematica-mcp.example.com/mcp).
2. Añade las variables de entorno listadas arriba en la sección de secretos.
3. Recomendado: setear MCP_ALLOWED_ORIGINS al dominio exacto desde el que Claude/Nubiia conecta, no *.
4. Verifica con el endpoint GET /health que el servidor está vivo antes de habilitar el MCP en Claude.

Configuración local (desarrollo)

Para desarrollo local crea un .env (o .env.local) en la raíz:

cp .env.example .env
# Edita .env y rellena los 5 FREEMATICA_AUTH_*

Luego arranca con:

set -a; source .env; set +a
npm run dev

O todo en una línea:

node --env-file=.env --import tsx src/index.ts

Verificación de la configuración

1. Sin env vars — el proceso debe morir inmediatamente con un mensaje listando las 5 variables que faltan:

    node dist/index.js
    # [freematica-mcp] FATAL: Invalid configuration:
    #   - FREEMATICA_AUTH_TOKEN: Required
    #   - FREEMATICA_AUTH_COMPANY: Required
    #   ...

2. Con env vars válidas (modo HTTP) — arranca con MCP_TRANSPORT=http y el proceso queda escuchando; /health devuelve { "status": "ok", "version": "0.5.0", "sessions": 0 }:

    MCP_TRANSPORT=http node dist/index.js &
    curl http://localhost:3000/health

   En modo stdio (default) no hay endpoints HTTP — el server escucha JSON-RPC por stdin/stdout.

Troubleshooting

invalid_token en todas las llamadas

Las credenciales x-auth-* han caducado o son incorrectas. Pasos:

1. Verificar que las 5 variables FREEMATICA_AUTH_* están seteadas correctamente.
2. Contactar al responsable técnico de Freemática para renovar el token/sesión.
3. Reiniciar el proceso del MCP tras actualizar las variables (el cliente no refresca credenciales en caliente).

network_error — upstream Freemática caído

El API de Freemática no está respondiendo. Puede ser:

• Mantenimiento programado del upstream.
• Circuit breaker activo tras varios fallos consecutivos (ver logs: Circuit breaker opened).
• Problema de red entre el servidor y api-p01.clientservicepanel.com.

Pasos:

1. Verificar en los logs si hay circuitBreaker: "open" — si es así, esperar FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS ms (default 30s) para que pase a half-open.
2. Verificar conectividad al upstream: curl https://api-p01.clientservicepanel.com/.
3. Aumentar FREEMATICA_TIMEOUT_MS si el upstream es lento (default 30s puede ser insuficiente en algunas redes).

rate_limit_exceeded — throttling de Freemática

Freemática devuelve 429. El MCP reintenta automáticamente honrando el header Retry-After si está presente. Si el problema persiste:

1. Reducir la frecuencia de llamadas desde Claude.
2. Aumentar FREEMATICA_MAX_RETRIES (default 3) si los reintentos no son suficientes.
3. Contactar a Freemática para revisar los límites de rate asignados a la cuenta.

Response truncated en freematica_export_asientos

El endpoint de exportación de asientos devuelve demasiados registros para un rango de fechas amplio. Pasos:

1. Usar un rango de fechas más corto: en lugar de un trimestre, exportar mes a mes.
2. Añadir filtros adicionales: filtrar por empresa, delegación o cuenta específica.
3. Si el volumen esperado es grande por diseño, aumentar FREEMATICA_MAX_RESPONSE_SIZE_MB (default 10 MB).

El pre-commit hook falla al hacer git commit

Lint o formato detectaron errores en los ficheros staged. Pasos:

1. Revisar el output del hook: indicará qué fichero y qué regla falló.
2. Ejecutar npm run lint:fix y npm run format para corregir automáticamente.
3. Hacer git add de los ficheros corregidos antes de volver a intentar el commit.

Desarrollo

npm install
npm run dev           # arranca con tsx (hot reload)
npm test              # ejecuta vitest una vez
npm run test:watch    # watcher
npm run test:coverage # coverage report
npm run lint
npm run lint:fix
npm run format
npm run typecheck
npm run build         # compila a dist/
npm start             # ejecuta dist/index.js

Testing

Tests unitarios e integración

# Ejecutar todos los tests
npm test

# Ejecutar con coverage report
npm test -- --coverage

# Ejecutar un archivo concreto
npm test -- tests/fiql-builder.property.test.ts

Los tests están en tests/ organizados por tipo:

• tests/clients/ — tests de los clientes HTTP (con nock)
• tests/schemas/ — tests de los schemas Zod
• tests/tools/ — tests de los handlers MCP (unit + integration)
• tests/fiql-builder.*.test.ts — tests unitarios y property-based del FIQL builder
• tests/pagination-edge-cases.test.ts — edge cases del adapter de paginación
• tests/coverage-gaps.test.ts — cobertura específica de ramas no cubiertas

Coverage thresholds (configurados en vitest.config.ts):

• Global statements: ≥85%
• src/clients/: ≥90%
• src/schemas/: ≥90%
• src/tools/: ≥85%

Testing manual con MCP Inspector

Para probar el servidor MCP de forma interactiva, usa MCP Inspector.

Ver instrucciones detalladas en docs/testing-e2e.md.

Endpoints HTTP

Seguridad

[!IMPORTANT] El endpoint /mcp no autentica al cliente. Cualquiera con acceso de red al puerto puede invocar las tools usando las credenciales de Freemática que el servidor tiene configuradas en sus variables de entorno. Como todas las tools son de solo lectura, esto equivale a acceso de lectura a los datos de la empresa (cartera, facturación, clientes, personal…).

Por tanto, al desplegar en modo HTTP:

• Nunca expongas el puerto directamente a internet. Despliega siempre detrás de un gateway / reverse-proxy que haga la autenticación y autorización del cliente (es el modelo con el que opera Nubiia).
• Restringe MCP_ALLOWED_ORIGINS al dominio exacto desde el que se conecta, en lugar del valor por defecto *. Si arrancas con *, el servidor emite un warning en el log. Ten en cuenta que CORS solo protege frente a navegadores; no frente a clientes como curl.
• Trata las 5 credenciales FREEMATICA_AUTH_* como secretos. Inyéctalas vía gestor de secretos, nunca en el repositorio (.env* está en .gitignore).

Buenas prácticas ya incluidas en el servidor:

• Los headers x-auth-* se eliminan de cualquier log (incluido debug/trace) y los bodies de petición nunca se loguean.
• Rate limiting (120 req/min por IP) en /mcp y /health, límite de body de 1 MB, y expiración automática de sesiones inactivas.
• Los valores de los filtros FIQL se escapan para prevenir inyección de operadores de consulta.

Cómo añadir una nueva operación

1. Tipar la respuesta en src/types/<grupo>.ts.
2. Añadir método al FreematicaClient (src/clients/freematica-client.ts):

    getContratosServicios(): Promise<VoContratosServicios[]> {
      return this.get<VoContratosServicios[]>('/pvss/v1/contratos-servicios');
    }

3. Añadir server.tool(...) en src/tools/<grupo>.ts (o crear el archivo si el grupo es nuevo).
4. Si el grupo es nuevo: registrar register<Grupo>Tools(server, client) en src/server.ts.
5. Tests: un test del método del client (con nock) + un test del handler de la tool.

Patrón inspirado en mcp-nevent y mcp-holded.

Despliegue

Pensado para ejecutarse dentro de Nubiia. La plataforma se encarga del deploy y de inyectar las variables de entorno. Tienes 3 opciones:

Opción 1 — Instalar como paquete npm (recomendada)

El paquete se publica como @nubiia/mcp-freematica en el registry público de npm cuando se crea un tag v* en main.

# Instalar y ejecutar (no requiere autenticación)
npm install -g @nubiia/mcp-freematica
mcp-freematica   # binario instalado, lee env vars y arranca el server

Opción 2 — Docker

docker build -t mcp-freematica .
docker run --env-file .env -p 3000:3000 mcp-freematica

Opción 3 — Clone + build

git clone https://github.com/nubiia-dev/mcp-freematica.git
cd mcp-freematica
npm ci && npm run build
node dist/index.js

Publicar una nueva versión

1. Bump de versión en package.json (semver).
2. Commit + merge a main.
3. Crear y empujar un tag con prefijo v:

    git tag v0.5.0
    git push origin v0.5.0

4. El workflow .github/workflows/publish.yml se dispara, valida (lint + typecheck + test + build) y publica en npm.

Especificaciones y diseño

• v0.1.0 spec: docs/superpowers/specs/2026-05-18-freematica-mcp-design.md (bootstrap inicial)
• v0.1.0 plan: docs/superpowers/plans/2026-05-18-freematica-mcp.md
• v0.2.0 spec: docs/superpowers/specs/2026-05-19-stdio-transport-design.md (stdio support)
• v0.2.0 plan: docs/superpowers/plans/2026-05-19-stdio-transport.md
• v0.3.0 spec: docs/superpowers/specs/2026-05-19-master-data-tool-design.md (master data tool)
• v0.3.0 plan: docs/superpowers/plans/2026-05-19-master-data-tool.md
• v0.4.0 spec: docs/superpowers/specs/2026-05-20-commercial-tools-design.md (commercial tools + envelope unwrap fix)
• v0.4.0 plan: docs/superpowers/plans/2026-05-20-commercial-tools.md
• v0.4.1: hotfix de catálogos delegaciones (endpoint cambiado a /agrupcod) y tipos-marcajes (eliminado — endpoint roto). Ver CHANGELOG.
• ADRs de arquitectura: docs/adr/ (ver índice en ese directorio)
• API: apidocs/Freematica API - Complete Collection.postman_collection.json
• CHANGELOG: CHANGELOG.md

About Nubiia

This MCP server is built and maintained by Nubiia.

Nubiia ayuda a empresas a automatizar procesos e integrar sus herramientas con IA: servidores MCP a medida, integraciones con ERPs y CRMs (Freemática, Holded, Pipedrive…), y agentes que conectan tus datos de negocio con asistentes como Claude. Este @nubiia/mcp-freematica es un ejemplo open source de lo que hacemos.

👉 ¿Quieres una integración o automatización con IA para tu negocio? nubiia.es · ✉️ hola@nubiia.es

Author

Built by Nubiia — nubiia.es · hola@nubiia.es

Maintainer: Samuel Fraga — GitHub

Links

• Nubiia — AI automation & integrations
• npm: @nubiia/mcp-freematica
• GitHub: nubiia-dev/mcp-freematica

Licencia

MIT — ver LICENSE.