siigo-pyme-mcp

Servidor MCP que expone SIIGO Pyme a un agente de IA. Envuelve EXCELSIIGO.exe, el ejecutable de interfases de SIIGO, y convierte sus 47 funciones de exportación e importación en herramientas MCP con parámetros documentados, descubrimiento automático de empresas y resultados ya parseados a 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: [...] }

Se autodiagnostica: npx -y siigo-pyme-mcp --doctor dice si el equipo puede ejecutar SIIGO y qué falta, y --print-config escupe el bloque de configuración exacto para su cliente MCP. Las dos cosas funcionan antes de registrar nada.

Requisitos

Instalación

No hace falta instalar nada: se ejecuta con npx. Cuatro pasos, y el propio paquete guía cada uno.

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 conoce hermes, Claude Desktop, Claude Code, VS Code y Cursor, e imprime además los primitivos del protocolo para cualquier cliente que no esté en la lista. Sin argumento --cliente los muestra todos. Para el caso genérico:

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

El -y no es opcional: sin él npx pide confirmación por consola, se queda esperando, y el cliente MCP interpreta ese silencio como que el servidor no arrancó.

Si la instalación falla

En hermes hay un detalle que rompe la configuración escrita a mano: en su config.yaml, args y env son cadenas JSON dentro del YAML, no una lista y un mapa YAML. --print-config --cliente hermes ya lo emite así.

Si el agente no sabe usarlo

Registrar el servidor no basta para que el agente sepa qué hacer con él. El "cómo usarme" vive en tres canales del protocolo MCP, y no todos los clientes los leen:

1. instructions del InitializeResult — el texto que este servidor manda al conectar.
2. Recursos (siigo://guia/inicio, siigo://protocolo) y el prompt siigo_puesta_en_marcha.
3. Los nombres y descripciones de las herramientas — el único canal que todo cliente MCP entrega, porque sin él no podría llamarlas.

En hermes, por ejemplo, el canal 1 se pierde por completo: captura el InitializeResult solo para leer capabilities y nunca lee .instructions (tools/mcp_tool.py, en el comentario junto a self.initialize_result). Los recursos y prompts del canal 2 son opt-in y ningún agente los consulta espontáneamente. Solo queda el canal 3, así que este servidor lo usa a fondo:

• siigo_start_here es la primera herramienta de tools/list, titulada "LEER PRIMERO", y devuelve el protocolo de uso completo.
• Si el agente no la llama, la primera respuesta de cualquier otra herramienta siigo_* en el proceso trae el protocolo anexado al final de su contenido, una sola vez.
• npx -y siigo-pyme-mcp --print-agent-rules --cliente <su cliente> imprime ese mismo protocolo en el formato de reglas del cliente (una skill con frontmatter para hermes y Claude Code, un bloque para pegar en AGENTS.md o las instrucciones del proyecto para el resto), para que llegue antes de la primera llamada. Con --instalar lo escribe directamente en la carpeta de skills del cliente (por ejemplo %LOCALAPPDATA%\hermes\skills\siigo-pyme-mcp\SKILL.md); nunca sobrescribe un fichero existente con contenido distinto salvo que se agregue --forzar.

Primeros pasos

1. siigo_doctor — verifica el entorno y dice qué falta. Es la primera llamada ante cualquier fallo.
2. siigo_list_companies — lista las empresas SIIWI01..SIIWI99 disponibles.
3. siigo_set_credentials — guarda usuario y clave. Sin indicar empresa, la credencial se aplica a todas, que es lo más cómodo si usa el mismo usuario en todas ellas.
4. siigo_describe_function — los parámetros exactos de la función que va a usar.
5. siigo_run_function — ejecútela.

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" })

El paso 4 no es ceremonia: el CLI acepta un parámetro mal formateado, lo registra como 081 y termina con código 0, así que un error de parámetros se parece a un éxito. Es la única forma en la que este servidor puede devolver datos equivocados.

Cómo encuentra sus empresas

• Instalaciones: se leen del registro de Windows (HKLM\SOFTWARE\WOW6432Node\Informatica y Gestion S.A\Siigo Windows), de la configuración del servidor, y escaneando las unidades en busca de carpetas <X>:\Siigo* que contengan EXCELSIIGO.exe. Puede tener varias (C:\Siigo, C:\Siigo2, D:\Siigo...).
• Empresas: cada instalación declara en su filepath.txt la ruta de una empresa. A partir de ella se explora la carpeta que la contiene buscando SIIWI00..SIIWI99. Solo se aceptan las que traen datos reales de SIIGO (ZnnSIIGO, CONFIMP.CFG, archivos .DIS), de modo que carpetas homónimas vacías o de instalación no se ofrecen como empresas.
• Para registrar algo que el autodescubrimiento no ve, use siigo_add_installation o guarde credenciales directamente sobre la ruta de la empresa con siigo_set_credentials.

Puede referirse a una empresa por su ruta (Z:\SIIWI01\), por su número (01) o por el alias.

Herramientas

Por defecto expone 12. Cada esquema de herramienta viaja en cada llamada al modelo, así que las 47 funciones como herramientas independientes cuestan unos 35 000 tokens por llamada — medidos: 140 116 caracteres de tools/list frente a 8 927 del perfil por defecto, un 94 % menos. Se controla con SIIGO_TOOLS:

De apoyo

De función

En el perfil core, una sola: siigo_run_function, que ejecuta cualquiera de las 47 por nombre. En all, una por función con el nombre en minúsculas (siigo_getmov, siigo_getter, siigo_pushmov...). Las dos rutas construyen exactamente el mismo argv, y hay un test que lo compara lado a lado.

Todas aceptan los mismos campos comunes — empresa (obligatorio), anio, norma, instalacion, usuario, clave — más los parámetros propios de la función. Las de exportación admiten además filasPreview.

siigo_run_function exige confirmarEscritura: true para las funciones PUSH*. Al colapsar 47 herramientas en una se pierde el destructiveHint por función, y una importación escribe en la contabilidad sin que el servidor pueda deshacerla; la protección pasa a ser explícita.