Skip to content
Back to search

siigo-mcp-server-java

MCP Server implementado en Java que conecta LLM a Siigo mediante su REST API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gldconsulting--siigo-mcp-server-java/badge.svg)](/listings/gldconsulting--siigo-mcp-server-java)

HTML

<a href="/listings/gldconsulting--siigo-mcp-server-java"><img src="/api/listings/gldconsulting--siigo-mcp-server-java/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 456 lines
  1. # Siigo MCP Server para Java
  2. [![Java 21](https://img.shields.io/badge/Java-21-007396)](pom.xml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. Servidor de **Model Context Protocol (MCP)** de GLD Consulting S.A.S. para conectar asistentes de IA con **Siigo Colombia**, usando [nuestro SDK Java](https://github.com/gldconsulting/siigo-api-sdk-java), publicado como `co.gldconsulting:siigo-api-sdk:1.0.0`.
  5. Java 21, Maven, SDK oficial MCP Java, STDIO y Streamable HTTP. Independiente del proveedor del modelo: el asistente o aplicación debe actuar como cliente MCP compatible; un modelo por sí solo no abre conexiones MCP.
  6. > [!WARNING]
  7. > **Uso interno: este MCP no está diseñado para exponerse públicamente a Internet.**
  8. >
  9. > Debe utilizarse como herramienta interna o de apoyo para otros procesos, con acceso limitado a usuarios y sistemas autorizados. Exponerlo públicamente puede introducir una brecha de seguridad en tu arquitectura tecnológica y permitir el acceso no autorizado a datos contables de tu empresa y operaciones de Siigo.
  10. >
  11. > El bearer del transporte HTTP, la validación de Host/Origin y HTTPS no convierten esta implementación en un servicio preparado para exposición pública. Mantener el proceso en el equipo local o en una red privada; para ChatGPT, usar la conexión privada mediante Secure MCP Tunnel descrita más adelante.
  12. ## Compilar el JAR
  13. Requiere un JDK 21 y acceso a Maven Central. El wrapper descarga Maven; no se requiere una instalación global.
  14. ```sh
  15. ./mvnw clean verify
  16. ```
  17. Este comando genera y prueba el JAR; no deja un MCP operativo esperando conexiones. Quién ejecuta después el JAR depende del transporte elegido, como se explica en la tabla de arranque más adelante.
  18. El resultado es un JAR ejecutable con sus dependencias. La versión del servidor sigue siendo de desarrollo; este repositorio no implica que el servidor MCP ya esté publicado en Maven Central.
  19. ## Credenciales: entorno → SDK al iniciar
  20. El proceso recibe estas tres variables **antes de arrancar**:
  21. | Variable | Uso |
  22. |---|---|
  23. | `SIIGO_PARTNER_ID` | Partner-Id de la integración |
  24. | `SIIGO_USERNAME` | Usuario API de Siigo |
  25. | `SIIGO_ACCESS_KEY` | Access key de Siigo |
  26. El MCP las lee una sola vez en el startup y configura `SiigoApi.builder()`. A partir de ahí, **el SDK** obtiene el token al necesitarlo, lo almacena en memoria y lo renueva según su ciclo de vida. El servidor no implementa `/auth`, ni una caché alternativa, ni persistencia del token en disco. Reiniciar el proceso inicia otra sesión del SDK.
  27. Las variables se pasan al proceso con el entorno del shell, el gestor de secretos del despliegue, o el campo `env` del cliente MCP. No son argumentos de las herramientas ni parámetros `--username`, `--access-key` o `--token` de `java`. No es necesario pasar un token de Siigo; el servidor exige las tres variables anteriores.
  28. Las variables deben llegar al proceso que iniciará Java: el cliente local para STDIO, tu terminal o servicio para HTTP, o `tunnel-client` para el ejemplo de ChatGPT. Configurarlas en otra terminal no garantiza que esos procesos las hereden.
  29. No imprimirlas para comprobarlas ni guardarlas en el repositorio. Los ejemplos solo contienen marcadores; no son credenciales válidas.
  30. ## Quién arranca el MCP y qué preparar antes de conectar
  31. | Cliente y modalidad | Quién inicia el proceso Java del MCP | Qué hacer antes de conectar el cliente |
  32. |---|---|---|
  33. | Claude Desktop por STDIO | Claude Desktop, cuando conecta el servidor configurado | Compilar el JAR y configurar su ruta, Java 21 y las credenciales en el cliente; después abrir o reiniciar Claude Desktop |
  34. | Claude Code por STDIO | Claude Code, al conectar el servidor configurado | Compilar el JAR, preparar las variables en el entorno de Claude Code y registrar el servidor |
  35. | OpenCode con `type: "local"` | OpenCode, al conectar el servidor configurado | Compilar el JAR y preparar `opencode.jsonc` y las variables en el entorno de OpenCode |
  36. | OpenCode u otro cliente por HTTP | Tú, o un servicio de tu infraestructura | Configurar las credenciales y el bearer MCP, arrancar el servidor HTTP y mantenerlo funcionando; después conectar el cliente a su URL privada |
  37. | ChatGPT mediante Secure MCP Tunnel y STDIO | `tunnel-client`, que ejecuta el comando Java del perfil | Compilar el JAR, configurar el perfil y las variables, y arrancar `tunnel-client`; después seleccionar el túnel en ChatGPT |
  38. - **STDIO local:** configuras el comando; el cliente arranca y administra su propio proceso MCP. No debes ejecutar otro `java -jar` manualmente en una terminal para ese cliente: no se conectaría a ese proceso independiente. Cada cliente local tiene su propia instancia del MCP y su propia sesión del SDK.
  39. - **HTTP:** arrancas el servidor primero y lo dejas funcionando. El cliente solo se conecta a una URL; no ejecuta Java. Varios clientes autorizados pueden compartir esa instancia, que actúa sobre una sola empresa Siigo.
  40. - **ChatGPT con el túnel del ejemplo:** tú arrancas `tunnel-client`; este inicia el MCP por STDIO. ChatGPT se conecta al túnel y no inicia directamente un proceso Java en tu equipo. Mantener el túnel activo es necesario para usar sus herramientas.
  41. En los tres casos, el proceso Java recibe las credenciales por entorno y el SDK gestiona el token Siigo. Cerrar una instancia descarta su sesión en memoria; la siguiente instancia obtiene un token mediante el SDK cuando lo necesita.
  42. ## Conectar un cliente local: STDIO
  43. **El cliente arranca el MCP automáticamente al conectar.** STDIO es el transporte predeterminado.
  44. Antes de abrir o conectar el cliente:
  45. 1. Compilar el JAR y comprobar que existe en la ruta que se configurará.
  46. 2. Indicar en el cliente el ejecutable Java 21, la ruta absoluta del JAR y las tres variables de credenciales.
  47. 3. Abrir, reiniciar o reconectar el cliente para que ejecute ese comando y descubra las herramientas. No iniciar un servidor Java aparte para esta modalidad.
  48. En un cliente que admita la estructura `mcpServers`:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "siigo": {
  53. "command": "java",
  54. "args": ["-jar", "/ruta/absoluta/siigo-mcp-server-1.0.0-SNAPSHOT.jar"],
  55. "env": {
  56. "SIIGO_PARTNER_ID": "<partner-id>",
  57. "SIIGO_USERNAME": "<usuario-api>",
  58. "SIIGO_ACCESS_KEY": "<access-key>"
  59. }
  60. }
  61. }
  62. }
  63. ```
  64. Usar el soporte de secretos/entorno del cliente para los valores reales. La sintaxis para referenciar variables o secretos depende de cada host; los marcadores del ejemplo no se expanden automáticamente. Si el cliente hereda las tres variables, se puede omitir `env`. Usar una ruta absoluta al ejecutable Java 21 si el host no tiene configurado `PATH`.
  65. El servidor mantiene STDOUT libre de banners y logs: solo mensajes JSON-RPC MCP. Al cerrar stdin, cierra el servidor y el SDK.
  66. ## Conectar por Streamable HTTP en una red privada
  67. **Tú o un servicio de tu infraestructura arrancan el MCP antes de conectar los clientes.** El cliente HTTP no ejecuta el JAR y no inicia el servidor si está detenido.
  68. Configurar en el equipo del servidor las tres credenciales Siigo y estas opciones adicionales:
  69. | Variable | Valor / predeterminado |
  70. |---|---|
  71. | `SIIGO_MCP_TRANSPORT` | `http` (`stdio` por defecto) |
  72. | `SIIGO_MCP_HOST` | Dirección de escucha; `127.0.0.1` por defecto |
  73. | `SIIGO_MCP_PORT` | `8080` |
  74. | `SIIGO_MCP_HTTP_TOKEN` | Secreto de al menos 32 caracteres para autenticar **clientes MCP**, independiente del token Siigo |
  75. | `SIIGO_MCP_ALLOWED_HOSTS` | Nombres Host permitidos, separados por comas; por defecto `localhost,127.0.0.1,[::1]` |
  76. | `SIIGO_MCP_ALLOWED_ORIGINS` | Orígenes de navegador permitidos, separados por comas; ninguno por defecto. Los clientes sin Origin pueden conectarse |
  77. Orden de arranque:
  78. 1. Compilar el JAR y configurar en el entorno del servidor las tres credenciales Siigo y `SIIGO_MCP_HTTP_TOKEN`.
  79. 2. Ejecutar el comando siguiente en una terminal que permanecerá abierta, o configurar un servicio interno que mantenga ese proceso en ejecución.
  80. 3. Con el servidor ya funcionando, configurar la URL y el bearer MCP en cada cliente y conectar. Si el servidor se detiene, los clientes no podrán usar sus herramientas hasta que vuelva a arrancar.
  81. ```sh
  82. SIIGO_MCP_TRANSPORT=http java -jar target/siigo-mcp-server-1.0.0-SNAPSHOT.jar
  83. ```
  84. Las tres credenciales Siigo y `SIIGO_MCP_HTTP_TOKEN` deben estar configuradas antes de ejecutar ese comando. Endpoint: `http://127.0.0.1:8080/mcp`. El cliente debe enviar `Authorization: Bearer <SIIGO_MCP_HTTP_TOKEN>` en todas las solicitudes, incluidas las de sesión. La ruta soporta POST, GET y DELETE del transporte MCP; borrar una sesión HTTP no borra documentos Siigo.
  85. El transporte negocia el protocolo MCP de la familia `2025-11-25` y revisiones anteriores admitidas por el SDK oficial. No implementa el servidor del protocolo `2026-07-28` en este primer alcance. Si otro equipo de la red privada necesita conectarse, usar HTTPS en el punto de entrada interno y configurar los Host/Origin admitidos. El endpoint debe permanecer privado; estas opciones no autorizan su publicación en Internet. Esta versión **no implementa un authorization server OAuth ni discovery OAuth**: los clientes remotos que exigen OAuth requieren una capa de autorización compatible. No afirmar compatibilidad directa con un host concreto sin probar su configuración.
  86. `127.0.0.1` siempre se refiere al equipo donde se ejecuta el cliente. El ejemplo funciona cuando cliente y servidor están en el mismo equipo. Para equipos distintos dentro de una red privada, configurar `SIIGO_MCP_HOST` con la dirección privada de escucha, autorizar el nombre interno en `SIIGO_MCP_ALLOWED_HOSTS` y usar una URL HTTPS interna accesible para el cliente. Mantener la restricción de no exponerlo públicamente a Internet.
  87. Una instancia utiliza **una sola cuenta/empresa Siigo**. Todos los clientes autorizados de esa instancia actúan sobre esa misma empresa. Para empresas o políticas diferentes, ejecutar instancias separadas; no compartir esta configuración global como si fuera aislamiento multiempresa.
  88. ## Ejemplos por cliente: ChatGPT, Claude y OpenCode
  89. Los siguientes ejemplos son instrucciones de configuración; no implican que se haya conectado ninguna cuenta. Compilar el JAR primero, usar Java 21 y definir las credenciales Siigo en el entorno del proceso que lo arranca. El SDK conserva la gestión del token en todos los casos.
  90. | Cliente | Conexión del ejemplo | Configuración |
  91. |---|---|---|
  92. | ChatGPT web | Secure MCP Tunnel → STDIO local | Perfil de `tunnel-client` y plugin en ChatGPT |
  93. | Claude Desktop | STDIO local | `claude_desktop_config.json`, ejemplo de la sección anterior |
  94. | Claude Code | STDIO local | `.mcp.json` o CLI |
  95. | OpenCode V2 | STDIO local o Streamable HTTP | `opencode.jsonc`, bajo `mcp.servers` |
  96. ### ChatGPT: servidor privado mediante Secure MCP Tunnel
  97. **Quién arranca el MCP:** `tunnel-client`, al ejecutar el comando Java definido en su perfil. **Qué arrancas tú primero:** el proceso `tunnel-client`; no un servidor Java separado para este ejemplo STDIO.
  98. Antes de conectar ChatGPT:
  99. 1. Compilar el JAR e instalar `tunnel-client` según la guía oficial enlazada abajo.
  100. 2. Preparar el túnel, el perfil y las variables en el entorno del proceso `tunnel-client`, como se detalla a continuación.
  101. 3. Iniciar `tunnel-client run`, comprobar que la conexión esté lista y dejarlo funcionando. Solo después seleccionar el túnel en ChatGPT.
  102. ChatGPT no ejecuta directamente `java -jar`. Una opción documentada por OpenAI es [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels), que permite enlazar el proceso STDIO privado. Requiere acceso a Tunnels en la organización OpenAI y un `tunnel-client` instalado según esa guía; la disponibilidad depende de los permisos de la cuenta.
  103. Crear un túnel en Platform, asociarlo al workspace previsto y configurar la credencial de ejecución del cliente mediante su mecanismo seguro/entorno (`CONTROL_PLANE_API_KEY`). Guardar el identificador, que no es la access key Siigo, en `SIIGO_MCP_TUNNEL_ID`. Las tres variables `SIIGO_*` de credenciales deben estar disponibles para el proceso Java hijo.
  104. ```sh
  105. tunnel-client init \
  106. --sample sample_mcp_stdio_local \
  107. --profile siigo \
  108. --tunnel-id "$SIIGO_MCP_TUNNEL_ID" \
  109. --mcp-command "java -jar /ruta/absoluta/siigo-mcp-server-1.0.0-SNAPSHOT.jar"
  110. tunnel-client doctor --profile siigo --explain
  111. SIIGO_MCP_TRANSPORT=stdio tunnel-client run --profile siigo
  112. ```
  113. Mantener ese proceso activo durante el uso. Consultar `tunnel-client help quickstart` si cambia la sintaxis de la versión instalada. El túnel tiene sus propios límites de tiempo/tamaño; para períodos grandes, preferir consultas paginadas.
  114. En ChatGPT web, siguiendo [Add custom MCP server](https://developers.openai.com/api/docs/guides/custom-mcp-server):
  115. 1. Abrir **Plugins**, pulsar **+ → Add custom MCP server**.
  116. 2. Nombre: **Siigo GLD Consulting**. En **Connection**, seleccionar **Tunnel** y el túnel configurado.
  117. 3. Para este proceso STDIO, elegir **No authentication** a nivel del MCP: el acceso al túnel lo controla OpenAI. No publicar el endpoint HTTP de Siigo MCP sin su protección para imitar esta opción.
  118. 4. Revisar el acceso solicitado, crear el plugin e instalarlo. En un chat, seleccionarlo con `@` y pedir: «Consulta las facturas de compra entre el 1 y el 31 de agosto de 2026 usando Siigo GLD Consulting».
  119. Este proyecto no ofrece un modo de despliegue público. Para conectar ChatGPT, mantener el servidor privado y utilizar el túnel descrito arriba. ChatGPT no admite una API key personalizada como sustituto de OAuth; `SIIGO_MCP_HTTP_TOKEN` no se pega en el formulario como si fuera una credencial Siigo. Ver [autenticación de plugins](https://developers.openai.com/plugins/build/auth). El túnel privado no equivale a publicar el endpoint ni el plugin en un directorio público.
  120. ### Claude Desktop
  121. **Quién arranca el MCP:** Claude Desktop. No hay que dejar Java ejecutándose antes en una terminal.
  122. Antes de conectar:
  123. 1. Compilar el JAR y localizar las rutas absolutas de Java 21 y del JAR.
  124. 2. Preparar la configuración y las variables del proceso Java con el bloque STDIO descrito abajo.
  125. 3. Cerrar y volver a abrir Claude Desktop para que inicie su MCP y descubra las herramientas.
  126. En **Settings → Developer → Edit Config**, integrar el bloque `mcpServers.siigo` del [ejemplo STDIO](examples/stdio-client.json) con la configuración existente. Ubicaciones habituales:
  127. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`.
  128. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`.
  129. Usar rutas absolutas a Java 21 y al JAR. Los campos `env` del ejemplo pasan valores al entorno del proceso Java; no añadir las credenciales a `args`. Los marcadores `<...>` deben reemplazarse mediante la configuración privada del host; no son referencias automáticas a variables del shell. Una app abierta desde la interfaz gráfica puede no heredar variables exportadas en una terminal.
  130. Cerrar y volver a abrir Claude Desktop, comprobar el servidor en sus ajustes de desarrollador y solicitar una consulta de lectura. El archivo del ejemplo no es la configuración de Claude web. Referencia: [conexión local en la documentación oficial MCP](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
  131. ### Claude Code
  132. **Quién arranca el MCP:** Claude Code, al conectar el servidor registrado por STDIO. No iniciar un servidor Java aparte.
  133. Antes de conectar, compilar el JAR, preparar las credenciales en el entorno que iniciará Claude Code y registrar el servidor mediante `.mcp.json` o el comando CLI. Después abrir o reconectar Claude Code y comprobarlo con `/mcp`.
  134. Con las credenciales exportadas en el entorno desde el que se ejecuta Claude Code, agregar a `.mcp.json`:
  135. ```json
  136. {
  137. "mcpServers": {
  138. "siigo": {
  139. "type": "stdio",
  140. "command": "java",
  141. "args": ["-jar", "/ruta/absoluta/siigo-mcp-server-1.0.0-SNAPSHOT.jar"],
  142. "env": {
  143. "SIIGO_PARTNER_ID": "${SIIGO_PARTNER_ID}",
  144. "SIIGO_USERNAME": "${SIIGO_USERNAME}",
  145. "SIIGO_ACCESS_KEY": "${SIIGO_ACCESS_KEY}",
  146. "SIIGO_MCP_TRANSPORT": "stdio"
  147. }
  148. }
  149. }
  150. }
  151. ```
  152. Claude Code sí documenta la expansión `${VARIABLE}`. Como alternativa, si hereda las tres credenciales y no se ha configurado el transporte HTTP:
  153. ```sh
  154. claude mcp add --transport stdio --scope user siigo -- java -jar /ruta/absoluta/siigo-mcp-server-1.0.0-SNAPSHOT.jar
  155. claude mcp list
  156. ```
  157. Revisar el servidor con `/mcp` dentro de Claude Code. Referencia: [MCP en Claude Code](https://code.claude.com/docs/en/mcp). La forma de expansión anterior no se debe copiar sin cambios a otros clientes.
  158. ### OpenCode V2: local
  159. **Quién arranca el MCP:** OpenCode, porque la entrada usa `type: "local"`. No hace falta iniciar Java antes.
  160. Antes de conectar, compilar el JAR, configurar su ruta absoluta y las variables en el entorno de OpenCode. Guardar la configuración siguiente y abrir o reconectar OpenCode; este iniciará el proceso MCP.
  161. Crear o integrar en `opencode.jsonc` del proyecto (o `~/.config/opencode/opencode.jsonc` para todo el usuario):
  162. ```json
  163. {
  164. "$schema": "https://opencode.ai/config.json",
  165. "mcp": {
  166. "servers": {
  167. "siigo": {
  168. "type": "local",
  169. "command": ["java", "-jar", "/ruta/absoluta/siigo-mcp-server-1.0.0-SNAPSHOT.jar"],
  170. "protocol": "legacy",
  171. "environment": {
  172. "SIIGO_PARTNER_ID": "{env:SIIGO_PARTNER_ID}",
  173. "SIIGO_USERNAME": "{env:SIIGO_USERNAME}",
  174. "SIIGO_ACCESS_KEY": "{env:SIIGO_ACCESS_KEY}",
  175. "SIIGO_MCP_TRANSPORT": "stdio"
  176. }
  177. }
  178. }
  179. }
  180. }
  181. ```
  182. Las variables deben existir en el entorno que inicia OpenCode. V2 usa `mcp.servers`; los ejemplos antiguos de V1 colocaban los servidores directamente bajo `mcp`. `protocol: legacy` selecciona la familia MCP implementada por este servidor. Referencias: [MCP en OpenCode](https://opencode.ai/docs/mcp-servers/) y [ubicaciones y variables de configuración](https://opencode.ai/docs/config/).
  183. ### OpenCode V2: HTTP
  184. **Quién arranca el MCP:** tú o el servicio interno que lo hospeda. Con `type: "remote"`, OpenCode solo se conecta a la URL y no arranca Java.
  185. Antes de conectar:
  186. 1. Seguir el [orden de arranque HTTP](#conectar-por-streamable-http-en-una-red-privada) y dejar el servidor funcionando.
  187. 2. Configurar en el entorno de OpenCode `SIIGO_MCP_HTTP_TOKEN` con el mismo bearer MCP que usa el servidor. Las credenciales Siigo solo se configuran en el servidor.
  188. 3. Guardar la configuración de URL siguiente y abrir o reconectar OpenCode. Mantener el proceso del servidor activo durante su uso.
  189. Con el servidor ya ejecutándose en modo HTTP, el cliente solo necesita el bearer de acceso **MCP**; las credenciales Siigo permanecen en el servidor:
  190. ```json
  191. {
  192. "$schema": "https://opencode.ai/config.json",
  193. "mcp": {
  194. "servers": {
  195. "siigo": {
  196. "type": "remote",
  197. "url": "http://127.0.0.1:8080/mcp",
  198. "protocol": "legacy",
  199. "oauth": false,
  200. "headers": {
  201. "Authorization": "Bearer {env:SIIGO_MCP_HTTP_TOKEN}"
  202. }
  203. }
  204. }
  205. }
  206. }
  207. ```
  208. Comprobar con `opencode mcp list` o `/mcps`. Para conectarse desde otro equipo de una red privada, usar una URL HTTPS interna y autorizar su Host en el servidor. Mantener el endpoint fuera del acceso público a Internet. No ejecutar `opencode mcp auth siigo` para este ejemplo: utiliza bearer estático, no OAuth. Ambos ejemplos se conservan como archivos en `examples/`.
  209. ## Ejecutar con Docker
  210. El [Dockerfile](Dockerfile) compila el proyecto con Maven y Java 21 en una etapa de construcción y copia el JAR a una imagen de ejecución Java 21. La aplicación se ejecuta con el usuario sin privilegios `10001:10001`. El contexto de construcción se limita mediante [.dockerignore](.dockerignore); las credenciales se proporcionan al arrancar, no durante el build.
  211. ### Construir la imagen
  212. Con Docker Engine o Docker Desktop en funcionamiento, ejecutar desde la raíz del repositorio:
  213. ```sh
  214. docker build -t gldconsulting/siigo-mcp-server:local .
  215. ```
  216. No necesitas tener Java ni Maven instalados en el host para esta construcción. La etapa Docker empaqueta el JAR; la suite completa de pruebas se ejecuta con `./mvnw clean verify` fuera de la imagen. La etiqueta `:local` es una imagen construida en tu máquina, no una imagen que este proyecto haya publicado en Docker Hub.
  217. ### Docker por STDIO: el cliente arranca el contenedor
  218. En esta modalidad **el cliente MCP ejecuta `docker run` y mantiene abierto su stdin**. No debes dejar un contenedor STDIO separado funcionando antes de conectar: cada cliente crea y administra su propio contenedor. La imagen debe estar construida y las tres credenciales deben estar disponibles en el entorno del cliente.
  219. El comando que ejecutará el cliente es:
  220. ```sh
  221. docker run --rm -i \
  222. --env SIIGO_PARTNER_ID \
  223. --env SIIGO_USERNAME \
  224. --env SIIGO_ACCESS_KEY \
  225. gldconsulting/siigo-mcp-server:local
  226. ```
  227. Usar `-i`, sin `-t`: el terminal virtual puede alterar el intercambio JSON-RPC. No se publican puertos para STDIO. Los flags `--env NOMBRE` toman el valor del entorno del proceso Docker; no incluyen el secreto en los argumentos.
  228. Por ejemplo, en un cliente con formato `mcpServers` y las tres variables ya heredadas:
  229. ```json
  230. {
  231. "mcpServers": {
  232. "siigo": {
  233. "command": "docker",
  234. "args": [
  235. "run", "--rm", "-i",
  236. "--env", "SIIGO_PARTNER_ID",
  237. "--env", "SIIGO_USERNAME",
  238. "--env", "SIIGO_ACCESS_KEY",
  239. "gldconsulting/siigo-mcp-server:local"
  240. ]
  241. }
  242. }
  243. }
  244. ```
  245. Si el cliente gráfico no hereda las credenciales, configurarlas con su mecanismo privado de entorno/secretos, igual que en los ejemplos Java. Para Claude Code u OpenCode, conservar el formato propio de cada cliente y sustituir el comando Java por el comando Docker anterior. Al cerrar stdin, el MCP termina y `--rm` elimina ese contenedor.
  246. ### Docker por HTTP interno: tú arrancas el contenedor primero
  247. Definir previamente las tres credenciales y `SIIGO_MCP_HTTP_TOKEN` en el entorno de tu terminal. Después ejecutar:
  248. ```sh
  249. docker run --rm -d --name siigo-mcp \
  250. -p 127.0.0.1:8080:8080 \
  251. --env SIIGO_PARTNER_ID \
  252. --env SIIGO_USERNAME \
  253. --env SIIGO_ACCESS_KEY \
  254. --env SIIGO_MCP_HTTP_TOKEN \
  255. --env SIIGO_MCP_TRANSPORT=http \
  256. --env SIIGO_MCP_HOST=0.0.0.0 \
  257. gldconsulting/siigo-mcp-server:local
  258. ```
  259. `0.0.0.0` es la escucha **dentro del contenedor**; la publicación `127.0.0.1:8080:8080` limita el puerto al equipo host. Mantener esa publicación local: este MCP no está diseñado para exposición pública a Internet. Configurar después los clientes HTTP con `http://127.0.0.1:8080/mcp` y el bearer MCP. En esta modalidad los clientes no arrancan Docker ni Java.
  260. Mantener el contenedor funcionando durante el uso. Para detenerlo:
  261. ```sh
  262. docker stop siigo-mcp
  263. ```
  264. Para restringir herramientas se pueden añadir `--env SIIGO_MCP_READ_ONLY=true` o `--env SIIGO_MCP_TOOL_GROUPS=purchases,journals,catalogs` a cualquiera de los comandos. El token Siigo sigue siendo obtenido, almacenado en memoria y renovado exclusivamente por el SDK dentro del contenedor.
  265. Referencias: [construcción multi-stage](https://docs.docker.com/build/building/multi-stage/) y [opciones de docker run](https://docs.docker.com/reference/cli/docker/container/run/).
  266. ## Herramientas
  267. El [inventario](docs/tools.md) lista las herramientas de los 14 grupos: productos, terceros, facturas, cotizaciones, notas crédito, compras, comprobantes contables, comprobantes de pago, documentos soporte, recibos de caja, categorías de inventario, catálogos, reportes y webhooks.
  268. El registro parte de una lista explícita de interfaces del SDK. Excluye autenticación, transporte HTTP arbitrario y sobrecargas de conveniencia duplicadas. Cada herramienta publica su esquema JSON con parámetros propios, modelos anidados y nombres de campo Siigo en `snake_case`.
  269. Ejemplos de argumentos de herramientas —el host MCP envía estas llamadas; no son comandos del shell—:
  270. **Compras por página:** `siigo_get_purchases`
  271. ```json
  272. {"filter":{"page":1,"page_size":25}}
  273. ```
  274. **Compras de agosto de 2026:** `siigo_get_purchases_by_date`
  275. ```json
  276. {"from":"2026-08-01","to":"2026-08-31","filter":{"page_size":100}}
  277. ```
  278. **Compatibilidad de `page_size`:** en una consulta real de compras, Siigo devolvió `page_size=10` al solicitar `2`; con `25` y `100` respetó el tamaño pedido. Usar `25` o `100` para los recorridos completos. El SDK verifica que la paginación recibida sea coherente con la solicitada y devuelve un error ante discrepancias, en lugar de entregar un listado parcial.
  279. **Comprobantes de agosto de 2026:** `siigo_get_journals_by_date`
  280. ```json
  281. {"from":"2026-08-01","to":"2026-08-31","filter":{"page_size":100}}
  282. ```
  283. Estas dos consultas recorren todas las páginas y filtran localmente la fecha contable inclusiva con el SDK. No se limitan a la primera página. Si falta una página o los resultados son inconsistentes, devuelven un error. Siigo ha ignorado filtros remotos de fecha y `document_id` en journals: no interpretar una respuesta como prueba de que esos filtros se aplicaron. Para fechas usar las herramientas `*_by_date`; verificar el tipo de documento en los resultados si se necesita restringirlo.
  284. **Crear un comprobante contable:** `siigo_create_journal`
  285. ```json
  286. {
  287. "idempotency_key":"EjemploComprobanteAgo2026",
  288. "request":{
  289. "document":{"id":123},
  290. "date":"2026-08-31",
  291. "items":[
  292. {"account":{"code":"530505","movement":"Debit"},"value":1000.00},
  293. {"account":{"code":"111005","movement":"Credit"},"value":1000.00}
  294. ]
  295. }
  296. }
  297. ```
  298. Ese payload es ilustrativo: obtener los IDs, cuentas, terceros y demás campos requeridos de la empresa antes de escribir. El servidor no los deduce ni valida reglas contables de Siigo; Siigo valida su contrato. Los importes se manejan con `BigDecimal` y las fechas contables con `LocalDate`. Los modelos admiten extensiones del proveedor tal como lo hace el SDK.
  299. Las respuestas incluyen JSON en `content` y en `structuredContent.data`. Los fallos usan `isError=true`; conservan el estado HTTP cuando existe y ocultan credenciales. Ante una escritura con resultado incierto, comprobar el documento en Siigo antes de reintentar; no generar otra clave de idempotencia para repetirla a ciegas. Los errores nunca se convierten en resultados vacíos exitosos.
  300. ## Alcance y ejecución de escrituras
  301. Las escrituras están disponibles por defecto, con anotaciones MCP de lectura, destrucción e idempotencia. El host debe recabar la intención/aprobación del usuario para las operaciones que cambian Siigo; las anotaciones son información para el host, no una barrera de autorización independiente. El servidor no añade un segundo ciclo de confirmación en cada método.
  302. Para exponer solo consultas, definir `SIIGO_MCP_READ_ONLY=true`: las herramientas de escritura ni siquiera aparecen. Para reducir el catálogo, `SIIGO_MCP_TOOL_GROUPS=purchases,journals,catalogs`. Los grupos son los nombres del inventario, separados por comas. Los desconocidos impiden iniciar el servidor.
  303. Otras opciones: `SIIGO_API_URL` cambia la URL del SDK (HTTPS, o HTTP en loopback para pruebas); `SIIGO_API_TIMEOUT_SECONDS=120` configura espera de lectura/escritura; `SIIGO_MCP_REQUEST_TIMEOUT_SECONDS=600` limita la operación MCP. Para grandes volúmenes preferir consultas por página. El MCP no trunca respuestas silenciosamente; el SDK conserva sus controles de paginación. Las respuestas completas pueden ser grandes, especialmente PDF/XML o `get_all_*`.
  304. ## Desarrollo y pruebas
  305. ```sh
  306. ./mvnw clean verify
  307. ```
  308. Las pruebas no usan credenciales reales ni requieren una cuenta Siigo. Cubren contratos de herramientas, configuración por entorno, autenticación y renovación a través del SDK, paginación y período contable, creación de journals, precisión decimal, errores sin secretos, ausencia de reintentos de escrituras, y conexiones MCP reales contra el JAR empaquetado (STDIO) y el servidor HTTP local.
  309. ```text
  310. src/main/java/co/gldconsulting/siigo/mcp/
  311. SiigoMcpServer.java # Startup, SDK y transportes
  312. config/ # Environment variables
  313. tool/ # Registro, esquemas, argumentos y resultados
  314. transport/ # Acceso HTTP al MCP
  315. src/test/java/ # Pruebas unitarias y de integración
  316. ```
  317. El workflow de GitHub Actions compila y prueba con Java 21 y conserva el JAR. No despliega, no crea releases ni publica en Maven Central.
  318. ## Referencias
  319. - [SDK de Siigo de GLD Consulting](https://github.com/gldconsulting/siigo-api-sdk-java).
  320. - [SDK oficial de MCP Java: servidor y transportes](https://java.sdk.modelcontextprotocol.io/latest/server/).
  321. - [Dependencias oficiales MCP Java](https://java.sdk.modelcontextprotocol.io/latest/quickstart/).
  322. - [Documentación oficial de Siigo](https://siigoapi.docs.apiary.io/).
  323. Código abierto bajo [licencia MIT](LICENSE). Contribuciones e incidencias: [GitHub](https://github.com/gldconsulting/siigo-mcp-server-java).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.