siigo-pyme-mcp

siigo-pyme-mcp

MCP 服务，可将 SIIGO Pyme 提供给 AI Agent 使用。 它封装了 SIIGO 的接口可执行文件 EXCELSIIGO.exe，并将其 47 个导出和导入功能 转换为带有文档化参数的 MCP 工具，支持自动发现公司，并将结果解析为 JSON。

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 会告知设备能否运行 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 运行即可。只需四个步骤，软件包会逐步引导你完成。

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。请使用 --print-config --absoluto，它会输出指向 node.exe 和已安装的 dist/index.js 的配置代码块，并填入该计算机上的实际路径。
服务已启动，但所有功能都失败且未生成文件	缺少 Excel、没有桌面会话，或者某个路径超过 50 个字符。请运行 --doctor。

在 hermes 中，有个细节会导致手动编写的配置出错：在它的 config.yaml 中，args 和 env 是 YAML 中的 JSON 字符串，而非 YAML 列表和映射。--print-config --cliente hermes 会按此格式输出配置。

如果 Agent 不知道如何使用

注册服务器并不足以让 Agent 知道该如何使用它。“如何使用我”的信息存在于 MCP 协议的三个通道中，但并非所有客户端都会读取这些信息：

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 的资源和提示词需要选择启用，也没有 Agent 会主动查询它们。因此只剩下通道 3，此服务器会充分利用它：

• siigo_start_here 是 tools/list 中的第一个工具，标题为“请先阅读”，并会返回完整的使用协议。
• 如果 Agent 不调用它，进程中任何其他 siigo_* 工具的首次响应都会在内容末尾附上该协议，仅一次。
• npx -y siigo-pyme-mcp --print-agent-rules --cliente <su cliente> 会以客户端规则格式输出相同的协议（为 hermes 和 Claude Code 输出带 frontmatter 的 skill，为其他客户端输出可粘贴到 AGENTS.md 的区块或项目说明），以便在首次调用前将其提供给 Agent。使用 --instalar 会将其直接写入客户端的 skills 文件夹（例如 %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 中声明一个公司的路径。 从该路径开始，会搜索其所在文件夹，查找 SIIWI00..SIIWI99。只有包含真实 SIIGO 数据（ZnnSIIGO、CONFIMP.CFG、.DIS 文件）的公司才会被接受，因此不会将同名的空文件夹或安装文件夹作为公司提供。
• 如需登记自动发现功能无法找到的项目，请使用 siigo_add_installation，或使用 siigo_set_credentials 直接为公司的路径保存凭据。

可以通过路径（Z:\SIIWI01\）、编号（01）或别名来指代公司。

工具

默认公开 12 个。每个工具架构都会随每次模型调用发送，因此将 47 个函数作为独立工具会使每次调用耗费约 35 000 个令牌——实测：tools/list 为 140 116 个字符，而默认配置为 8 927 个，减少了 94%。通过 SIIGO_TOOLS 控制：

SIIGO_TOOLS	工具	tools/list 开销
core（默认）	12 个：辅助工具加上 siigo_run_function	约 2 200 个令牌
all	58 个：每个函数对应一个工具	约 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，可按名称执行 47 个函数中的任意一个。在 all 配置中，每个函数各有一个工具，名称均为小写（siigo_getmov、siigo_getter、siigo_pushmov……）。两种方式构建的 argv 完全相同，并且有一个测试会逐项比较两者。

所有工具都接受相同的通用字段——empresa（必填）、anio、norma、instalacion、usuario、clave——以及函数专属参数。导出工具还接受 filasPreview。

siigo_run_function 要求对 PUSH* 函数设置 confirmarEscritura: true。将 47 个工具合并为一个后，会失去每个函数的 destructiveHint；而导入会写入会计账目，服务无法撤销此操作，因此必须显式启用保护。

资源和提示词

siigo://guia/inicio 提供与 --help 相同的指南，siigo://funcion/{nombre} 则以 markdown 格式提供函数签名，可供查询而无需消耗一次工具调用。提示词 siigo_puesta_en_marcha 会引导完成完整的启动流程。除非客户端请求资源，否则不会占用上下文。

GET* 函数会返回 .xlsx 文件路径、行数总计、列以及已解析的前 50 行，并提供 siguienteOffset，以便继续使用 siigo_read_xlsx 读取。

SIIGO 模型的标题不在开头：企业名称位于第 1 行，模型名称位于第 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。参见工具。
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 或写入任何文件。通过注册表（App Paths，并以 COM ProgID 作为备用）检测 Excel；通过进程自身的会话编号检测桌面会话：在没有桌面的计算机上实例化 Excel 来检查其是否存在，会导致程序卡住，而这正是需要诊断的问题。报告中绝不会显示密钥；有一项测试会序列化完整报告，并在发现密钥时失败。

注册后，同样的信息也可通过 MCP 工具 siigo_doctor 获取。

限制

这些限制源自 SIIGO 可执行文件，而非服务：

• 密钥会显示在进程表中。 EXCELSIIGO.exe 将其作为位置参数接收，因此在执行期间，它会出现在 Get-CimInstance Win32_Process 中。 无法从外部避免这一点。服务会确保密钥不会出现在日志、错误消息和 MCP 响应中。
• 一次只能执行一个任务。 CLI 不支持多个实例同时运行；服务会将它们排入队列。
• 出错时会打开一个对话框并等待点击，且不会写入日志。服务会监视进程窗口标题，一旦识别到错误对话框，就会取消执行并返回该标题：当 SIIGO 没有写入任何内容时，这是唯一能说明发生了什么的地方。
• 导出需要时间。 导出 1,000 条第三方记录的 GETTER 大约需要 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 退出。服务会结合三个信号判断运行是否成功：退出代码、日志内容，以及生成文件是否存在且大小是否符合预期。
• 导入结果会写入公司 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

test:e2e 是唯一需要安装 SIIGO 的脚本；其余脚本可在任何机器上运行，包括 CI 机器。

没有凭据时会运行负向测试：故意使用无效凭据，并要求服务报告失败，这正是二进制文件本身不会做的事情。使用有效凭据时会运行正向测试，执行真实的 GETTER，并验证 .xlsx 文件存在、大小大于零，且包含可读取的列和行：

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 的操作：类型检查、测试、构建、冒烟测试，以及检查 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 之前就失败。

只需在仓库中配置一次：设置 secret NPM_TOKEN，其值为 npm 的 Automation 类型令牌（Automation 令牌会跳过 2FA，而运行器无法处理 2FA）。MCP Registry 不需要任何 secret。

许可证

MIT。独立项目，与 Informática y Gestión S.A. (SIIGO) 无关。