siigo-pyme-mcp

siigo-pyme-mcp

SIIGO PymeをAIエージェントに公開するMCPサーバーです。 SIIGO のインターフェース実行ファイルであるEXCELSIIGO.exeをラップし、エクスポートとインポートを行う47 個の関数を、ドキュメント化されたパラメーター、自動的な会社の検出、JSON に解析済みの結果を備えた MCP ツールに変換します。

Agente: "dame los terceros de la empresa 02"
  → siigo_run_function(funcion: "GETTER", empresa: "02")
  → EXCELSIIGO.exe Z:\SIIWI02\ 2026 GETTER L USUARIO **** ... Terceros.xlsx
  → { ok: true, archivo: "...", totalFilas: 1240, columnas: [...], filas: [...] }

自己診断機能を備えており、npx -y siigo-pyme-mcp --doctorを実行すると、PC で SIIGO を実行できるか、不足しているものは何かがわかります。また、--print-configを実行すると、MCP クライアント用の正確な設定ブロックが出力されます。どちらも何も登録する前に利用できます。

要件

要件	理由
Windows	SIIGO Pyme は Windows 専用です。
SIIGO Pyme のインストール	EXCELSIIGO.exeが必要です（デフォルトではC:\Siigoにあります）。
Microsoft Excel のインストール	SIIGO はSiigoExcel.exeを介して COM 経由で Excel を使用し、.xlsxファイルを生成します。Excel がなければファイルは生成されません。
アクティブなデスクトップセッション	上記に伴い、Windows サービスとしては動作せず、セッションのない SSH 経由やコンテナ内でも動作しません。実行するたびに、SIIGO と Excel の進行状況ウィンドウが表示されます。非表示にはできません。ウィンドウを非表示にすると、プロセスは何も生成せずに停止します。
Node.js 18 以降	npxで実行するために必要です。

インストール

インストールは不要です。npxで実行できます。4 つの手順があり、パッケージが各手順を案内します。

npx -y siigo-pyme-mcp --doctor                            # 1. ¿puede este equipo ejecutar SIIGO?
npx -y siigo-pyme-mcp --print-config --cliente hermes     # 2. el bloque exacto a pegar
npx -y siigo-pyme-mcp --print-agent-rules --cliente hermes  # 3. que el agente sepa usarlo
# 4. reinicie el cliente MCP y repita --doctor

--print-configはhermes、Claude Desktop、Claude Code、VS Code、Cursor に対応しており、リストにないクライアント向けにプロトコルの基本情報も出力します。--clienteを指定しない場合は、すべて表示されます。汎用的なケースでは、次のようにします。

{
  "mcpServers": {
    "siigo": {
      "command": "npx",
      "args": ["-y", "siigo-pyme-mcp"],
      "env": {
        "SIIGO_USUARIO": "TU_USUARIO",
        "SIIGO_CLAVE": "TU_CLAVE"
      }
    }
  }
}

-yは省略できません。これを指定しないと、npx がコンソールで確認を求めて待機し、その無応答状態を MCP クライアントがサーバーの起動失敗と判断します。

インストールに失敗した場合

症状	実際の原因
npm error EBADPLATFORM ... wanted {"os":"win32"}	Windows 以外（WSL、コンテナ、Linux）でインストールしています。SIIGO がある Windows マシンに登録する必要があります。--forceを使っても解決しません。SIIGO も Excel もなければ、実行できるものがないためです。
クライアントに詳細なしでサーバーの起動失敗と表示される	npx に-yがありません。
'npx' no se reconoce como un comandoと表示される、または起動時にENOENTが発生する	MCP クライアントの PATH にnpxがありません。実際のマシン上のパスを使って、node.exeとインストール済みのdist/index.jsを指定するブロックを出力する--print-config --absolutoを使用してください。
起動するが、どの関数もファイルを生成せずに失敗する	Excel がない、デスクトップセッションがない、またはいずれかのパスが 50 文字を超えています。--doctorを実行してください。

hermes には手動で設定を記述すると問題になる点があります。config.yamlでは、argsとenvは YAML のリストやマップではなく、YAML 内の JSON 文字列です。--print-config --cliente hermesは、すでにこの形式で出力します。

エージェントが使い方を知らない場合

サーバーを登録するだけでは、エージェントはその使い方を理解できません。「使い方」はMCPプロトコルの3つのチャネルに含まれていますが、すべてのクライアントが読み取るわけではありません。

1. InitializeResult の instructions — 接続時にこのサーバーが送信するテキストです。
2. リソース（siigo://guia/inicio、siigo://protocolo）とプロンプト siigo_puesta_en_marcha。
3. ツール名と説明 — これがなければツールを呼び出せないため、すべての MCP クライアントが利用する唯一のチャネルです。

たとえば hermes では、チャネル1が完全に失われます。InitializeResult は capabilities を読むためだけに取得され、.instructions は読み取られません（tools/mcp_tool.py の self.initialize_result の横にあるコメントを参照してください）。チャネル2のリソースとプロンプトはオプトイン方式で、エージェントが自発的に参照することはありません。チャネル3だけが残るため、このサーバーではそれを最大限に活用します。

• siigo_start_here は tools/list の最初のツールで、タイトルは「最初に読む」です。使用プロトコル全体を返します。
• エージェントがこれを呼び出さない場合、プロセス内でほかの siigo_* ツールを呼び出した際の最初の応答に、プロトコルが内容の末尾に一度だけ追加されます。
• npx -y siigo-pyme-mcp --print-agent-rules --cliente <su cliente> は、クライアントのルール形式で同じプロトコルを出力します（hermes と Claude Code にはフロントマター付きのスキル、AGENTS.md に貼り付けるブロック、その他にはプロジェクトの指示）。これにより、最初の呼び出しより前にプロトコルが届きます。--instalar を指定すると、クライアントのスキルフォルダーに直接書き込みます（例：%LOCALAPPDATA%\hermes\skills\siigo-pyme-mcp\SKILL.md）。--forzar を追加しない限り、既存のファイルの内容が異なる場合は上書きしません。

はじめに

1. siigo_doctor — 環境を確認し、不足しているものを示します。問題が起きたときは、まずこれを呼び出してください。
2. siigo_list_companies — 利用可能な企業 SIIWI01..SIIWI99 を一覧表示します。
3. siigo_set_credentials — ユーザー名とパスワードを保存します。企業を指定しない場合、認証情報はすべての企業に適用されます。同じユーザーをすべての企業で使う場合に便利です。
4. siigo_describe_function — 使用する関数の正確なパラメーターを確認します。
5. siigo_run_function — 関数を実行します。

siigo_set_credentials(usuario: "TU_USUARIO", clave: "TU_CLAVE")
siigo_set_company_alias(empresa: "Z:\\SIIWI01\\", alias: "Inmunotek")
siigo_describe_function(funcion: "GETMOV")
siigo_run_function(funcion: "GETMOV", empresa: "Inmunotek",
                   params: { fechaInicial: "0101", fechaFinal: "0131", tipoComprobante: "F" })

手順4は形式的なものではありません。CLI は形式が誤ったパラメーターを受け付け、それを 081 として記録し、終了コード0で終了するため、パラメーターエラーが成功したように見えます。誤ったデータを返す可能性があるのは、このサーバーではこの場合だけです。

企業の検出方法

• インストール：Windows レジストリ（HKLM\SOFTWARE\WOW6432Node\Informatica y Gestion S.A\Siigo Windows）、サーバーの設定、および EXCELSIIGO.exe を含む <X>:\Siigo* フォルダーを探すドライブのスキャンから検出します。複数のインストールが存在する場合があります（C:\Siigo、C:\Siigo2、D:\Siigo など）。
• 企業：各インストールでは、filepath.txt に1社分のパスを指定します。そのパスを基点に、親フォルダーを調べて SIIWI00..SIIWI99 を検索します。実際の SIIGO データ（ZnnSIIGO、CONFIMP.CFG、.DIS ファイル）を含む企業のみを受け付けるため、同名の空フォルダーやインストール用フォルダーは企業として提示されません。
• 自動検出で見つからないものを登録するには、siigo_add_installation を使用するか、siigo_set_credentials で企業のパスに直接認証情報を保存してください。

企業は、パス（Z:\SIIWI01\）、番号（01）、またはエイリアスで指定できます。

ツール

デフォルトでは12個を公開します。各ツールのスキーマはモデルへの呼び出しごとに送信されるため、47個の関数を独立したツールとして公開すると、1回の呼び出しにつき約35,000トークンかかります。 実測値では、tools/list は140,116文字、デフォルトプロファイルは8,927文字で、94％削減されます。 SIIGO_TOOLS で設定できます。

SIIGO_TOOLS	ツール	tools/list のコスト
core（デフォルト）	12個：補助ツールと siigo_run_function	約2,200トークン
all	58個：各関数につき1個	約35,000トークン

補助ツール

ツール	用途
siigo_start_here	最初に読む：使用方法の完全なプロトコルです。意図的に tools/list の先頭に配置されています。
siigo_doctor	Windows、SIIGO、Excel、デスクトップセッション、認証情報、企業、および50文字の上限を確認します。SIIGOの処理は実行しません。
siigo_list_installations	検出されたSIIGOのインストールを一覧表示します。
siigo_list_companies	利用可能な企業を、エイリアスおよび認証情報の有無とともに一覧表示します。
siigo_list_functions	47個の関数のカタログを一覧表示します。グループで絞り込めます。
siigo_describe_function	関数のパラメーター、位置引数の順序、およびマニュアルの例を表示します。
siigo_set_credentials	ユーザー名とパスワードを、グローバルまたは企業ごとに保存します。
siigo_set_company_alias	企業にわかりやすい名前を付けます。
siigo_add_installation	自動検出されなかったインストールを登録します。
siigo_get_config	設定を表示します（キーはマスクされます）。
siigo_read_xlsx	生成された任意の .xlsx をページごとに読み込みます。

関数ツール

core プロファイルでは、siigo_run_function の1つだけを公開し、名前を指定して47個の関数のいずれかを実行します。all では、関数ごとに小文字の名前を付けて公開します（siigo_getmov、siigo_getter、siigo_pushmov など）。どちらの経路もまったく同じ argv を構築し、それらを並べて比較するテストがあります。

すべての関数で共通フィールド（必須の empresa、anio、norma、instalacion、usuario、clave）と、関数固有のパラメーターを指定できます。エクスポート関数では、さらに filasPreview も指定できます。

siigo_run_function で PUSH* 関数を実行するには、confirmarEscritura: true が必須です。47個のツールを1つにまとめると、関数ごとの destructiveHint が失われます。また、インポートではサーバーが取り消せないまま会計データに書き込みが行われるため、保護を明示的に指定する必要があります。

リソースとプロンプト

siigo://guia/inicio は --help と同じガイドを提供し、siigo://funcion/{nombre} は関数のシグネチャをMarkdownで提供します。どちらもツール呼び出しを消費せずに参照できます。プロンプト siigo_puesta_en_marcha では、起動手順全体を案内します。クライアントがリソースを要求しない限り、リソースはコンテキストを消費しません。

GET* 関数は .xlsx のパス、行数、列、および解析済みの先頭50行を返します。siigo_read_xlsx で続きの行を取得するための siguienteOffset も返します。

SIIGOのモデルでは、タイトルは先頭にありません。1行目に企業名、2行目にモデル名があり、その後に空白行が2行続き、5行目にヘッダーがあります。リーダーはこの行を自動的に検出し、COBOLに由来する余分な空白を取り除きます。モデルによってヒューリスティックがうまく機能しない場合は、siigo_read_xlsx の filaEncabezado で行を指定できます。

設定

%APPDATA%\siigo-pyme-mcp\config.json に保存されます（SIIGO_MCP_CONFIG_DIR で移動できます）。

{
  "installations": ["D:\\Siigo"],
  "defaultCredentials": { "user": "TU_USUARIO", "password": "TU_CLAVE" },
  "companies": {
    "Z:\\SIIWI01\\": { "alias": "Inmunotek" },
    "Z:\\SIIWI02\\": { "alias": "Comercial", "user": "CONTA", "password": "2222", "year": "2025" }
  },
  "outputDir": "C:\\SiigoMCP\\out",
  "norma": "L",
  "timeoutMs": 180000
}

優先順位は、認証情報と年の両方で同じです。呼び出し時の値 → 環境変数 → 企業の値 → デフォルト値（または現在の年）。

注意が必要な点として、MCP クライアントの環境で SIIGO_ANO を定義すると、すべての企業の year フィールドよりもその年が優先されます。企業ごとに別の年を使うには、呼び出し時に anio を渡すか、環境から SIIGO_ANO を削除して、企業ごとの year だけを設定してください。siigo_doctor はこの状況を検出すると警告します。誤った会計年度を照会しても、応答からは気づけないためです。

0.2.0 までは、認証情報とは逆に、企業の年が SIIGO_ANO より優先されていました。両方の設定を使用していた場合は、0.3.0 に更新する前に、どの年が照会されるかを確認してください。

outputDir は短くしてください。SIIGO は .xlsx のパスを50文字に制限しています。siigo_doctor は残りの文字数を計算し、CLI によって黙って切り詰められる前に警告します。

環境変数

変数	用途
SIIGO_USUARIO、SIIGO_CLAVE	config.json に保存する代わりに使用する認証情報です。
SIIGO_ANO	デフォルトの処理年（4桁）です。
SIIGO_TOOLS	core（デフォルト）または all。［ツール］(#herramientas)を参照してください。
SIIGO_MCP_CONFIG_DIR	設定フォルダーを移動します。

診断

npx -y siigo-pyme-mcp --doctor            # informe legible; exit 1 si el veredicto es NO LISTO
npx -y siigo-pyme-mcp --doctor --json     # el mismo informe para consumo de máquina
npx -y siigo-pyme-mcp --doctor --sin-empresas   # omite el escaneo de discos, más rápido

10項目のチェックがあり、すべて常に実行されます。プラットフォーム、Node、SIIGO のインストール、Excel、デスクトップセッション、設定、認証情報、アクセス可能な企業、出力フォルダー、実行中の SIIGO または Excel プロセスを確認します。[ ok ] 以外の各結果には具体的な対処方法が示され、最後の行には必ず問題を解決する手順が表示されます。

EXCELSIIGO.exe は実行せず、Excel を起動せず、ファイルも書き込みません。Excel はレジストリ（App Paths と、代替手段としての COM ProgID）で検出し、セッションはプロセス自体のセッション番号で検出します。Excel が存在するか確認するためにインスタンスを作成すると、デスクトップのないマシンではハングします。これはまさに診断すべき障害です。キーがレポートに表示されることはありません。レポート全体をシリアル化し、キーが見つかった場合に失敗するテストもあります。

同じ情報は、登録後に MCP ツール siigo_doctor からも利用できます。

制限事項

これらはサーバーではなく、SIIGO の実行ファイルに起因します。

• プロセス一覧でキーを確認できます。 EXCELSIIGO.exe はキーを位置引数として受け取るため、実行中は Get-CimInstance Win32_Process に表示されます。外部からこれを避ける方法はありません。ただし、サーバーはキーをログ、エラーメッセージ、MCP の応答に含めません。
• 一度に実行できるのは一つです。 CLI は複数のインスタンスを同時に実行できないため、サーバーは実行をキューに入れます。
• **エラーが発生するとダイアログが開き、クリックされるまで待機します。**ログは書き込まれません。サーバーはプロセスのウィンドウタイトルを監視し、エラーダイアログを認識すると直ちに実行をキャンセルして、そのタイトルを返します。SIIGO が何も書き込まなかった場合に、何が起きたかを説明するのはここだけです。
• **エクスポートには時間がかかります。**千件の第三者情報を取得する GETTER には約1分、1年分の25,000件の動きを取得する GETMOV には2分強かかります。サーバーは、無応答を理由にクライアントが呼び出しを中断しないよう進捗通知を送信し、デフォルトでは180秒後に処理を終了します（設定の timeoutMs）。
• **すべての機能がすべての企業で使えるわけではありません。**SIIGO のライセンスにシリアル番号モジュールまたは給与計算モジュールが含まれていない場合、それらの機能は 020 または 105 を返します。サーバーはこれを通常のエラーと区別し、moduloNoDisponible: true を返します。再試行しても状況は変わらないため、SIIGO でモジュールを有効にするか、別の機能を使用してください。
• **パスの長さは50文字までです。**出力 .xlsx とログに適用されます。サーバーは短い名前を生成し、パスが上限を超えている場合は呼び出し前に通知します。
• COM を使用するため、Excel と対話型セッションが必要です。
• **exit code 0 は成功を意味しません。**バイナリは失敗しても（081 Parámetros de la función tienen errores）、終了コード0で終了する場合があります。サーバーは実行を成功と判断する前に、終了コード、ログの内容、生成されたファイルの有無とサイズという3つのシグナルを組み合わせて確認します。
• インポート結果は、マニュアルの説明どおり、指定されたパスではなく企業の TEMP フォルダーに保存されます。
• 企業がネットワークドライブにあり、そのリソースが停止した場合、Windows ではマッピングが表示されていても接続が切れた状態になります。サーバーは実行前にこれを検出し、明示的に通知します。

開発

npm install
npm run typecheck
npm test               # 220 tests, incluidos los dorados contra los ejemplos del manual
npm run build
npm run test:smoke     # handshake MCP en los dos perfiles, más --doctor --json
npm run test:e2e       # prueba negativa: exige que un fallo se reporte como fallo
npm run test:tools     # ejercita LAS 56 herramientas contra una instalación real

SIIGO のインストールが必要なのは test:e2e のみです。それ以外は CI マシンを含め、どのマシンでも実行できます。

認証情報がない場合は、ネガティブテストを実行します。意図的に無効な認証情報を使用し、バイナリ単体では行われないサーバーの失敗報告を検証します。有効な認証情報がある場合は、ポジティブテストを実行します。実際の GETTER を実行し、.xlsx が存在し、サイズが0より大きく、読み取り可能な列と行を含むことを検証します。

SIIGO_USUARIO=TU_USUARIO SIIGO_CLAVE=TU_CLAVE npm run test:e2e     # bash
$env:SIIGO_USUARIO='TU_USUARIO'; $env:SIIGO_CLAVE='TU_CLAVE'; npm run test:e2e   # PowerShell

test:tools は all プロファイルのツールを順に実行します。補助ツールを呼び出し、企業に対して29個のエクスポートを実際に実行し、18個のインポートは検証パスのみでテストします。インポートは会計データを書き換え、このスクリプトでは元に戻せないため、スキーマ、企業と認証情報の解決、argv の構築を確認し、実行ファイルを起動する前に存在しない入力ファイルが拒否されることを検証します。インポートの argv はゴールデンテストですべてカバーされています。インポートを実際にテストする場合は、テスト用の企業を使用してください。

ゴールデンテストについて

SIIGO のマニュアル（<instalación>\ExcelSIIGO-Ayuda.LOG）には、各機能の Ejemplo: 行があります。src/siigo/args.golden.test.ts は同じ値で argv を再構築し、トークン単位で一致することを検証します。これは、バイナリが何も通知せずに報告するエラー 081 に対する唯一の実質的な防御策です。src/catalog/functions.ts の関数シグネチャを修正した場合は、対応するテストで確認できます。

公開

公開は自動で行われます。手動で公開することはありません。

• ci.yml は、Windows ランナー上で各 PR と main への各プッシュを検証します。typecheck、テスト、ビルド、スモークテスト、および tarball に配布用アーティファクトのみが含まれていることの確認を行います。
• publish.yml は v* タグのプッシュ時に実行され、完全な検証を再度行った後、--provenance を使って npm に公開し、GitHub Actions の OIDC で認証して公式 MCP Registry に公開し、生成されたリリースノートを添えて GitHub Release を作成します。

バージョンをリリースするには：

npm version patch --no-git-tag-version   # o minor / major
# sincronizar server.json a la misma versión (version y packages[].version)
git commit -am "release: v0.1.1"
git push
git tag v0.1.1
git push origin v0.1.1

ワークフローは、package.json、タグ、server.json の内容が一致しない場合、公開をブロックします。バージョンが異なると MCP Registry は 422 で拒否するため、npm に何もアップロードする前に失敗させるほうが適切です。

リポジトリで一度だけ必要な設定：npm の Automation タイプのトークンを使ったシークレット NPM_TOKEN（Automation トークンは、ランナーでは対応できない 2FA を省略します）。MCP Registry にはシークレットは不要です。

ライセンス

MIT。独立したプロジェクトであり、Informática y Gestión S.A.（SIIGO）とは関係ありません。