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

Tool	Endpoint Freemática	Descripción
freematica_list_articulos	GET /part/v1/articulos	Catálogo de artículos/materiales/consumibles (referencias, familias, proveedores)
freematica_get_articulo	GET /part/v1/articulos/{idreg}	Detalle de un artículo
freematica_get_precio_articulo	GET /pgrl/v1/precio-articulo/{idreg}	Precios de venta de un artículo (PRECIO_VENTA, DESCUENTO, FACTURABLE)
freematica_list_materiales_asignados_servicios	GET /pvss/v2/contratos-servicios-material	Lista de material asignado a servicios
freematica_get_master_data	(24 endpoints según catalog)	Devuelve un catálogo de datos maestros (tipos, geográficos, organizativos, inventario, financiero)
freematica_list_clientes	GET /pgrl/v2/clientes	Lista paginada de clientes
freematica_get_cliente	GET /pgrl/v2/clientes/{idReg}	Detalle de un cliente
freematica_list_contactos_clientes	GET /pgrl/v2/contactos-clientes	Lista paginada de contactos
freematica_list_oportunidades_negocio	GET /pcrm/v2/oportunidades-negocio	Lista paginada de oportunidades
freematica_get_oportunidad_negocio	GET /pcrm/v2/oportunidades-negocio/{idReg}	Detalle de oportunidad
freematica_get_oportunidad_negocio_datos_ampliados	GET /pcrm/v2/oportunidades-negocio/{idReg}/datos-ampliados	Datos ampliados (puede 404)
freematica_get_ficha_prev_cliente	GET /pprl/v2/ficha-prev-cliente	Ficha PRL de un cliente
freematica_list_vigilancia_salud	GET /pprl/v1/vigilancia-salud	Lista paginada de registros de Vigilancia de la Salud
freematica_get_vigilancia_salud	GET /pprl/v1/vigilancia-salud/{idreg}	Detalle de un registro de Vigilancia de la Salud
freematica_list_personal	GET /pers/v1/personal	Lista paginada de personas (RRHH)
freematica_get_persona	GET /pers/v2/personal/{idreg}	Detalle de una persona
freematica_list_calendarios	GET /pgrl/v1/calendarios	Lista paginada de calendarios laborales
freematica_list_calendario_periodos	GET /pgrl/v1/calendarios/{idreg}/periodos	Periodos de un calendario laboral
freematica_list_cartera_clientes	GET /pcar/v1/cartera-clientes	Lista paginada de cartera de clientes (cobros, impagados)
freematica_get_cartera_cliente	GET /pcar/v1/cartera-clientes/{idReg}	Detalle de un documento de cartera
freematica_list_facturas_cabecera	GET /pven/v1/facturas-cabecera	Lista paginada de facturas de ventas (cabecera)
freematica_get_factura_cabecera	GET /pven/v1/facturas-cabecera/{idReg}	Detalle de una factura de venta
freematica_list_factura_lineas	GET /pven/v1/facturas-cabecera/{idReg}/lineas	Líneas de detalle de una factura de venta
freematica_list_factura_iva	GET /pven/v1/facturas-cabecera/{idReg}/iva	Líneas de IVA de una factura de venta
freematica_list_factura_vencimientos	GET /pven/v1/facturas-cabecera/{idReg}/vencimientos	Vencimientos de cobro de una factura de venta
freematica_list_facturas_compras	GET /pcom/v1/facturas-cabecera	Lista paginada de facturas de compras
freematica_get_factura_compra	GET /pcom/v1/facturas-cabecera/{idReg}	Detalle de una factura de compra
freematica_list_proveedores	GET /pgrl/v2/proveedores	Lista paginada de proveedores
freematica_get_proveedor	GET /pgrl/v2/proveedores/{idReg}	Detalle de un proveedor
freematica_list_localizaciones_cobro_clientes	GET /pgrl/v2/localizaciones-cobro-clientes	Localizaciones de cobro de clientes (SEPA, domiciliaciones)
freematica_list_localizaciones_pago_proveedores	GET /pgrl/v2/localizaciones-pago-proveedores	Localizaciones de pago de proveedores
freematica_list_localizaciones_servicio_clientes	GET /pgrl/v2/localizaciones-servicio-clientes	Localizaciones de servicio de clientes
freematica_list_cuentas_contables	GET /pcon/v2/cuentas	Plan de cuentas contables (COD_CTA, COD_PLAN, etc.)
freematica_list_cuentas_analiticas	GET /pcon/v2/cuentas-analiticas	Catálogo de cuentas analíticas
freematica_export_asientos	GET /pcon/v2/asientos	Exporta asientos contables de un período (CSV/JSON)
freematica_list_pedidos_compra	GET /pcmp/v2/pedidos	Lista paginada de pedidos de compra (filtros nativos + FIQL + estado enum)
freematica_get_pedido_compra	GET /pcmp/v2/pedidos/{idReg}	Detalle de un pedido de compra (cabecera + proveedor + líneas)
freematica_list_albaranes_ventas	GET /pven/v2/albaranes-ventas	Lista paginada de albaranes de ventas (filtros todos nativos, empresa requerido)
freematica_get_albaran_venta	GET /pven/v2/albaranes-ventas/{idReg}	Detalle de un albarán de venta
freematica_list_albaranes_factura	GET /pven/v2/albaranes-facturas	Lista paginada de vinculaciones albarán↔factura (idReg nativo + FIQL)
freematica_get_albaran_factura	GET /pven/v2/albaranes-facturas/{idReg}	Detalle de una vinculación albarán-factura
freematica_list_resultados_facturacion	GET /pvss/v1/facturacion-resultados	Resultados del proceso batch de facturación automática de vigilancia (FIQL)
freematica_list_contratos	GET /pvss/v1/contratos	Lista paginada de cabeceras de contratos (solo filtros nativos: el API ignora FIQL aquí)
freematica_get_contrato	GET /pvss/v1/contratos (scan)	Busca un contrato por empresa + código natural (paginación interna + filtrado en cliente)
freematica_list_servicios_contrato	GET /pvss/v1/contratos/{idReg}/servicios	Servicios de un contrato
freematica_get_servicio_contrato	GET /pvss/v2/contratos-servicios/{idReg}	Detalle de un servicio de contrato
freematica_list_contratos_opcionales	GET /ppre/v2/contratos/opcionales	Lista paginada de opcionales de contratos
freematica_get_contrato_opcionales	GET /ppre/v2/contratos/opcionales/{idReg}	Detalle de un registro de opcionales
freematica_list_localizaciones_envio_clientes	GET /pgrl/v2/localizaciones-envio-clientes	Localizaciones de envío de clientes
freematica_list_localizaciones_factura_clientes	GET /pgrl/v2/localizaciones-factura-clientes	Localizaciones de factura de clientes

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).

Tool	Endpoint Freemática	Descripción
freematica_create_contrato	POST /pvss/v2/contratos	Alta de cabecera de contrato
freematica_update_contrato	PUT /pvss/v2/contratos/{idReg}	Actualización de cabecera de contrato
freematica_create_servicio_contrato	POST /pvss/v2/contratos/{idReg}/servicios	Alta de servicio (identificación derivada del idReg)
freematica_update_servicio_fechas	PUT /pvss/v2/contratos/{id}/servicio/{id}	Fechas inicio/fin del servicio (mecanismo de baja)
freematica_create_servicio_historico_precios	POST /pvss/v2/contratos/{id}/servicios-historico-precios/{id}	Alta de revisión de precios del servicio
freematica_update_servicio_historico_precios	PUT /pvss/v2/contratos/{id}/servicios-historico-precios/{id}	Actualización de revisión de precios
freematica_create_servicio_facturacion_txt	POST /pvss/v2/contratos/{id}/servicios-facturacion-txt/{id}	Alta de línea de texto de facturación
freematica_update_servicio_facturacion	PUT /pvss/v2/contratos/{id}/servicios-facturacion/{id}	Datos de facturación del servicio (precios hora, forma de pago…)
freematica_create_contrato_opcionales	POST /ppre/v2/contratos/opcionales	Alta de opcionales de contrato
freematica_update_contrato_opcionales	PUT /ppre/v2/contratos/opcionales/{idReg}	Actualización de opcionales de contrato
freematica_create_cliente	POST /pgrl/v2/clientes	Alta de cliente (idReg derivado de grupo+código)
freematica_update_cliente	PUT /pgrl/v2/clientes/{idReg}	Actualización parcial de cliente (fetch+merge)
freematica_create_contacto_cliente	POST /pgrl/v2/contactos-clientes	Alta de contacto de cliente
freematica_update_contacto_cliente	PUT /pgrl/v2/contactos-clientes/{idReg}	Actualización parcial de contacto (fetch+merge)
freematica_create_localizacion_cliente	POST /pgrl/v2/localizaciones-{tipo}-clientes	Alta de localización (tipo: cobro/envio/factura/servicio)
freematica_update_localizacion_cliente	PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg}	Actualización parcial de localización (fetch+merge)

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

Modo	Cuándo usar	Comando
stdio	Claude Desktop, Claude Code, ejecución local	mcp-freematica (default) o mcp-freematica --transport=stdio
http	Nubiia, deploy como servicio web	mcp-freematica --transport=http o MCP_TRANSPORT=http mcp-freematica

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.

catalog	Endpoint Freemática	Contenido
Tipos / clasificaciones
tipos-contrato	GET /ppre/v2/tipos-contrato	Tipos de contrato comercial
tipo-instalacion	GET /ppre/v1/tipo-instalacion	Tipos de instalación física
clases-servicios	GET /pvss/v1/clases-servicios	Clases de servicio operativas
tipos-casos	GET /pcrm/v2/tipos-casos	Tipos de caso CRM
subtipos-casos	GET /pcrm/v2/subtipos-casos	Subtipos de caso CRM
tipos-oportunidad-negocio	GET /pcrm/v2/tipos-oportunidad-negocio	Tipos de oportunidad comercial
tipos-impuestos	GET /pgrl/v2/tipos-impuestos	IVA, IRPF, retenciones
naturalezas-abono	GET /pven/v1/naturalezas-abono	Naturalezas de abono comercial
incidencecode	GET /pvss/v2/incidencecode	Códigos de incidencia en servicios
claves-facturacion	GET /pvss/v2/claves-facturacion	Claves de facturación de servicios
Geográficos
paises	GET /pgrl/v1/paises	Países
nacionalidades	GET /pgrl/v1/nacionalidades	Nacionalidades
provincias	GET /pgrl/v1/provincias	Provincias
poblaciones	GET /pgrl/v2/poblaciones	Municipios
Organizativos
empresas	GET /pgrl/v1/empresas	Empresas
delegaciones	GET /pgrl/v1/delegaciones/agrupcod	Delegaciones (listado global)
lineas-negocio	GET /pgrl/v2/lineas-negocio	Líneas de negocio
cargos-clientes	GET /pgrl/v2/cargos-clientes	Cargos de contactos
calendarios	GET /pgrl/v1/calendarios	Calendarios laborales
series	GET /pgrl/v2/series	Series de numeración de documentos
Inventario
familias	GET /part/v1/familias	Familias de artículos
subfamilias	GET /part/v1/subfamilias	Subfamilias
lineas	GET /part/v1/lineas	Líneas de artículos
Financiero
bancos	GET /pgrl/v2/bancos	Entidades bancarias

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

Variable	Descripción
FREEMATICA_AUTH_TOKEN	Header x-auth-token para autenticar con la API de Freemática.
FREEMATICA_AUTH_COMPANY	Header x-auth-company. Identifica la empresa dentro del API.
FREEMATICA_AUTH_ORGANIZATION	Header x-auth-organization. Identifica la organización.
FREEMATICA_AUTH_APP	Header x-auth-app. Identifica la aplicación que consume (p.ej. pvss).
FREEMATICA_AUTH_SESSION	Header x-auth-session. Identifica la sesión activa.

Configuración avanzada

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

Variable	Default	Descripción
FREEMATICA_BASE_URL	https://api-p01.clientservicepanel.com/restsat/api	Base URL del API de Freemática. Cambiar solo si Freemática cambia el host o se usa un entorno alternativo.
FREEMATICA_TIMEOUT_MS	30000	Timeout por petición en milisegundos. Si el upstream no responde en este tiempo, el request se cancela con network_error.
FREEMATICA_MAX_RETRIES	3	Número máximo de reintentos para errores 5xx y errores de red. Los errores 4xx nunca se reintentan.
FREEMATICA_CIRCUIT_BREAKER_THRESHOLD	5	Número de operaciones lógicas fallidas consecutivas (post-retry-exhaustion) necesarias para abrir el circuit breaker.
FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS	30000	Tiempo en ms que el circuit breaker permanece abierto antes de pasar a half-open.
FREEMATICA_MAX_RESPONSE_SIZE_MB	10	Tamaño máximo de respuesta aceptada del upstream en MB. Respuestas mayores se truncan con aviso en el campo truncated.
FREEMATICA_ENABLE_WRITES	false	Registra las tools de escritura (freematica_create_* / freematica_update_*). Sin ella el servidor es de solo lectura. Valores: true/false/1/0.
MCP_TRANSPORT	stdio	Transporte: stdio (para Claude Desktop/Code) o http (para Nubiia). Equivale al flag --transport=.
MCP_PORT	3000	Puerto TCP donde el servidor MCP expone /mcp y /health. Ignorado en modo stdio.
MCP_ALLOWED_ORIGINS	*	CORS: lista de orígenes permitidos separados por coma, o * para todos. En producción restringir al dominio de Nubiia. Ignorado en modo stdio.
LOG_LEVEL	info	Nivel de log para pino: fatal, error, warn, info, debug, trace. En producción usar info. En desarrollo usar debug.

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

Método	Path	Descripción
POST	/mcp	JSON-RPC del MCP (envía initialize la primera vez)
GET	/mcp	Stream SSE (requiere Mcp-Session-Id)
DELETE	/mcp	Terminar sesión
GET	/health	Healthcheck

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.