mcp-freematica

mcp-freematica

Freemática の REST API の操作（ERP：請求、売掛金、仕入先、会計、人事）を公開し、Claude などの AI アシスタントから利用できる MCP サーバーです。

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	売上請求書の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 レベル、完全な body は 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 構文の複雑さは、内部アダプター（src/clients/fiql-builder.ts）にカプセル化されています。
• 検証エラーが明確です。「empresa は文字列である必要があります」と表示され、「FIQL parse error」とは表示されません。
• ブール値のフィルター（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.'

トランスポートモード

バイナリは、選択可能な2つのトランスポートに対応しています。選択の優先順位は次のとおりです。

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_* と併せて指定します。その他の変数（ポート、オリジン）は省略可能です。「詳細設定」の表を参照してください。

利用可能なマスターデータ

freematica_get_master_data ツールは、以下の24個の値のいずれかを指定する catalog パラメーターを受け取ります。それぞれが Freemática の特定のエンドポイントに対応しています。

catalog	Freemática エンドポイント	内容
種類／分類
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_* は、次の2つの省略可能なパラメーターを受け付けます。

• page（int、≥1、デフォルト 1）：取得するページ。1始まりです。
• items（int、1..50、デフォルト 20）：1ページあたりの項目数です。

LLM がページを順に取得できるよう、レスポンスには常にデータセット内の要素数を示す total が含まれます。

実際の Freemática API では page=0 を「データセット全体を返す」として扱うため、このパラメーターは page >= 1 に制限されています（clientes などの大規模なエンドポイントでは数 MB になります）。実測で確認済みです。

詳細エンドポイントの不透明な ID

ツール freematica_get_* では、自然なコード（COD_CLI、ID_OPORTUNIDAD）ではなく、対応する一覧の項目に表示される idReg フィールドを id として指定する必要があります。MV9fMTAwMA== のような、不透明な Base64 文字列です。

自然なコードを渡すと、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 ヘッダー。利用するアプリケーションを識別します（例：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	リクエストごとのタイムアウト時間（ミリ秒）です。upstream がこの時間内に応答しない場合、リクエストは network_error でキャンセルされます。
FREEMATICA_MAX_RETRIES	3	5xx エラーおよびネットワークエラーに対する最大再試行回数です。4xx エラーは再試行されません。
FREEMATICA_CIRCUIT_BREAKER_THRESHOLD	5	サーキットブレーカーを開くために必要な、連続して失敗した論理操作の回数（再試行を使い切った後）です。
FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS	30000	サーキットブレーカーが開いた状態を維持してから half-open に移行するまでの時間（ミリ秒）です。
FREEMATICA_MAX_RESPONSE_SIZE_MB	10	upstream から受け入れるレスポンスの最大サイズ（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 コレクションにはログインエンドポイントが公開されていないため、これらの認証情報は別途入手します（通常は Freemática の IT 部門またはインテグレーターから取得します）。

• Freemática の技術担当者に5つの値を依頼してください（すでにプロビジョニングされている場合は、シークレット管理ツールから取得してください）。
• 実際の認証情報をコミットしないでください。リポジトリでは .env.* が .gitignore に含まれています（.env.example を除く）。
• 認証情報の有効期限が切れると、MCP はすべての呼び出しに対して invalid_token を返します。更新するにはプロセスを再起動する必要があります（自動更新には対応していません）。

Nubiia での設定（本番環境）

Nubiia は MCP サーバーをデプロイし、環境変数を注入します。Nubiia のパネルで次の操作を行います。

1. デプロイしたコンテナの URL（例：https://freematica-mcp.example.com/mcp）を指定して、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

または、すべてを1行で実行します。

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 ミリ秒（デフォルトは30秒）待つと、half-open 状態に移行します。
2. アップストリームへの接続を確認します：curl https://api-p01.clientservicepanel.com/。
3. アップストリームの応答が遅い場合は、FREEMATICA_TIMEOUT_MS を増やします（デフォルトの30秒では、一部のネットワークで不十分な場合があります）。

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 フックが失敗する

Lint またはフォーマットのチェックで、ステージングされたファイルにエラーが検出されました。以下の手順に従ってください。

1. フックの出力を確認します。どのファイルでどのルールに違反したかが表示されます。
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 スキーマのテスト
• tests/tools/ — MCP ハンドラーのテスト（単体＋統合）
• tests/fiql-builder.*.test.ts — FIQL builder の単体テストとプロパティベーステスト
• tests/pagination-edge-cases.test.ts — ページネーションアダプターのエッジケース
• tests/coverage-gaps.test.ts — カバレッジされていない分岐に特化したテスト

カバレッジのしきい値（vitest.config.ts で設定）：

• 全体の statements：≥85%
• src/clients/：≥90%
• src/schemas/：≥90%
• src/tools/：≥85%

MCP Inspector を使った手動テスト

MCP サーバーを対話的にテストするには、MCP Inspector を使用します。

詳しい手順については、docs/testing-e2e.md を参照してください。

HTTP エンドポイント

メソッド	パス	説明
POST	/mcp	MCP の JSON-RPC（初回に initialize を送信）
GET	/mcp	SSE ストリーム（Mcp-Session-Id が必要）
DELETE	/mcp	セッションを終了
GET	/health	ヘルスチェック

セキュリティ

重要

/mcp エンドポイントではクライアントを認証しません。 ポートにネットワーク経由でアクセスできるユーザーは誰でも、サーバーの環境変数に設定された Freemática の認証情報を使ってツールを呼び出せます。すべてのツールは読み取り専用であるため、これは会社のデータ（ポートフォリオ、請求、顧客、人員など）への読み取りアクセスに相当します。

そのため、HTTP モードでデプロイする場合は、以下の点に注意してください。

• ポートをインターネットに直接公開しないでください。 必ずクライアントの認証と認可を行うゲートウェイ／リバースプロキシの背後にデプロイしてください（Nubiia はこの方式で運用されています）。
• MCP_ALLOWED_ORIGINS はデフォルト値の * ではなく、接続元の正確なドメインに制限してください。 * を指定して起動すると、サーバーはログに警告を出力します。CORS が保護するのはブラウザーだけであり、curl などのクライアントは保護しない点に注意してください。
• 5 つの FREEMATICA_AUTH_* 認証情報を秘密情報として扱ってください。 シークレット管理ツールを通じて注入し、リポジトリには決して保存しないでください（.env* は .gitignore に含まれています）。

サーバーには、以下のベストプラクティスがすでに組み込まれています。

• x-auth-* ヘッダーはすべてのログ（debug／trace を含む）から除外され、リクエストボディはログに記録されません。
• /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* タグを作成すると、パッケージは npm のパブリックレジストリに @nubiia/mcp-freematica として公開されます。

# 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 などのアシスタントをつなぐエージェントを提供しています。この @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 を参照してください。