{
  "markdown": "# siigo-pyme-mcp\n\nServidor [MCP](https://modelcontextprotocol.io) que expone **SIIGO Pyme** a un agente de IA.\nEnvuelve `EXCELSIIGO.exe`, el ejecutable de interfases de SIIGO, y convierte sus **47 funciones**\nde exportación e importación en herramientas MCP con parámetros documentados, descubrimiento\nautomático de empresas y resultados ya parseados a JSON.\n\n```\nAgente: \"dame los terceros de la empresa 02\"\n  → siigo_run_function(funcion: \"GETTER\", empresa: \"02\")\n  → EXCELSIIGO.exe Z:\\SIIWI02\\ 2026 GETTER L USUARIO **** ... Terceros.xlsx\n  → { ok: true, archivo: \"...\", totalFilas: 1240, columnas: [...], filas: [...] }\n```\n\nSe autodiagnostica: `npx -y siigo-pyme-mcp --doctor` dice si el equipo puede ejecutar SIIGO y qué\nfalta, y `--print-config` escupe el bloque de configuración exacto para su cliente MCP. Las dos\ncosas funcionan **antes** de registrar nada.\n\n## Requisitos\n\n| Requisito | Por qué |\n|---|---|\n| **Windows** | SIIGO Pyme solo existe en Windows. |\n| **SIIGO Pyme instalado** | Se necesita `EXCELSIIGO.exe` (por defecto en `C:\\Siigo`). |\n| **Microsoft Excel instalado** | SIIGO genera los `.xlsx` con Excel por COM, a través de `SiigoExcel.exe`. Sin Excel no se produce ningún archivo. |\n| **Sesión de escritorio activa** | Consecuencia de lo anterior: no funciona como servicio de Windows, ni por SSH sin sesión, ni en un contenedor. Durante cada ejecución verás aparecer la ventana de progreso de SIIGO y Excel: **no se pueden ocultar**, con la ventana oculta el proceso se cuelga sin generar nada. |\n| **Node.js 18 o superior** | Para ejecutarlo con `npx`. |\n\n## Instalación\n\nNo hace falta instalar nada: se ejecuta con `npx`. Cuatro pasos, y el propio paquete guía cada uno.\n\n```bash\nnpx -y siigo-pyme-mcp --doctor                            # 1. ¿puede este equipo ejecutar SIIGO?\nnpx -y siigo-pyme-mcp --print-config --cliente hermes     # 2. el bloque exacto a pegar\nnpx -y siigo-pyme-mcp --print-agent-rules --cliente hermes  # 3. que el agente sepa usarlo\n# 4. reinicie el cliente MCP y repita --doctor\n```\n\n`--print-config` conoce **hermes**, Claude Desktop, Claude Code, VS Code y Cursor, e imprime\nademás los primitivos del protocolo para cualquier cliente que no esté en la lista. Sin argumento\n`--cliente` los muestra todos. Para el caso genérico:\n\n```json\n{\n  \"mcpServers\": {\n    \"siigo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"siigo-pyme-mcp\"],\n      \"env\": {\n        \"SIIGO_USUARIO\": \"TU_USUARIO\",\n        \"SIIGO_CLAVE\": \"TU_CLAVE\"\n      }\n    }\n  }\n}\n```\n\nEl `-y` **no es opcional**: sin él npx pide confirmación por consola, se queda esperando, y el\ncliente MCP interpreta ese silencio como que el servidor no arrancó.\n\n### Si la instalación falla\n\n| Síntoma | Causa real |\n|---|---|\n| `npm error EBADPLATFORM ... wanted {\"os\":\"win32\"}` | Se está instalando fuera de Windows (WSL, contenedor, Linux). Hay que registrarlo en la máquina Windows donde está SIIGO; `--force` no ayuda, porque sin SIIGO ni Excel no hay nada que ejecutar. |\n| El cliente dice que el servidor no arrancó, sin más detalle | Falta el `-y` en npx. |\n| `'npx' no se reconoce como un comando`, o `ENOENT` al lanzarlo | El cliente MCP no tiene `npx` en su PATH. Use `--print-config --absoluto`, que emite un bloque apuntando a `node.exe` y al `dist/index.js` instalado, con las rutas reales de esa máquina. |\n| Arranca, pero toda función falla sin generar archivo | Falta Excel, falta la sesión de escritorio, o alguna ruta pasa de 50 caracteres. Ejecute `--doctor`. |\n\nEn hermes hay un detalle que rompe la configuración escrita a mano: en su `config.yaml`, `args` y\n`env` son **cadenas JSON dentro del YAML**, no una lista y un mapa YAML. `--print-config --cliente\nhermes` ya lo emite así.\n\n## Si el agente no sabe usarlo\n\nRegistrar el servidor no basta para que el agente sepa qué hacer con él. El \"cómo usarme\" vive en\ntres canales del protocolo MCP, y no todos los clientes los leen:\n\n1. `instructions` del `InitializeResult` — el texto que este servidor manda al conectar.\n2. Recursos (`siigo://guia/inicio`, `siigo://protocolo`) y el prompt `siigo_puesta_en_marcha`.\n3. Los nombres y descripciones de las herramientas — el único canal que **todo** cliente MCP\n   entrega, porque sin él no podría llamarlas.\n\nEn hermes, por ejemplo, el canal 1 se pierde por completo: captura el `InitializeResult` solo\npara leer `capabilities` y nunca lee `.instructions` (`tools/mcp_tool.py`, en el comentario junto\na `self.initialize_result`). Los recursos y prompts del canal 2 son opt-in y ningún agente los\nconsulta espontáneamente. Solo queda el canal 3, así que este servidor lo usa a fondo:\n\n- **`siigo_start_here`** es la primera herramienta de `tools/list`, titulada \"LEER PRIMERO\", y\n  devuelve el protocolo de uso completo.\n- Si el agente no la llama, **la primera respuesta de cualquier otra herramienta `siigo_*`** en\n  el proceso trae el protocolo anexado al final de su contenido, una sola vez.\n- **`npx -y siigo-pyme-mcp --print-agent-rules --cliente <su cliente>`** imprime ese mismo\n  protocolo en el formato de reglas del cliente (una skill con frontmatter para hermes y Claude\n  Code, un bloque para pegar en `AGENTS.md` o las instrucciones del proyecto para el resto), para\n  que llegue **antes** de la primera llamada. Con `--instalar` lo escribe directamente en la\n  carpeta de skills del cliente (por ejemplo `%LOCALAPPDATA%\\hermes\\skills\\siigo-pyme-mcp\\SKILL.md`);\n  nunca sobrescribe un fichero existente con contenido distinto salvo que se agregue `--forzar`.\n\n## Primeros pasos\n\n1. **`siigo_doctor`** — verifica el entorno y dice qué falta. Es la primera llamada ante cualquier fallo.\n2. **`siigo_list_companies`** — lista las empresas `SIIWI01`..`SIIWI99` disponibles.\n3. **`siigo_set_credentials`** — guarda usuario y clave. Sin indicar empresa, la credencial\n   se aplica a **todas**, que es lo más cómodo si usa el mismo usuario en todas ellas.\n4. **`siigo_describe_function`** — los parámetros exactos de la función que va a usar.\n5. **`siigo_run_function`** — ejecútela.\n\n```\nsiigo_set_credentials(usuario: \"TU_USUARIO\", clave: \"TU_CLAVE\")\nsiigo_set_company_alias(empresa: \"Z:\\\\SIIWI01\\\\\", alias: \"Inmunotek\")\nsiigo_describe_function(funcion: \"GETMOV\")\nsiigo_run_function(funcion: \"GETMOV\", empresa: \"Inmunotek\",\n                   params: { fechaInicial: \"0101\", fechaFinal: \"0131\", tipoComprobante: \"F\" })\n```\n\nEl paso 4 no es ceremonia: el CLI acepta un parámetro mal formateado, lo registra como `081` y\n**termina con código 0**, así que un error de parámetros se parece a un éxito. Es la única forma\nen la que este servidor puede devolver datos equivocados.\n\n## Cómo encuentra sus empresas\n\n- **Instalaciones**: se leen del registro de Windows\n  (`HKLM\\SOFTWARE\\WOW6432Node\\Informatica y Gestion S.A\\Siigo Windows`), de la configuración\n  del servidor, y escaneando las unidades en busca de carpetas `<X>:\\Siigo*` que contengan\n  `EXCELSIIGO.exe`. Puede tener varias (`C:\\Siigo`, `C:\\Siigo2`, `D:\\Siigo`...).\n- **Empresas**: cada instalación declara en su `filepath.txt` la ruta de **una** empresa.\n  A partir de ella se explora la carpeta que la contiene buscando `SIIWI00`..`SIIWI99`. Solo\n  se aceptan las que traen datos reales de SIIGO (`ZnnSIIGO`, `CONFIMP.CFG`, archivos `.DIS`),\n  de modo que carpetas homónimas vacías o de instalación no se ofrecen como empresas.\n- Para registrar algo que el autodescubrimiento no ve, use `siigo_add_installation` o\n  guarde credenciales directamente sobre la ruta de la empresa con `siigo_set_credentials`.\n\nPuede referirse a una empresa por su ruta (`Z:\\SIIWI01\\`), por su número (`01`) o por el alias.\n\n## Herramientas\n\nPor defecto expone **12**. Cada esquema de herramienta viaja en *cada* llamada al modelo, así que\nlas 47 funciones como herramientas independientes cuestan unos 35 000 tokens por llamada —\nmedidos: 140 116 caracteres de `tools/list` frente a 8 927 del perfil por defecto, un 94 % menos.\nSe controla con `SIIGO_TOOLS`:\n\n| `SIIGO_TOOLS` | Herramientas | Coste de `tools/list` |\n|---|---|---|\n| `core` (por defecto) | 12: las de apoyo más `siigo_run_function` | ~2 200 tokens |\n| `all` | 58: una por cada función | ~35 000 tokens |\n\n### De apoyo\n\n| Herramienta | Para qué |\n|---|---|\n| `siigo_start_here` | LEER PRIMERO: protocolo de uso completo. Primera de `tools/list` a propósito. |\n| `siigo_doctor` | Verifica Windows, SIIGO, Excel, sesión de escritorio, credenciales, empresas y el límite de 50 caracteres. No ejecuta nada de SIIGO. |\n| `siigo_list_installations` | Instalaciones de SIIGO detectadas. |\n| `siigo_list_companies` | Empresas disponibles, con alias y si tienen credenciales. |\n| `siigo_list_functions` | Catálogo de las 47 funciones, filtrable por grupo. |\n| `siigo_describe_function` | Parámetros, orden posicional y ejemplo del manual de una función. |\n| `siigo_set_credentials` | Guarda usuario y clave, global o por empresa. |\n| `siigo_set_company_alias` | Da un nombre legible a una empresa. |\n| `siigo_add_installation` | Registra una instalación que no se detectó sola. |\n| `siigo_get_config` | Muestra la configuración (claves enmascaradas). |\n| `siigo_read_xlsx` | Lee de forma paginada cualquier `.xlsx` generado. |\n\n### De función\n\nEn el perfil `core`, una sola: **`siigo_run_function`**, que ejecuta cualquiera de las 47 por\nnombre. En `all`, una por función con el nombre en minúsculas (`siigo_getmov`, `siigo_getter`,\n`siigo_pushmov`...). Las dos rutas construyen exactamente el mismo `argv`, y hay un test que lo\ncompara lado a lado.\n\nTodas aceptan los mismos campos comunes — `empresa` (obligatorio), `anio`, `norma`,\n`instalacion`, `usuario`, `clave` — más los parámetros propios de la función. Las de\nexportación admiten además `filasPreview`.\n\n`siigo_run_function` exige **`confirmarEscritura: true`** para las funciones `PUSH*`. Al colapsar\n47 herramientas en una se pierde el `destructiveHint` por función, y una importación escribe en la\ncontabilidad sin que el servidor pueda deshacerla; la protección pasa a ser explícita.\n\n### Recursos y prompt\n\n`siigo://guia/inicio` trae la misma guía que `--help`, y `siigo://funcion/{nombre}` la firma de\nuna función en markdown, para consultarla sin gastar una llamada de herramienta. El prompt\n`siigo_puesta_en_marcha` recorre el arranque completo. Los recursos no cuestan contexto salvo que\nel cliente los pida.\n\nLas funciones `GET*` devuelven la ruta del `.xlsx`, el total de filas, las columnas y las\nprimeras 50 filas ya parseadas, con un `siguienteOffset` para continuar con `siigo_read_xlsx`.\n\nLos modelos de SIIGO no empiezan por los títulos: llevan el nombre de la empresa en la fila 1,\nel del modelo en la 2, dos filas vacías, y los encabezados en la 5. El lector detecta esa fila\nautomáticamente y recorta el relleno de espacios que arrastra COBOL. Si algún modelo despista a\nla heurística, `siigo_read_xlsx` acepta `filaEncabezado` para forzarla.\n\n## Configuración\n\nSe guarda en `%APPDATA%\\siigo-pyme-mcp\\config.json` (se puede reubicar con\n`SIIGO_MCP_CONFIG_DIR`).\n\n```json\n{\n  \"installations\": [\"D:\\\\Siigo\"],\n  \"defaultCredentials\": { \"user\": \"TU_USUARIO\", \"password\": \"TU_CLAVE\" },\n  \"companies\": {\n    \"Z:\\\\SIIWI01\\\\\": { \"alias\": \"Inmunotek\" },\n    \"Z:\\\\SIIWI02\\\\\": { \"alias\": \"Comercial\", \"user\": \"CONTA\", \"password\": \"2222\", \"year\": \"2025\" }\n  },\n  \"outputDir\": \"C:\\\\SiigoMCP\\\\out\",\n  \"norma\": \"L\",\n  \"timeoutMs\": 180000\n}\n```\n\n**Precedencia**, la misma para las credenciales y para el año: valor de la llamada → variable de\nentorno → valor de la empresa → valor por defecto (o el año actual).\n\nConsecuencia que conviene tener presente: si define `SIIGO_ANO` en el entorno del cliente MCP, ese\naño manda sobre el campo `year` de cualquier empresa. Para que una empresa trabaje en otro año,\npase `anio` en la llamada, o quite `SIIGO_ANO` del entorno y deje solo los `year` por empresa.\n`siigo_doctor` avisa cuando detecta esa situación, porque consultar el año contable equivocado no\nse nota en la respuesta.\n\n> Hasta la 0.2.0 el año de la empresa ganaba a `SIIGO_ANO`, al contrario que las credenciales. Si\n> usaba las dos fuentes a la vez, revise qué año va a consultar antes de actualizar a 0.3.0.\n\n`outputDir` debe ser **corto**: SIIGO limita la ruta del `.xlsx` a 50 caracteres. `siigo_doctor`\ncalcula el margen que queda y avisa antes de que el CLI empiece a truncar en silencio.\n\n### Variables de entorno\n\n| Variable | Para qué |\n|---|---|\n| `SIIGO_USUARIO`, `SIIGO_CLAVE` | Credenciales, como alternativa a guardarlas en el `config.json`. |\n| `SIIGO_ANO` | Año de proceso por defecto, 4 dígitos. |\n| `SIIGO_TOOLS` | `core` (por defecto) o `all`. Ver [Herramientas](#herramientas). |\n| `SIIGO_MCP_CONFIG_DIR` | Reubica la carpeta de configuración. |\n\n## Diagnóstico\n\n```bash\nnpx -y siigo-pyme-mcp --doctor            # informe legible; exit 1 si el veredicto es NO LISTO\nnpx -y siigo-pyme-mcp --doctor --json     # el mismo informe para consumo de máquina\nnpx -y siigo-pyme-mcp --doctor --sin-empresas   # omite el escaneo de discos, más rápido\n```\n\nDiez comprobaciones, todas se ejecutan siempre: plataforma, Node, instalaciones de SIIGO, Excel,\nsesión de escritorio, configuración, credenciales, empresas accesibles, carpeta de salida y\nprocesos de SIIGO o Excel vivos. Cada resultado que no esté en `[ ok ]` viene con una acción\nconcreta, y la última línea es siempre el paso que desbloquea.\n\nNunca ejecuta `EXCELSIIGO.exe`, no lanza Excel y no escribe ningún archivo. Detecta Excel por el\nregistro (`App Paths`, y el ProgID COM como respaldo) y la sesión por el número de sesión del\npropio proceso: instanciar Excel para comprobar que existe se colgaría en una máquina sin\nescritorio, que es justo el fallo que hay que diagnosticar. La clave nunca aparece en el informe;\nhay un test que serializa el informe completo y falla si la encuentra.\n\nLa misma información está disponible como herramienta MCP, `siigo_doctor`, una vez registrado.\n\n## Limitaciones\n\nNacen del ejecutable de SIIGO, no del servidor:\n\n- **La clave es visible en la tabla de procesos.** `EXCELSIIGO.exe` la recibe como argumento\n  posicional, así que aparece en `Get-CimInstance Win32_Process` mientras dura la ejecución.\n  No hay forma de evitarlo desde fuera. El servidor sí la mantiene fuera de logs, mensajes de\n  error y respuestas MCP.\n- **Una ejecución a la vez.** El CLI no tolera instancias simultáneas; el servidor las encola.\n- **Ante un error abre un cuadro de diálogo y espera un clic**, sin escribir el log. El servidor\n  vigila el título de la ventana del proceso y, en cuanto reconoce un diálogo de error, cancela\n  la ejecución y devuelve ese título: es el único sitio donde SIIGO explica qué pasó cuando no\n  llega a escribir nada.\n- **Las exportaciones tardan.** Un `GETTER` de mil terceros ronda el minuto; un `GETMOV` de un\n  año completo con 25 000 movimientos, algo más de dos. El servidor emite notificaciones de\n  progreso para que el cliente no aborte la llamada por silencio, y corta a los 180 segundos\n  por defecto (`timeoutMs` en la configuración).\n- **No todas las funciones aplican a todas las empresas.** Si SIIGO está licenciado sin el\n  módulo de seriales o el de nómina, esas funciones responden `020` o `105`. El servidor lo\n  distingue de un error corriente y devuelve `moduloNoDisponible: true`: reintentar no cambia\n  nada, hay que habilitar el módulo en SIIGO o usar otra función.\n- **Rutas de 50 caracteres.** Se aplica al `.xlsx` de salida y al log. El servidor genera\n  nombres cortos y avisa antes de invocar si una ruta se pasa.\n- **Requiere Excel y sesión interactiva**, por el uso de COM.\n- **`exit code 0` no significa éxito.** El binario puede fallar (`081 Parámetros de la función\n  tienen errores`) y salir con 0. El servidor combina tres señales antes de dar por buena una\n  corrida: código de salida, contenido del log y existencia y tamaño del archivo generado.\n- **Las importaciones dejan su resultado en la carpeta `TEMP` de la empresa**, según documenta\n  el manual, no en la ruta que se indique.\n- Si la empresa vive en una unidad de red mapeada y el recurso se cae, Windows deja el mapeo\n  visible pero desconectado. El servidor lo detecta antes de ejecutar y lo dice explícitamente.\n\n## Desarrollo\n\n```bash\nnpm install\nnpm run typecheck\nnpm test               # 220 tests, incluidos los dorados contra los ejemplos del manual\nnpm run build\nnpm run test:smoke     # handshake MCP en los dos perfiles, más --doctor --json\nnpm run test:e2e       # prueba negativa: exige que un fallo se reporte como fallo\nnpm run test:tools     # ejercita LAS 56 herramientas contra una instalación real\n```\n\n`test:e2e` es el único script que necesita SIIGO instalado; el resto corre en cualquier\nmáquina, incluida la de CI.\n\nSin credenciales corre la **prueba negativa**: usa unas inválidas a propósito y exige que el\nservidor reporte el fallo, que es justo lo que el binario no hace por su cuenta. Con\ncredenciales válidas corre la **prueba positiva**, que ejecuta un `GETTER` real y verifica que\nel `.xlsx` exista, pese más de cero y traiga columnas y filas legibles:\n\n```bash\nSIIGO_USUARIO=TU_USUARIO SIIGO_CLAVE=TU_CLAVE npm run test:e2e     # bash\n$env:SIIGO_USUARIO='TU_USUARIO'; $env:SIIGO_CLAVE='TU_CLAVE'; npm run test:e2e   # PowerShell\n```\n\n`test:tools` recorre las herramientas del perfil `all`: invoca las de apoyo, **ejecuta de verdad** las 29\nexportaciones contra la empresa, y prueba las 18 importaciones **solo por su ruta de\nvalidación**. Las importaciones escriben en la contabilidad y ese script no puede deshacerlo,\nasí que comprueba el esquema, la resolución de empresa y credenciales y la construcción del\nargv, y verifica que rechacen un archivo de entrada inexistente antes de lanzar el ejecutable.\nSu argv sí está cubierto al completo por los tests dorados. Para probar una importación de\nverdad, use una empresa de pruebas.\n\n### Sobre los tests dorados\n\nEl manual de SIIGO (`<instalación>\\ExcelSIIGO-Ayuda.LOG`) trae una línea `Ejemplo:` por cada\nfunción. `src/siigo/args.golden.test.ts` reconstruye el `argv` con esos mismos valores y exige\nque coincida token por token. Es la única defensa real contra el error `081`, que el binario\nreporta en silencio. Si corrige la firma de una función en `src/catalog/functions.ts`, el test\ncorrespondiente se lo confirmará.\n\n## Publicación\n\nLa publicación es automática. No se publica nada a mano.\n\n- **`ci.yml`** valida cada PR y cada push a `main` en un runner de Windows: typecheck, tests,\n  build, smoke y comprobación de que el tarball solo lleva artefactos de distribución.\n- **`publish.yml`** se dispara al empujar un tag `v*` y, tras repetir la validación completa,\n  publica a npm con `--provenance`, publica al MCP Registry oficial autenticando con el OIDC\n  de GitHub Actions, y crea la GitHub Release con notas generadas.\n\nPara sacar una versión:\n\n```bash\nnpm version patch --no-git-tag-version   # o minor / major\n# sincronizar server.json a la misma versión (version y packages[].version)\ngit commit -am \"release: v0.1.1\"\ngit push\ngit tag v0.1.1\ngit push origin v0.1.1\n```\n\nEl workflow bloquea la publicación si `package.json`, el tag y `server.json` no coinciden:\nel MCP Registry rechaza con 422 cuando las versiones difieren, y es mejor fallar antes de\nhaber subido nada a npm.\n\nConfiguración necesaria una sola vez en el repositorio: el secret **`NPM_TOKEN`** con un token\nde tipo *Automation* de npm (los tokens Automation omiten el 2FA, que un runner no puede\nresolver). El MCP Registry no necesita ningún secret.\n\n## Licencia\n\nMIT. Proyecto independiente, sin relación con Informática y Gestión S.A. (SIIGO).\n",
  "bytes": 19531,
  "sha": "2e5eb2ecf6cf27a45d7dd45fd6464003396399c77909b5ff878788caf28f96c5",
  "repo_slug": "javalenciacai/siigo-pyme-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_javalenciacai_siigo_pyme_mcp_432a70fc/readme"
}