mcp-freematica

mcp-freematica

MCP 服务，用于公开 Freemática REST API 的操作（ERP：开票、应收账款、供应商、会计、人员），供 Claude 等 AI 助手使用。

由 Nubiia 构建和维护——为企业提供 AI 自动化与集成服务（MCP、Holded、Pipedrive 等）。想为你的企业打造类似的服务？欢迎访问 nubiia.es 联系我们。

技术栈

• TypeScript + Node.js ≥20
• @modelcontextprotocol/sdk（stdio + Streamable HTTP 传输）
• Express + axios + zod
• pino（结构化日志）
• Vitest + nock（用于测试）

已公开的工具

工具	Freemática 端点	描述
freematica_list_articulos	GET /part/v1/articulos	物品／材料／耗材目录（参考信息、类别、供应商）
freematica_get_articulo	GET /part/v1/articulos/{idreg}	物品详情
freematica_get_precio_articulo	GET /pgrl/v1/precio-articulo/{idreg}	物品售价（PRECIO_VENTA、DESCUENTO、FACTURABLE）
freematica_list_materiales_asignados_servicios	GET /pvss/v2/contratos-servicios-material	服务分配的材料列表
freematica_get_master_data	（根据 catalog 提供 24 个端点）	返回主数据目录（类型、地理、组织、库存、财务）
freematica_list_clientes	GET /pgrl/v2/clientes	分页客户列表
freematica_get_cliente	GET /pgrl/v2/clientes/{idReg}	客户详情
freematica_list_contactos_clientes	GET /pgrl/v2/contactos-clientes	分页联系人列表
freematica_list_oportunidades_negocio	GET /pcrm/v2/oportunidades-negocio	分页商机列表
freematica_get_oportunidad_negocio	GET /pcrm/v2/oportunidades-negocio/{idReg}	商机详情
freematica_get_oportunidad_negocio_datos_ampliados	GET /pcrm/v2/oportunidades-negocio/{idReg}/datos-ampliados	扩展数据（可能返回 404）
freematica_get_ficha_prev_cliente	GET /pprl/v2/ficha-prev-cliente	客户的 PRL 档案
freematica_list_vigilancia_salud	GET /pprl/v1/vigilancia-salud	健康监测记录分页列表
freematica_get_vigilancia_salud	GET /pprl/v1/vigilancia-salud/{idreg}	健康监测记录详情
freematica_list_personal	GET /pers/v1/personal	人员分页列表（人力资源）
freematica_get_persona	GET /pers/v2/personal/{idreg}	人员详情
freematica_list_calendarios	GET /pgrl/v1/calendarios	工作日历分页列表
freematica_list_calendario_periodos	GET /pgrl/v1/calendarios/{idreg}/periodos	工作日历的时段
freematica_list_cartera_clientes	GET /pcar/v1/cartera-clientes	客户应收账款分页列表（收款、逾期未付款项）
freematica_get_cartera_cliente	GET /pcar/v1/cartera-clientes/{idReg}	应收账款单据详情
freematica_list_facturas_cabecera	GET /pven/v1/facturas-cabecera	销售发票分页列表（抬头）
freematica_get_factura_cabecera	GET /pven/v1/facturas-cabecera/{idReg}	销售发票详情
freematica_list_factura_lineas	GET /pven/v1/facturas-cabecera/{idReg}/lineas	销售发票明细行
freematica_list_factura_iva	GET /pven/v1/facturas-cabecera/{idReg}/iva	销售发票的增值税行
freematica_list_factura_vencimientos	GET /pven/v1/facturas-cabecera/{idReg}/vencimientos	销售发票的收款到期日
freematica_list_facturas_compras	GET /pcom/v1/facturas-cabecera	采购发票分页列表
freematica_get_factura_compra	GET /pcom/v1/facturas-cabecera/{idReg}	采购发票详情
freematica_list_proveedores	GET /pgrl/v2/proveedores	供应商分页列表
freematica_get_proveedor	GET /pgrl/v2/proveedores/{idReg}	供应商详情
freematica_list_localizaciones_cobro_clientes	GET /pgrl/v2/localizaciones-cobro-clientes	客户收款地点（SEPA、银行自动扣款）
freematica_list_localizaciones_pago_proveedores	GET /pgrl/v2/localizaciones-pago-proveedores	供应商付款地点
freematica_list_localizaciones_servicio_clientes	GET /pgrl/v2/localizaciones-servicio-clientes	客户服务地点
freematica_list_cuentas_contables	GET /pcon/v2/cuentas	会计科目表（COD_CTA、COD_PLAN 等）
freematica_list_cuentas_analiticas	GET /pcon/v2/cuentas-analiticas	分析科目目录
freematica_export_asientos	GET /pcon/v2/asientos	导出某个期间的会计分录（CSV/JSON）
freematica_list_pedidos_compra	GET /pcmp/v2/pedidos	采购订单分页列表（原生筛选器 + FIQL + 枚举状态）
freematica_get_pedido_compra	GET /pcmp/v2/pedidos/{idReg}	采购订单详情（抬头 + 供应商 + 行项目）
freematica_list_albaranes_ventas	GET /pven/v2/albaranes-ventas	销售交货单分页列表（所有筛选器均为原生筛选器，必填公司）
freematica_get_albaran_venta	GET /pven/v2/albaranes-ventas/{idReg}	销售交货单详情
freematica_list_albaranes_factura	GET /pven/v2/albaranes-facturas	交货单↔发票关联分页列表（原生 idReg + FIQL）
freematica_get_albaran_factura	GET /pven/v2/albaranes-facturas/{idReg}	交货单与发票关联详情
freematica_list_resultados_facturacion	GET /pvss/v1/facturacion-resultados	自动健康监测计费批处理的结果（FIQL）
freematica_list_contratos	GET /pvss/v1/contratos	合同抬头分页列表（仅支持原生筛选器：API 在此处忽略 FIQL）
freematica_get_contrato	GET /pvss/v1/contratos (scan)	按公司 + 自然代码搜索合同（内部分页 + 客户端筛选）
freematica_list_servicios_contrato	GET /pvss/v1/contratos/{idReg}/servicios	合同服务列表
freematica_get_servicio_contrato	GET /pvss/v2/contratos-servicios/{idReg}	合同服务详情
freematica_list_contratos_opcionales	GET /ppre/v2/contratos/opcionales	合同可选项分页列表
freematica_get_contrato_opcionales	GET /ppre/v2/contratos/opcionales/{idReg}	可选项记录详情
freematica_list_localizaciones_envio_clientes	GET /pgrl/v2/localizaciones-envio-clientes	客户发货地点
freematica_list_localizaciones_factura_clientes	GET /pgrl/v2/localizaciones-factura-clientes	客户发票地点

写入工具（需要设置 FREEMATICA_ENABLE_WRITES=true）

默认情况下，服务为只读。设置 FREEMATICA_ENABLE_WRITES=true 后，还会注册以下创建和更新工具。**没有删除工具。**所有写入操作都会记录审计日志（info 级别记录操作、端点和字段；debug 级别记录完整请求正文）。

工具	Freemática 端点	描述
freematica_create_contrato	POST /pvss/v2/contratos	新增合同主记录
freematica_update_contrato	PUT /pvss/v2/contratos/{idReg}	更新合同主记录
freematica_create_servicio_contrato	POST /pvss/v2/contratos/{idReg}/servicios	新增服务（标识从 idReg 推导）
freematica_update_servicio_fechas	PUT /pvss/v2/contratos/{id}/servicio/{id}	服务的开始/结束日期（停用机制）
freematica_create_servicio_historico_precios	POST /pvss/v2/contratos/{id}/servicios-historico-precios/{id}	新增服务价格修订
freematica_update_servicio_historico_precios	PUT /pvss/v2/contratos/{id}/servicios-historico-precios/{id}	更新价格修订
freematica_create_servicio_facturacion_txt	POST /pvss/v2/contratos/{id}/servicios-facturacion-txt/{id}	新增账单文本行
freematica_update_servicio_facturacion	PUT /pvss/v2/contratos/{id}/servicios-facturacion/{id}	服务的账单数据（小时价格、付款方式……）
freematica_create_contrato_opcionales	POST /ppre/v2/contratos/opcionales	新增合同可选项
freematica_update_contrato_opcionales	PUT /ppre/v2/contratos/opcionales/{idReg}	更新合同可选项
freematica_create_cliente	POST /pgrl/v2/clientes	新增客户（idReg 从组别和代码推导）
freematica_update_cliente	PUT /pgrl/v2/clientes/{idReg}	部分更新客户（获取后合并）
freematica_create_contacto_cliente	POST /pgrl/v2/contactos-clientes	新增客户联系人
freematica_update_contacto_cliente	PUT /pgrl/v2/contactos-clientes/{idReg}	部分更新联系人（获取后合并）
freematica_create_localizacion_cliente	POST /pgrl/v2/localizaciones-{tipo}-clientes	新增地址（类型：收款/寄送/账单/服务）
freematica_update_localizacion_cliente	PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg}	部分更新地址（获取后合并）

类型化筛选器（内部使用 FIQL）

MCP 会向使用方（Claude/LLM）公开由 zod 定义的类型化参数。内部客户端会在调用 Freemática API 前将这些参数转换为 FIQL 语法。使用方不会看到或编写 FIQL。

示例

// 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'

该模式的优势

• LLM 只需了解用西班牙语命名的语义化类型参数。
• FIQL 语法的复杂性由内部 adapter（src/clients/fiql-builder.ts）封装。
• 验证错误清晰明了：“empresa 必须是 string”，而不是“FIQL 解析错误”。
• 布尔筛选条件（soloImpagados: true）会自动转换为正确的 FIQL 运算符。

更多示例

// 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.'

传输模式

该二进制文件支持两种可选传输方式。选择优先级如下：

1. CLI 标志：--transport=<modo>
2. 环境变量：MCP_TRANSPORT=<modo>
3. 默认值：stdio

模式	使用场景	命令
stdio	Claude Desktop、Claude Code、本地运行	mcp-freematica（默认）或 mcp-freematica --transport=stdio
http	Nubiia、部署为 Web 服务	mcp-freematica --transport=http 或 MCP_TRANSPORT=http mcp-freematica

在 Claude Desktop 中配置（stdio）

编辑 ~/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": "..."
      }
    }
  }
}

重启 Claude Desktop，即可使用 freematica_* 工具。

在 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=...

在 Nubiia 中配置（HTTP）

在进程的环境变量中设置 MCP_TRANSPORT=http，并同时设置 5 个 FREEMATICA_AUTH_* 变量。其余变量（端口、origins）为可选项——请参阅“高级配置”中的表格。

可用的主数据

工具 freematica_get_master_data 接受参数 catalog，可填写以下 24 个值之一。每个值都映射到 Freemática 的一个特定 endpoint。

catalog	Freemática endpoint	内容
类型 / 分类
tipos-contrato	GET /ppre/v2/tipos-contrato	商业合同类型
tipo-instalacion	GET /ppre/v1/tipo-instalacion	实体设施类型
clases-servicios	GET /pvss/v1/clases-servicios	运营服务类别
tipos-casos	GET /pcrm/v2/tipos-casos	CRM 案例类型
subtipos-casos	GET /pcrm/v2/subtipos-casos	CRM 案例子类型
tipos-oportunidad-negocio	GET /pcrm/v2/tipos-oportunidad-negocio	商业机会类型
tipos-impuestos	GET /pgrl/v2/tipos-impuestos	IVA、IRPF、预扣税
naturalezas-abono	GET /pven/v1/naturalezas-abono	商业贷项性质
incidencecode	GET /pvss/v2/incidencecode	服务事件代码
claves-facturacion	GET /pvss/v2/claves-facturacion	服务计费代码
地理信息
paises	GET /pgrl/v1/paises	国家
nacionalidades	GET /pgrl/v1/nacionalidades	国籍
provincias	GET /pgrl/v1/provincias	省
poblaciones	GET /pgrl/v2/poblaciones	市镇
组织信息
empresas	GET /pgrl/v1/empresas	企业
delegaciones	GET /pgrl/v1/delegaciones/agrupcod	分支机构（全局列表）
lineas-negocio	GET /pgrl/v2/lineas-negocio	业务线
cargos-clientes	GET /pgrl/v2/cargos-clientes	联系人职务
calendarios	GET /pgrl/v1/calendarios	工作日历
series	GET /pgrl/v2/series	单据编号系列
库存
familias	GET /part/v1/familias	商品族
subfamilias	GET /part/v1/subfamilias	子族
lineas	GET /part/v1/lineas	商品线
财务
bancos	GET /pgrl/v2/bancos	银行机构

响应：{ catalog, items, count, total }。典型用法：当其他工具返回晦涩难懂的 ID 时，先调用对应目录，将其解析为易于理解的名称。

分页

所有 freematica_list_* 工具都接受两个可选参数：

• page（int，≥1，默认值为 1）：要获取的页码，从 1 开始计数。
• items（int，1..50，默认值为 20）：每页的条目数。

响应始终包含 total（数据集中的元素总数），供 LLM 遍历各页。

将参数限制为 page >= 1，是因为 Freemática 的实际 API 会将 page=0 视为“返回整个数据集”（在 clientes 等大型端点中会产生数 MB 的数据）。此行为已通过实际测试验证。

详情端点中的不透明 ID

freematica_get_* 工具需要的 id 不是自然代码（COD_CLI、ID_OPORTUNIDAD），而是对应列表条目中出现的 **idReg** 字段。它是一个不透明的 Base64 字符串，例如 MV9fMTAwMA==`。

如果传入自然代码，API 会返回 not_found。

LLM 的典型使用方式：

1. freematica_list_clientes(page=1, items=20) → 找到需要的客户。
2. 获取该条目的 idReg 字段。
3. freematica_get_cliente(id="<idReg>") → 获取完整详情。

配置

服务会在启动时读取所有环境变量中的配置。如果缺少任何必需项，进程就会终止，并清楚地列出缺失项；在配置有效之前，它不会接受请求。

必需的环境变量

变量	描述
FREEMATICA_AUTH_TOKEN	用于向 Freemática API 进行身份验证的 x-auth-token 标头。
FREEMATICA_AUTH_COMPANY	x-auth-company 标头。用于标识 API 中的公司。
FREEMATICA_AUTH_ORGANIZATION	x-auth-organization 标头。用于标识组织。
FREEMATICA_AUTH_APP	x-auth-app 标头。用于标识使用该 API 的应用（例如 pvss）。
FREEMATICA_AUTH_SESSION	x-auth-session 标头。用于标识当前会话。

高级配置

用于调整生产环境行为的可选环境变量：

变量	默认值	说明
FREEMATICA_BASE_URL	https://api-p01.clientservicepanel.com/restsat/api	Freemática API 的基础 URL。仅在 Freemática 更改主机或使用备用环境时修改。
FREEMATICA_TIMEOUT_MS	30000	每个请求的超时时间，单位为毫秒。如果上游在此时间内未响应，请求将以 network_error 取消。
FREEMATICA_MAX_RETRIES	3	针对 5xx 错误和网络错误的最大重试次数。4xx 错误不会重试。
FREEMATICA_CIRCUIT_BREAKER_THRESHOLD	5	打开熔断器所需的连续失败逻辑操作次数（重试耗尽后）。
FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS	30000	熔断器保持打开状态后转为半开状态前的时间，单位为毫秒。
FREEMATICA_MAX_RESPONSE_SIZE_MB	10	上游响应可接受的最大大小，单位为 MB。超出大小的响应将被截断，并在 truncated 字段中给出提示。
FREEMATICA_ENABLE_WRITES	false	注册写入工具（freematica_create_* / freematica_update_*）。未启用时，服务为只读。取值：true/false/1/0。
MCP_TRANSPORT	stdio	传输方式：stdio（用于 Claude Desktop/Code）或 http（用于 Nubiia）。等同于 --transport= 标志。
MCP_PORT	3000	MCP 服务公开 /mcp 和 /health 的 TCP 端口。在 stdio 模式下忽略。
MCP_ALLOWED_ORIGINS	*	CORS：以逗号分隔的允许来源列表，或使用 * 表示全部来源。生产环境中应限制为 Nubiia 的域名。在 stdio 模式下忽略。
LOG_LEVEL	info	pino 的日志级别：fatal、error、warn、info、debug、trace。生产环境使用 info。开发环境使用 debug。

x-auth-* 凭据的来源

这 5 个 x-auth-* 凭据是预先存在的——Freemática 的 Postman collection 未提供登录端点，因此需要通过带外方式获取这些凭据（通常由 Freemática 的 IT 部门或你的集成商提供）。

• 向 Freemática 的技术负责人索取这 5 个值（如果已配置，也可以从你的密钥管理器中获取）。
• 切勿提交真实凭据。仓库已在 .gitignore 中忽略 .env.*（.env.example 除外）。
• 如果凭据过期，MCP 会在所有调用中返回 invalid_token。续期后需要重启进程（不会自动刷新）。

在 Nubiia 中配置（生产环境）

Nubiia 会部署 MCP 服务并负责注入环境变量。在 Nubiia 控制面板中：

1. 创建一个 MCP 服务，并将其指向已部署容器的 URL（例如 https://freematica-mcp.example.com/mcp）。
2. 在密钥部分添加上方列出的环境变量。
3. 建议将 MCP_ALLOWED_ORIGINS 设置为 Claude/Nubiia 连接所用的确切域名，而不是 *。
4. 在 Claude 中启用 MCP 之前，使用端点 GET /health 验证服务是否正常运行。

本地配置（开发环境）

在本地开发时，请在根目录创建 .env（或 .env.local）：

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

然后启动：

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

也可以合并为一行：

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

配置验证

1. 未设置环境变量——进程应立即退出，并显示缺失的 5 个变量：

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

2. 环境变量有效（HTTP 模式）——使用 MCP_TRANSPORT=http 启动后，进程会开始监听；/health 返回 { "status": "ok", "version": "0.5.0", "sessions": 0 }：

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

   在 stdio 模式（默认）下没有 HTTP 端点——服务通过 stdin/stdout 监听 JSON-RPC。

故障排查

所有调用均返回 invalid_token

x-auth-* 凭据已过期或不正确。处理步骤：

1. 检查 5 个 FREEMATICA_AUTH_* 变量是否均已正确设置。
2. 联系 Freemática 的技术负责人续期令牌/会话。
3. 更新变量后重启 MCP 进程（客户端不会热刷新凭据）。

network_error——Freemática 上游服务不可用

Freemática API 无响应。可能原因：

• 上游正在进行计划内维护。
• 连续发生多次故障后，断路器已触发（查看日志：Circuit breaker opened）。
• 服务与 api-p01.clientservicepanel.com 之间存在网络问题。

处理步骤：

1. 检查日志中是否有 circuitBreaker: "open"——如果有，请等待 FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS 毫秒（默认 30s），使其进入半开状态。
2. 检查与上游的连通性：curl https://api-p01.clientservicepanel.com/。
3. 如果上游响应缓慢，请增大 FREEMATICA_TIMEOUT_MS（默认 30s 在某些网络中可能不够）。

rate_limit_exceeded——Freemática 限流

Freemática 返回 429。MCP 会在存在 Retry-After 标头时遵循其值并自动重试。如果问题仍然存在：

1. 降低从 Claude 发出的调用频率。
2. 如果重试次数不够，请增大 FREEMATICA_MAX_RETRIES（默认 3）。
3. 联系 Freemática，了解分配给账户的速率限制。

freematica_export_asientos 中出现 Response truncated

导出分录的端点在日期范围较大时会返回过多记录。处理步骤：

1. 使用更短的日期范围：不要按季度导出，而是逐月导出。
2. 添加其他筛选条件：按公司、分支机构或特定账户筛选。
3. 如果预期数据量较大且属于设计需求，请增大 FREEMATICA_MAX_RESPONSE_SIZE_MB（默认 10 MB）。

执行 git commit 时 pre-commit hook 失败

Lint 或格式检查在暂存文件中检测到错误。请按以下步骤操作：

1. 查看 hook 的输出：其中会指出出错的文件和规则。
2. 运行 npm run lint:fix 和 npm run format，自动修复问题。
3. 重新尝试提交前，对修复后的文件执行 git add。

开发

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

测试

单元测试与集成测试

# 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

测试位于 tests/，按类型组织：

• tests/clients/ — HTTP 客户端测试（使用 nock）
• tests/schemas/ — Zod schemas 测试
• tests/tools/ — MCP 处理器测试（单元测试 + 集成测试）
• tests/fiql-builder.*.test.ts — FIQL builder 的单元测试和基于属性的测试
• tests/pagination-edge-cases.test.ts — 分页适配器的边缘情况
• tests/coverage-gaps.test.ts — 针对未覆盖分支的专项覆盖测试

覆盖率阈值（在 vitest.config.ts 中配置）：

• 全局语句：≥85%
• src/clients/：≥90%
• src/schemas/：≥90%
• src/tools/：≥85%

使用 MCP Inspector 进行手动测试

如需交互式测试 MCP 服务，请使用 MCP Inspector。

详细说明请参阅 docs/testing-e2e.md。

HTTP 端点

方法	Path	描述
POST	/mcp	MCP 的 JSON-RPC（首次发送 initialize）
GET	/mcp	SSE 流（需要 Mcp-Session-Id）
DELETE	/mcp	结束会话
GET	/health	健康检查

安全

重要

/mcp 端点不会对客户端进行身份验证。 任何能够访问网络端口的人都可以使用服务配置的 Freemática 凭据调用工具，这些凭据存储在环境变量中。由于所有工具都为只读，这相当于可以读取公司的数据（投资组合、开票信息、客户、员工……）。

因此，以 HTTP 模式部署时：

• 绝不要将端口直接暴露到互联网。 始终将服务部署在负责对客户端进行身份验证和授权的网关 / 反向代理之后（Nubiia 就采用这种模式）。
• 将 MCP_ALLOWED_ORIGINS 限制为连接来源的确切域名，而不是使用默认值 *。如果使用 * 启动，服务会在日志中发出 warning。请注意，CORS 只能防范浏览器，无法防范 curl 之类的客户端。
• 将 5 个 FREEMATICA_AUTH_* 凭据视为机密信息。 通过机密管理器注入，绝不要将它们放入仓库（.env* 已列入 .gitignore）。

服务已包含以下安全最佳实践：

• 从所有日志（包括 debug/trace）中删除 x-auth-* 标头，且绝不记录请求正文。
• 在 /mcp 和 /health 上进行速率限制（每个 IP 每分钟 120 个请求）、请求正文大小限制为 1 MB，并自动使不活跃会话过期。
• 对 FIQL 筛选器的值进行转义，以防止查询运算符注入。

如何添加新操作

1. 为响应添加类型定义，位置为 src/types/<grupo>.ts。
2. 在 FreematicaClient 中添加方法（src/clients/freematica-client.ts）：

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

3. 在 src/tools/<grupo>.ts 中添加 server.tool(...)（如果该组是新的，则创建文件）。
4. 如果该组是新的： 在 src/server.ts 中注册 register<Grupo>Tools(server, client)。
5. 测试： 一个客户端方法测试（使用 nock）+ 一个工具处理器测试。

此模式参考了 mcp-nevent 和 mcp-holded。

部署

此项目旨在 Nubiia 内运行。平台负责部署并注入环境变量。你有 3 种选择：

选项 1 — 安装为 npm 包（推荐）

在 main 上创建 v* 标签时，该包会以 @nubiia/mcp-freematica 的名称发布到 npm 公共 registry。

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

选项 2 — Docker

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

选项 3 — 克隆 + 构建

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

发布新版本

1. 在 package.json 中提升版本号（semver）。
2. 提交 + 合并到 main。
3. 创建并推送带 v 前缀的标签：

   git tag v0.5.0
   git push origin v0.5.0
   

4. 工作流 .github/workflows/publish.yml 随即触发，执行验证（lint + typecheck + test + build）并发布到 npm。

规范与设计

• v0.1.0 规范：docs/superpowers/specs/2026-05-18-freematica-mcp-design.md（初始引导）
• v0.1.0 计划：docs/superpowers/plans/2026-05-18-freematica-mcp.md
• v0.2.0 规范：docs/superpowers/specs/2026-05-19-stdio-transport-design.md（支持 stdio）
• v0.2.0 计划：docs/superpowers/plans/2026-05-19-stdio-transport.md
• v0.3.0 规范：docs/superpowers/specs/2026-05-19-master-data-tool-design.md（主数据工具）
• v0.3.0 计划：docs/superpowers/plans/2026-05-19-master-data-tool.md
• v0.4.0 规范：docs/superpowers/specs/2026-05-20-commercial-tools-design.md（商业工具 + 信封解包修复）
• v0.4.0 计划：docs/superpowers/plans/2026-05-20-commercial-tools.md
• v0.4.1：目录热修复：delegaciones（端点已更改为 /agrupcod）和 tipos-marcajes（已移除 — 端点失效）。请参阅 CHANGELOG。
• 架构 ADR：docs/adr/（请参阅该目录中的索引）
• API：apidocs/Freematica API - Complete Collection.postman_collection.json
• 更新日志：CHANGELOG.md

关于 Nubiia

此 MCP 服务由 Nubiia 构建并维护。

Nubiia 帮助企业借助 AI 自动化流程并集成工具：量身定制的 MCP 服务、与 ERP 和 CRM（Freemática、Holded、Pipedrive……）的集成，以及将业务数据连接到 Claude 等助手的 Agent。这个 @nubiia/mcp-freematica 是我们工作成果的一个开源示例。

👉 想为你的业务集成或自动化 AI？nubiia.es · ✉️ [email protected]

作者

由 Nubiia 构建 — nubiia.es · [email protected]

维护者：Samuel Fraga — GitHub

链接

• Nubiia — AI 自动化与集成
• npm：@nubiia/mcp-freematica
• GitHub：nubiia-dev/mcp-freematica

许可证

MIT — 请参阅 LICENSE。