Genexus MCP

Servidor MCP de GeneXus 18 para Claude, Cursor y agentes de IA: lee, edita y analiza objetos KB (transacciones, paneles web, procedimientos, SDT) a través del Protocolo de Contexto de Modelo.

GitHub
36
Prueba este MCPPatrocinado

Documentación

GeneXus MCP Server — GeneXus multiversión para Claude, Cursor y Agentes de IA

npm version npm downloads License: MIT SafeSkill 85/100 MCP Badge

¿Hablás español? → Guía de inicio en español Fala português? → Guia de início em português ¿Atascado? → Guía de solución de problemas

GeneXus MCP Server permite que los agentes de IA — Claude Desktop, Claude Code, Cursor, Antigravity y cualquier cliente compatible con MCP — lean, editen, analicen y refactoricen objetos dentro de una Knowledge Base compatible con el SDK nativo seleccionado o el controlador de compatibilidad heredado. Las rutas del SDK nativo funcionan con el SDK real de GeneXus y las rutas heredadas usan adaptadores explícitos de reflexión/COM; ninguna ruta depende de una copia analizada de la KB.

En la práctica: apuntas el MCP a tu KB y luego le pides a tu asistente de IA cosas como "lista todas las transacciones con el atributo CustomerId", "agrega una regla a la transacción Order que valide el total" o "refactoriza este procedimiento para usar el nuevo SDT" — y lo hace.

Soporte multiversión de GeneXus

La misma distribución de MCP soporta las versiones principales oficiales del SDK nativo listadas en el documento de compatibilidad generado. También incluye compatibilidad básica de mejor esfuerzo para las versiones heredadas listadas allí mediante controladores separados; esa ruta no equivale al soporte completo del SDK nativo. Un proceso puede enrutar cada KB declarada a su propio SDK/controlador; --gx sigue siendo el predeterminado global conveniente para una configuración de una sola versión principal. Los comandos a continuación son ejemplos de cómo cambiar la configuración existente:

npx genexus-mcp@latest init --kb "C:\KBs\KBTeste17" --gx "C:\Program Files (x86)\GeneXus\GeneXus17Trial"
# To switch this MCP configuration to GX18:
npx genexus-mcp@latest init --kb "C:\KBs\MyGX18KB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"

Después de cambiar el SDK o la KB, reinicia completamente el cliente de IA para que recargue el proceso MCP y sus esquemas de herramientas. Si GX17 y GX18 deben ejecutarse simultáneamente, usa configuraciones y puertos MCP separados.

Las KB clásicas GX8/GX9 se pueden abrir sin cambiar el predeterminado global GX18 declarando su controlador e instalación por KB (el Gateway acepta tanto la lista como las formas del catálogo de objetos):

{
  "Environment": {
    "KBs": {
      "SECT80": {
        "Path": "D:\\GX80\\SECT",
        "Driver": "com-gxpublic",
        "InstallationPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\gxw80",
        "Major": "8"
      }
    }
  }
}

La solicitud única equivalente es genexus_kb action=open con path, alias, driver: "com-gxpublic", installationPath y major: "8". GX8 usa el proveedor GXPublic de 32 bits registrado; el ProgID documentado .4 y el registro de compatibilidad instalado GXPubGXX.GXPublic(.5) son reconocidos. Las raíces clásicas de KB DAT se identifican por sus marcadores heredados (DATA001, GXSPC001, kbdata, ATTRIBUT.DAT o ATT.XPW).

init también lee la versión principal .gxw de la KB y los metadatos seleccionados GeneXus.exe. Se aborta antes de escribir config.json cuando las versiones principales entran en conflicto o una selección automática no puede verificarse. genexus-mcp doctor expone el mismo resultado que la verificación kb_sdk_compatibility. Para un fixture desechable, el harness de KB en vivo incluye una matriz basada en catálogo que verifica cada versión principal soportada contra un artefacto publicado.

El Gateway informa el SDK detectado a través de genexus_whoami:

  • geneXus.supportedMajors: versiones principales del SDK nativo validadas explícitamente desde el catálogo de versiones
  • geneXus.legacyMajors: versiones principales heredadas catalogadas manejadas por sus controladores de compatibilidad
  • geneXus.sdkCompatibility.supportLevel: native-sdk o basic-legacy para la instalación detectada
  • geneXus.matchedMajor: la versión principal detectada para la instalación configurada
  • geneXus.versionMatches: si la instalación detectada está en ese catálogo
  • geneXus.supportedMajor: conservado como el alias heredado de versión única para el principal del catálogo

El Worker aísla los miembros del SDK sensibles a la versión detrás de adaptadores de compatibilidad. Por ejemplo, los métodos auxiliares de Design System que difieren entre versiones principales del SDK se reemplazan campo por campo analizando las partes nativas Tokens y Styles cuando sea necesario. Los nombres de herramientas existentes, argumentos y formatos de configuración del cliente MCP no cambian.

Versiones principales del SDK soportadas: GeneXus 16, GeneXus 17, GeneXus 18 (SDK nativo). Compatibilidad básica heredada: GeneXus Evolution 3, GeneXus Evolution 2, GeneXus Evolution 1, GeneXus 15, GeneXus 9.0, GeneXus 8.0 vía com-gxpublic y dotnet-reflection (no la compilación del SDK nativo). SDK principal: GeneXus 18. Fuente de verdad: config/gx-versions.json.

Para agregar otra versión principal del SDK nativo en el futuro, agrégala al catálogo explícito supportedMajors solo después de compilar el Worker con ese SDK y pasar las pruebas enfocadas más una prueba de humo de KB en vivo. Esto evita que el servidor reclame compatibilidad con el SDK nativo basándose solo en una cadena de versión.

Compatibilidad básica heredada (no soporte del SDK nativo)

Cada versión heredada declarada actualmente en legacyMajors usa un controlador de mejor esfuerzo en lugar de la compilación del SDK nativo:

  • GeneXus Evolution 1 (10.1), Evolution 2 (10.2), Evolution 3 (10.3) y GeneXus 15: Impulsadas mediante reflexión en tiempo de ejecución (dotnet-reflection), adaptándose dinámicamente a tipos faltantes o diferencias estructurales (como KB sin módulos sin QualifiedName).
  • GeneXus 8.0 y GeneXus 9.0: Impulsadas a través de la superficie clásica GXPublic (com-gxpublic), detectadas desde gxw32.exe/gx.exe/gxdl32.dll y Knowledge Bases clásicas .gxi. GXPublic es una superficie OLE DB orientada a metadatos; esta ruta está intencionalmente limitada a operaciones básicas de metadatos/núcleo y no reclama paridad de edición de fuente del SDK nativo.
  • Degradación elegante: Las herramientas modernas que requieren funciones introducidas en versiones más recientes de GeneXus (como genexus_api, genexus_gam o genexus_module) devuelven errores estructurados UNSUPPORTED_IN_GENEXUS_VERSION que indican la versión mínima requerida en lugar de fallar de manera abrupta.

Esta ruta heredada está destinada a operaciones básicas del núcleo donde se implementa; no reclama la misma paridad de funciones que el contrato del SDK nativo para GeneXus 16, 17 y 18.

Compartir un Worker entre clientes MCP

El Gateway y el Worker del SDK de GeneXus tienen diferentes responsabilidades. Por defecto, Server.WorkerSharingMode es "isolated": cada Gateway posee su propio proceso Worker. Mantén ese modo cuando un agente necesite intencionalmente múltiples Workers independientes.

Cuando dos o más clientes MCP independientes necesiten trabajar en la misma KB física, establece WorkerSharingMode a "shared-host" en una configuración stdio-isolated:

{
  "ConfigSchemaVersion": 2,
  "GatewayMode": "stdio-isolated",
  "GeneXus": {
    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
    "WorkerExecutable": "C:\\path\\to\\GxMcp.Worker.exe"
  },
  "Server": {
    "HttpPort": 0,
    "McpStdio": true,
    "WorkerSharingMode": "shared-host"
  },
  "Environment": {
    "ResolutionPolicy": "strict",
    "KBs": [
      { "alias": "main", "path": "C:\\KBs\\YourKB" }
    ]
  }
}

shared-host comparte solo el Worker del SDK propiedad del broker por KB a través de adjuntos limitados de named pipes locales. Los Gateways permanecen independientes: sesiones MCP, autorización, selección de KB, cachés, seguimiento de solicitudes, cancelación, progreso, notificaciones y artefactos generados no cruzan el límite del proceso. El compartir se acepta solo cuando la KB física, el ejecutable del Worker, la instalación de GeneXus, el controlador y la versión principal objetivo son compatibles; una discrepancia falla de forma cerrada en lugar de adjuntarse al proceso SDK incorrecto.

Las escrituras llevan un propietario local del Gateway al Worker. El mismo objeto/parte no puede escribirse concurrentemente por dos clientes adjuntos, mientras que las escrituras a objetos distintos pueden proceder independientemente a través del límite compartido del SDK. El Worker en sí mismo sigue siendo un proceso STA único, por lo que las llamadas que alcanzan el mismo SDK aún se serializan según lo requerido por GeneXus.

Para un adjunto compartido saludable, genexus_whoami y genexus_doctor informan el modo, clave de identidad, pipe, PIDs del host/Worker, generación, ID de adjunto, estado de conexión y el último diagnóstico de inicio/fallo. Cuando algo falla, inspecciona worker.diagnostics y workerHealth antes de reiniciar o eliminar el estado local; estos campos distinguen configuración/identidad, mutex o registro, pipe/handshake, inicio, salida/reinicio del hijo, TTL y fallos de marco.

Consulta Propiedad del Worker para el contrato del ciclo de vida y el benchmark de Worker compartido para los resultados medidos de smoke de dos clientes y contrapresión.

Qué puedes hacer con él

Un mapa rápido de lo que el agente puede hacer contra tu KB real a través de las 50 herramientas (detalles en Superficie de herramientas):

ÁreaQué puede hacer el agente
🔎 ExplorarBuscar y listar objetos, leer cualquier parte (fuente, reglas, eventos, estructura, documentación, XML de patrón), inspeccionar metadatos y llamadores, búsqueda regex en fuente, ver el informe de navegación
✏️ Editar códigoEditar cualquier parte del objeto (modos full/patch/ops), CRUD de variables, formatear, crear y eliminar objetos, generar un Procedure a partir de un comando curl, editar y reconstruir llamadores en una sola operación
🗄️ Autorar el modelo de datosEstructura de transacción (DSL), índices únicos/no únicos (crear y eliminar), fórmulas y subtipos de atributos, atributos de Descripción/Imagen de nivel, valores de enumeración de Dominio, carpetas y módulos, relaciones tabla↔transacción y detección de atributos redundantes
🧩 Autorar otros objetosMétodos y propiedades de External Object, opciones de Menú, objetos de API REST, patrones WorkWithPlus / WorkWith, referencias tipadas del generador .NET
🎨 UI y WorkWithPlusLectura/escritura completa del XML de patrón (controles, acciones, grillas, órdenes, grupos), clases y estilos de tema, ediciones nativas de WebForm/layout, catálogo de controles y tokens/clases/imágenes del design system, verificación con navegador headless
🔬 AnalizarAnálisis de impacto/dependencias, métricas de complejidad y código, nomenclatura, explicar-qué-hace-esto, actividad/actualidad de la KB, vista previa de impacto de reorg/DDL, escaneo de seguridad nativo, verificación de desviación de esquema
🛠️ Compilar, probar y desplegarCompilar (completa o rápida compile_check), validar, reorg, indexar, ejecutar pruebas nativas GXtest, desplegar la aplicación (objetivos + despliegue)
🔀 Refactorizar y compararRenombrar en toda la KB, extraer procedimiento, comparar y fusionar objetos (paridad con IDE)
🌿 Versionado, transferencia y equiposVersiones/ramas del modelo de KB, exportación/importación XPZ real (consciente de dependencias), sincronización GXserver (Team Development) + pipelines de CI, historial tipo git, trabajo paralelo multi-KB
🔐 SeguridadAprovisionamiento de GAM / seguridad integrada, auditoría de seguridad de KB + Security Scanner nativo

El soporte del SDK nativo funciona a través del SDK nativo de GeneXus — las mismas rutas de código que usa el IDE — por lo que las ediciones son reales y validadas, no trucos de texto sobre archivos de KB. El soporte heredado usa el controlador de reflexión o COM listado en el catálogo y degrada las herramientas modernas no soportadas explícitamente.

Requisitos previos

Antes de comenzar, asegúrate de tener:

  • ✅ Windows (GeneXus es solo para Windows)
  • ✅ Una instalación de GeneXus soportada instalada localmente: GeneXus 16, 17 o 18 para soporte del SDK nativo, o una instalación heredada catalogada para compatibilidad básica (consulta docs/generated/supported-versions.md; pasa otra ruta de instalación explícitamente cuando sea necesario)
  • ✅ GeneXus 18 instalado localmente para la ruta principal del SDK nativo; otras versiones nativas y heredadas catalogadas también son soportadas según su controlador listado
  • ✅ Una Knowledge Base creada con una versión principal nativa o heredada soportada de GeneXus y abierta al menos una vez en el IDE (para que esté inicializada)
  • ✅ Node.js 22+ — verifica con node --version en una terminal; instala desde nodejs.org si falta
  • ✅ Un cliente de IA compatible con MCP — Claude Desktop, Claude Code, Cursor, Antigravity, etc.

No necesitas clonar este repositorio ni instalar nada globalmente — npx lo maneja.

¿Nunca usaste una terminal antes? Presiona Win+R, escribe powershell, presiona Enter. Esa es tu terminal.

Inicio rápido (3 pasos, ~5 minutos)

Encuentra tus dos rutas primero

Antes de ejecutar el instalador, anota lo siguiente:

  1. Carpeta de instalación de GeneXus — donde vive GeneXus.exe. Usualmente C:\Program Files (x86)\GeneXus\GeneXus18.
  2. Tu carpeta de KB — la carpeta raíz de tu Knowledge Base (contiene el archivo .gx y subcarpetas como Model/, WebSpa/).

¿No estás seguro de dónde vive tu KB? Ábrela en GeneXus y revisa la barra de título, o busca en File → Recent.

Paso 1 — Ejecuta el instalador

Abre una terminal y ejecuta, reemplazando las rutas con tu carpeta de KB y tu instalación de GeneXus:

npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"

¿Prefieres el asistente? Ejecuta npx genexus-mcp@latest init --interactive y responde las indicaciones.

Lo que verás (tarda ~30 segundos la primera vez, más rápido en ejecuciones posteriores):

  1. npx descarga el paquete.
  2. El instalador verifica que las rutas existan y que GeneXus esté presente.
  3. Detecta automáticamente qué clientes de IA tienes instalados y añade la configuración MCP a cada uno.
  4. Imprime un fragmento JSON al final — consérvalo por si necesitas configurar un cliente manualmente.
  5. Termina con 🎉 You are all set!.

En Windows, Antigravity se registra con el ejecutable de la puerta de enlace incluido en el paquete npm actual cuando ese artefacto está disponible, por lo que omite la cadena de arranque npx en cada negociación MCP. Esa ruta sigue al paquete en la caché de npx; después de una actualización, ejecuta npx genexus-mcp@latest clients add --clients antigravity nuevamente si genexus-mcp clients informa un lanzador obsoleto. Otros clientes conservan el lanzador npx genexus-mcp@latest a menos que uses el instalador de ruta fija a continuación.

Paso 2 — Registra el MCP en tu cliente de IA

El Paso 1 registra automáticamente todos los clientes compatibles que detecta, incluyendo Claude Desktop, Claude Code, Cursor, Antigravity, Gemini CLI, OpenCode, Codex CLI y VS Code. Si el tuyo no fue detectado, copia el fragmento JSON del Paso 1 en la configuración MCP de tu cliente manualmente. Consulta la guía de configuración del cliente si no estás seguro de dónde se encuentra ese archivo.

Paso 3 — Reinicia tu cliente de IA y luego prueba

Esta parte confunde a la mayoría: cierra por completo tu cliente de IA y vuelve a abrirlo. No solo la ventana — todo el proceso.

  • Claude Desktop: haz clic derecho en el ícono de la bandeja del sistema → Salir. Luego ábrelo nuevamente. (Cerrar la ventana no es suficiente.)
  • Claude Code: finaliza la sesión e inicia una nueva.
  • Cursor / Antigravity: cierra todas las ventanas y vuelve a abrir.
  • OpenCode: sal por completo y vuelve a abrirlo para que recargue opencode.json / opencode.jsonc.
  • Gemini CLI / Codex CLI: inicia un nuevo proceso o sesión.

Luego pega esta indicación:

"Usando el MCP de GeneXus, lista los primeros 5 objetos en mi KB y muestra nombre + tipo."

Lo que debería suceder:

  • La IA invoca la herramienta genexus_list_objects (algunas interfaces muestran "llamando herramienta…").
  • Unos segundos después, obtienes una lista de objetos de tu KB.

Si recibes una lista — has terminado. Salta a ¿Qué puedo preguntarle a la IA? para ideas.

Si la IA dice que no tiene una herramienta de GeneXus, o no sucede nada, ve a Solución de problemas — la mayoría de los problemas están cubiertos allí.

🤖 Deja que tu IA lo instale por ti

Si prefieres no ejecutar nada en la terminal tú mismo, pega esto en tu chat de IA:

Por favor, configura el servidor MCP de GeneXus. Ejecuta npx genexus-mcp@latest init --kb "<MY_KB_PATH>" --gx "<MY_GENEXUS_PATH>" en la terminal. Si aún no te he dicho mi ruta de GeneXus y mi ruta de KB, pregúntame primero. Una vez que tenga éxito, lee el bloque JSON que imprimió y agrégalo a la configuración de mi cliente MCP. Dime cuándo debo reiniciar el cliente para comenzar a usar las herramientas de GeneXus.

Reemplaza los marcadores de posición o deja que la IA te los pregunte.

Instalación corporativa (ruta fija, compatible con ASR)

Si tu máquina tiene Microsoft Defender ASR, SmartScreen u otra política de endpoint que bloquea binarios sin firmar, el flujo predeterminado de npx es problemático — npx almacena en caché el paquete bajo %LOCALAPPDATA%\npm-cache\_npx\<hash>\..., y el <hash> cambia según la versión, por lo que TI no puede incluir en la lista blanca una ruta estable sin un comodín sobre toda la caché de npm (lo cual es demasiado amplio).

Usa el instalador corporativo en su lugar. Extrae los binarios a un directorio estable y registra los clientes de IA para que inicien la puerta de enlace directamente desde allí — npx nunca está en la ruta de ejecución.

# One-liner — installs latest release, registers AI clients
iex (irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1)

# With explicit KB and GeneXus paths
$s = irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1
& ([scriptblock]::Create($s)) -Kb "C:\KBs\MyKB" -Gx "C:\Program Files (x86)\GeneXus\GeneXus18"

Ubicación de instalación:

  • Shell de administrador → C:\Tools\GenexusMCP\
  • Shell sin administrador → %LOCALAPPDATA%\Programs\GenexusMCP\

Rutas para dar a TI para la lista de exclusión de ASR / Defender:

<InstallDir>\GxMcp.Gateway.exe
<InstallDir>\worker\GxMcp.Worker.exe

Vuelve a ejecutar el mismo comando de una línea más tarde para actualizar — detecta la versión instalada (version.txt en el directorio de instalación) y descarga solo si hay una versión más reciente disponible. Usa -Force para reinstalar la misma versión, -Version v2.3.0 para fijar una etiqueta específica, -NoClient para omitir el registro del cliente de IA. Node.js 22+ debe estar instalado para el registro del cliente; sin él, el script aún extrae los binarios pero necesitarás editar la configuración del cliente (claude_desktop_config.json etc.) manualmente.

¿Qué puedo preguntarle a la IA?

Una vez instalado, esto es lo que se desbloquea. Prueba estos como tus primeras indicaciones:

Exploración

  • "Lista todos los objetos de tipo Procedure en el KB."
  • "Muéstrame el código fuente del procedimiento CalculateInvoiceTotal."
  • "Encuentra todas las transacciones que referencian el atributo CustomerId."

Edición

  • "Agrega una regla a la transacción Order: error('Total must be positive') si Total < 0."
  • "Agrega un nuevo atributo CreatedAt de tipo DateTime a la transacción Customer."
  • "Renombra la variable &qty a &quantity en el procedimiento CreateOrder."

Creación de modelo de datos (sin ida y vuelta al IDE)

  • "Haz que CustomerEmail sea único en la transacción Customer." (crea un índice único)
  • "Convierte CustomerBalance en una fórmula: sum(InvoiceAmount)."
  • "Agrega los valores de enumeración Active/Inactive/Pending al dominio Status."
  • "Agrega una propiedad apiKey y un método Connect(url) al objeto externo PaymentGateway."
  • "Agrega una opción de menú 'Customers' a MainMenu que abra CustomerWW."

Edición de patrón WorkWithPlus (control estructural y de temas completo)

  • "Agrega una pestaña tipada con variables, una acción y tablas responsivas anidadas a un WebPanel de WorkWithPlus."
  • "En WorkWithPlusOrder, agrega un botón 'Duplicate' a la vista de transacción junto a Save/Cancel/Delete."
  • "Agrupa los atributos de la transacción Customer en una sección 'Contact Info' con la clase de tema GroupTelaResp."
  • "En la lista de WorkWithPlusInvoice, agrega un nuevo ordenamiento por InvoiceDate descendente."
  • "Dale estilo al botón Save en WorkWithPlusOrder con buttonClass='btn ButtonGreen' y aplica BigTitle al encabezado del formulario."
  • "Elimina la acción Export de la cuadrícula de selección de WorkWithPlusReport."
  • "Lee la parte de Documentación de la transacción Customer y reescríbela en markdown."

Análisis

  • "Explica qué hace el procedimiento ProcessShipment." — genexus_analyze mode=explain es un envoltorio solo de compatibilidad y devuelve NotImplemented; usa mode=summary, mode=context o genexus_read para análisis y código fuente compatibles.
  • "¿Qué SQL genera la consulta en el WebPanel CustomerList?"
  • "Resume la estructura del módulo Sales."

Compilación y ciclo de vida

  • "Compila el KB e informa cualquier error."
  • "Ejecuta las pruebas unitarias y muéstrame cuáles fallaron."

El agente elige la herramienta correcta de las 50 herramientas que expone el MCP (lectura, edición, refactorización, análisis, compilación, creación de modelos de datos, automatización de diseño, BD/DDL, versionado, seguridad, vista previa de SQL, etc.). La lista completa de herramientas está en Superficie de herramientas a continuación.

Clientes de IA compatibles

Detectados y configurados automáticamente por el instalador:

ClienteConfiguración automáticaNotas
Claude Desktop✅Reinicio requerido después de la instalación
Claude Code (CLI)✅Recargar sesión
Cursor✅Reinicio requerido
Antigravity✅Puerta de enlace empaquetada directa; reinicio requerido; detectado incluso antes de que exista su configuración MCP
Gemini CLI✅—
OpenCode (CLI)✅Lee diseños MCP directos y anidados; reinicio requerido
Codex CLI✅Escribe ~/.codex/config.toml
VS Code / VS Code Insiders✅MCP nativo (User/mcp.json); reinicio requerido
OpenCode Desktop✅Comparte opencode.jsonc con OpenCode CLI; reinicio requerido
Cualquier cliente MCPManualUsa el fragmento JSON impreso por init

Ejecuta npx genexus-mcp clients en cualquier momento para ver qué agentes están instalados, cuáles tienen genexus registrado y si alguno apunta a un ejecutable de puerta de enlace obsoleto. Para (re)registrar específicos: npx genexus-mcp clients add --clients antigravity,vscode.

OpenCode Desktop

OpenCode Desktop comparte su archivo de configuración MCP (opencode.jsonc o opencode.json) con OpenCode CLI. Ejecutar genexus-mcp init --write-clients o genexus-mcp clients add --clients opencode-desktop registra automáticamente genexus18mcp en la configuración compartida. Después del registro, reinicia por completo OpenCode Desktop para que recargue su configuración MCP.

Solución de problemas

Primera parada para cualquier problema de "el agente no ve GeneXus": npx genexus-mcp clients (¿está registrado? ¿apunta a un ejecutable de puerta de enlace que aún existe?) y npx genexus-mcp doctor --mcp-smoke.

La mayoría de los problemas de instalación se dividen en unas pocas categorías — consulta TROUBLESHOOTING.md para soluciones:

  • El instalador no puede encontrar GeneXus o el KB
  • El cliente de IA no ve las herramientas de GeneXus después del reinicio
  • Errores de "Worker failed to start" / .NET 4.8
  • Errores de compilación del KB / artefactos bloqueados
  • Puerto 5000 ya en uso
  • Permisos en %LOCALAPPDATA%\GenexusMCP\
  • Antigravity solo muestra exit status 1 / 0xffffffff sin stderr útil

Cuando un lanzador stdio falla antes de que el cliente pueda retener stderr, el envoltorio escribe el último fallo en %LOCALAPPDATA%\GenexusMCP\logs\last-stdio-error.txt. Contiene la marca de tiempo UTC, el código de salida y la cola de stderr limitada. genexus-mcp doctor informa la misma ruta cuando hay un fallo anterior presente. Léelo antes de cambiar la instalación o usar una instalación global de npm; si el lanzador de Antigravity está obsoleto, vuelve a registrarlo con npx genexus-mcp@latest clients add --clients antigravity.

Diagnóstico de un fallo compartido de Worker

Si shared-host no se adjunta o se reinicia un Worker, ejecuta genexus_whoami y genexus_doctor desde el cliente afectado y conserva el bloque estructurado worker.diagnostics/workerHealth. La evidencia útil es el modo, la identidad, el PID del host/Worker, la generación, el estado de adjunción, el error de conexión y el diagnóstico de fallo — no solo el resumen final de no_worker o startup_failed. No elimines un archivo de registro de worker compartido mientras un host correspondiente siga en ejecución; el broker es dueño de ese ciclo de vida y los registros obsoletos se recuperan después de la validación de PID/marca de tiempo de inicio.

¿Sigue atascado? Abre un problema con la salida de npx genexus-mcp doctor --mcp-smoke y los campos de diagnóstico limitados anteriores. Redacta credenciales, tokens, cadenas de conexión y otros valores sensibles.

Superficie de herramientas

El worker expone 50 herramientas al enrutador MCP, agrupadas por capacidad a continuación. La mayoría son paraguas con un action (por ejemplo, genexus_db action=sql_ddl); los esquemas detallados viven en src/GxMcp.Gateway/tool_definitions.json.

Orientación y salud

  • genexus_whoami — contexto del KB, versión, salud del worker/índice/base de datos, verificación de autoactualización, sugerencias de próximos pasos
  • genexus_doctor — verificación de salud de conexión + instalación + caché
  • genexus_recipe — playbooks nombrados / macros autoextensibles
  • genexus_telemetry — observabilidad (métricas, latencia, errores)

Búsqueda y descubrimiento

  • genexus_query — búsqueda de objetos (prefijos name:, type:, usedby:, parent:, …)
  • genexus_list_objects — listado de objetos paginado con agregados
  • genexus_read — lee cualquier parte de un objeto (código fuente, estructura, reglas, eventos, documentación, XML de patrón, …)
  • genexus_inspect — instantánea de objeto de una sola vez (metadatos, variables, estructura, firma, llamadores)
  • genexus_search_source — búsqueda regex/semántica en código fuente de Procedure/DataProvider/WebPanel/Transaction
  • genexus_navigation — el informe "View Navigation" del IDE Para un Data Selector de GeneXus 18 U16, genexus_read type=DataSelector también acepta parameters, conditions, orders, definedBy, baseTransaction, baseTable y structure. Preserva el orden del SDK y las expresiones completas, devuelve un versionToken y no realiza ninguna operación de ciclo de vida. El SDK público de U16 no expone una colección de atributos proyectados ni joins resueltos para este tipo de objeto, por lo que projection y joins se devuelven en unsupportedParts con el motivo técnico en lugar de arreglos vacíos engañosos. Los objetos base y los índices declarados se informan solo cuando se pueden resolver sin Specify. structure.expression se identifica como un semanticProjection: combina los elementos públicos tipados del SDK y nunca expone los nombres de tipos de colección internos producidos por DataSelectorStructurePart.ToString() en U16.

Edición

  • genexus_edit — editar cualquier parte del objeto; modos full / patch / ops
  • genexus_edit_and_build — editar + especificación opcional + reconstruir llamadores en una sola llamada, con rollback compensatorio ante fallos de validación
  • genexus_edit_form — ediciones semánticas de WebForm
  • genexus_variable — CRUD de la parte Variables
  • genexus_create — paraguas de creación (Transaction, Procedure, Domain, SDT, API, Folder, Module, curl_procedure = generar un Procedure a partir de un comando curl, …); object_atomic redacta definición + variables + Rules + propiedades + Source con preflight/lectura posterior/rollback
  • genexus_data_view — crear/inspeccionar/actualizar/eliminar atómicamente una Transaction de Business Component solo raíz mapeada a través de una Data View nativa a una tabla física existente; valida atributos/claves primero, admite versiones optimistas y dry-runs reales sin mutación, requiere confirm=true para eliminación destructiva e informa el estado de commit/verificación por separado
  • genexus_delete_object — eliminar un objeto por identidad nativa del SDK; use dryRun=true para inspeccionar referencias entrantes antes de confirm=true
  • genexus_format — formatear un fragmento de código con las reglas del worker

Modelo de datos y creación de estructura

  • genexus_structure — lectura/escritura del modelo de datos: get_visual/get_logic, update_visual (DSL de estructura), create_index/drop_index (índices únicos/no únicos — la forma GeneXus de imponer unicidad), set_attribute (Formula, subtipo, Title/ColumnTitle, IsCollection, basedOnDomain), set_level (atributo Description/Image de nivel), set_domain (editar los valores de enum / tipo base de un Domain existente). Para create_index, dryRun:true valida y devuelve el diff proyectado sin guardar; use el versionToken de get_indexes como baseVersion para protección de concurrencia. Una escritura real se vuelve a leer y verifica exactamente, con rollback de snapshot ante fallos. Nunca dispara Specify, Generate, Build, Rebuild, compilación, reorganización, ejecución ni pruebas.
  • genexus_authoring — miembros de tipos de objeto que el DSL de estructura no cubre: add_external_method/add_external_property (External Objects), add_menu_option (Menus)
  • genexus_properties — leer/actualizar propiedades a nivel de objeto
  • genexus_generator_reference — listar/vista previa/agregar/eliminar referencias nativas del generador .NET con validación de ensamblados administrados, concurrencia optimista, verificación de guardado/relectura y rollback exacto de snapshot completo; nunca ejecuta acciones de ciclo de vida implícitamente

Refactor, patrones y comparación

  • genexus_refactor — renombrar, extraer procedimiento, conjunto de condiciones WWP
  • genexus_apply_pattern — aplicar un patrón GeneXus (WorkWith, WorkWithPlus, …); mode=actions gestiona acciones de grid y Action Groups tipados de WorkWithPlus
  • genexus_wwp — edición tipada de WorkWithPlus: Action Groups, add_grid_attribute nativos atómicos, más add_tab, move_tab y remove_tab para pestañas de WebPanel e hijos tipados
  • genexus_compare — paridad con "Compare Objects" del IDE (IComparerService)
  • genexus_merge — fusión de objetos a 2 o 3 vías (IMergeService)

Análisis, documentación y API

  • genexus_analyze — análisis semántico entre objetos (impacto, dependencias, complejidad, nomenclatura, code_metrics, resumen, kb_stats = actividad/actualidad de KB, table_relations = relaciones tabla↔transacción + atributos redundantes, …). mode=explain es solo por compatibilidad: preserva el sobre de respuesta heredado y devuelve NotImplemented; use mode=summary, mode=context o genexus_read en su lugar.
  • genexus_doc — generar wiki / grafos de dependencias / informes de salud
  • genexus_api — inspeccionar endpoints REST expuestos por procedimientos HTTP
  • genexus_security — auditar seguridad de KB: audit_gam (props de env/GAM), scan_secrets (regex sobre Source), scan_native (el Security Scanner propio del SDK, ISecurityScannerService)

Ciclo de vida, build, prueba y BD

  • genexus_lifecycle — build dirigido (incl. compile_check), build_all global incremental, rebuild global forzado, validar, indexar, reorganizar y consultar estado
  • genexus_test — ejecutar pruebas nativas GXtest
  • genexus_db — paraguas de BD: desviación de esquema, sql_ddl/sql_navigation, asesor de índices estático, sample_data, consulta/inserción/actualización tipada de registros de Transaction con dry-run, versionado optimista, relectura y rollback verificado, introspección de tipos Domain/SDT, importación de traducciones, reorg_impact y reorg_preview no mutante con DDL exacto solo desde un artefacto actual de Impact Analysis
  • genexus_deploy — desplegar aplicación (IDeploymentService): list_targets (lectura) / deploy (destructivo, confirm=true)
  • genexus_run_object / genexus_browser — resolver URL de runtime y verificación con navegador headless

Layout nativo / UI

  • genexus_layout — operaciones de layout/WebForm del SDK (get_tree, find_controls, set_property, add_printblock, get_preview, list_controls = catálogo de controles/clases de tema, design_system = tokens/clases/imágenes de DSO, …)

Pool de KB, versionado y desarrollo en equipo

  • genexus_kb — pool multi-KB (list/open/close/set_default)
  • genexus_module — Module Manager (IModuleManagerService)
  • genexus_kb_version — gestión de versiones/ramas del modelo (Create/Activate/Revert)
  • genexus_versioning — paraguas de versionado (historial estilo git sobre la KB)
  • genexus_gxserver — sincronización GXserver / Team Development, incl. pipeline_* (pipelines de CI mediante IContinuousIntegrationService)
  • genexus_transfer — exportación/importación XPZ real (IKnowledgeManagerService, consciente de dependencias): export / inspect / import
  • genexus_memory — almacén de hechos por KB para el agente

Aprovisionamiento de seguridad, IO y meta

  • genexus_gam — aprovisionamiento GAM / seguridad integrada (IIntegratedSecurityService)
  • genexus_io — activos, intercambio de texto de partes, capturas de pantalla, OCR
  • genexus_sdk_probe — volcar la superficie viva del SDK (tipos/métodos/props) para descubrimiento de capacidades
  • genexus_worker_reload — intercambio en caliente del worker sin reiniciar el cliente

Multi-KB (v2.3.0+): cada herramienta no meta acepta un argumento opcional kb (alias o ruta absoluta). La puerta de enlace puede mantener hasta Server.MaxOpenKbs (por defecto 3) KB abiertas a la vez, cada una en su propio proceso Worker — las llamadas a diferentes KB se ejecutan realmente en paralelo. Consulte Advanced Configuration para el esquema KBs[].

WorkWithPlus y theming (vía genexus_read / genexus_edit)

  • Lectura/escritura completa de XML de PatternInstance / PatternVirtual: contenedores (<table>, grupos), controles (<textBlock>, <attribute>, <gridAttribute>, <filterAttribute>, <errorViewer>), acciones (<standardAction>, <userAction>), grids, órdenes, reglas, bloques de eventos. Las vistas Transaction y Selection son direccionables de forma independiente.
  • Documentation (markdown) y Help (HTML) son objetivos de escritura de primera clase.
  • Aplique valores reales de ThemeClass (themeClass, buttonClass, groupThemeClass, …); descúbralos con genexus_list_objects --typeFilter ThemeClass.

Modos de edición (genexus_edit): full (reemplazo de parte completa, predeterminado), patch (Replace/Insert_After/Append sobre un ancla de contexto — funciona en código fuente Y XML de patrones), ops (operaciones semánticas tipadas como set_attribute, add_rule para partes con fuente).

Reconciliación automática de XML de patrones: WorkWithPlus codifica el orden de renderizado del IDE en un atributo childrenOrderedList por padre. El MCP ahora reconstruye (y crea si falta) cada lista a partir del orden real de hijos XML en cada escritura — los llamadores solo describen dónde va un elemento en el árbol y el MCP hace que el IDE lo renderice allí. La respuesta incluye un bloque childrenOrderedListReconciliation que lista cada padre (re)escrito más cualquier elemento estructural que no se pudo inferir de forma segura.

Seguro por defecto: todas las herramientas de escritura aceptan dryRun: true (devuelve una vista previa sin mutar la KB) y idempotencyKey (reintentos seguros; las llamadas concurrentes se fusionan, los resultados se cachean 15 min).

Edición de patrones WorkWithPlus — lo que realmente puede hacer

Los patrones WorkWithPlus son documentos XML que impulsan las pantallas de Transaction y Selection. El MCP expone toda la superficie para que un agente pueda diseñar o reestructurar una pantalla sin abrir el IDE:

CapacidadHerramienta / patrónEstado
Leer XML de PatternInstance / PatternVirtualgenexus_read --part PatternInstance✅
Reemplazar patrón completo (mode: full)genexus_edit --mode full --part PatternInstance✅ verificado en vivo
Parches de estilo buscar/reemplazar texto (mode: patch)genexus_edit --mode patch --part PatternInstance --operation Replace✅ verificado en vivo
Agregar / eliminar / reordenar elementos estructurales (textBlock, attribute, standardAction, table-as-group, order, filterAttribute, gridAttribute, eventBlock…)Edición XML + reconciliación automática✅ verificado en vivo
Clases de tema (themeClass, buttonClass, groupThemeClass, cellThemeClass, format="HTML")Atributo XML en el elemento✅ verificado en vivo
Reorganizar vista Transaction (layout de formulario, fila de acciones)editar bajo /instance/transaction/...✅ verificado en vivo
Reorganizar vista Selection (lista/grid, filtros, órdenes)editar bajo /instance/level/selection/...✅ verificado en vivo
Reconstruir automáticamente childrenOrderedList desde el orden XMLhecho implícitamente en cada escritura; informe bajo childrenOrderedListReconciliation✅ verificado en vivo
Agregar / mover / eliminar pestañas de WebPanel y controles tipadosgenexus_wwp add_tab / move_tab / remove_tab✅ comandos nativos del Pattern SDK; snapshot + relectura + verificación de proyección WebForm
Agregar o reconciliar un caption de atributo de gridgenexus_wwp add_grid_attribute✅ dry-run aislado, snapshots completos de PatternInstance/WebForm, rollback exacto y sin ciclo de vida implícito

Flujo de trabajo recomendado para un rediseño de pantalla:

  1. genexus_list_objects --typeFilter ThemeClass --nameFilter Button — descubra las clases de botón reales disponibles en esta KB (ButtonGreen, ButtonBlue, ButtonRed, etc — los nombres varían por KB).
  2. genexus_read --name WorkWithPlus<Object> --part PatternInstance — obtenga el XML actual.
  3. Edite el XML en memoria (LLM): envuelva atributos en un <table isGroup="True" title="…" groupThemeClass="GroupTelaResp">, reordene botones, agregue un nuevo <standardAction>, adjunte buttonClass="btn ButtonGreen", etc.
  4. genexus_edit --mode full --part PatternInstance --content "<new xml>" — el MCP reescribe la parte, reconcilia childrenOrderedList en cada contenedor y verifica el viaje de ida y vuelta.
  5. Lea de nuevo para confirmar; actualice el IDE de GeneXus para ver el resultado.

Los botones personalizados usan <userAction>, no <standardAction>. Trn_Enter / Trn_Cancel / Trn_Delete son las únicas acciones estándar registradas en una transacción WorkWithPlus; cualquier botón personalizado (Duplicate, Audit, Export, etc.) debe ser un <userAction caption="…" name="…" buttonClass="btn ButtonGreen" confirm="False" />. El reconciliador del MCP trata <userAction> como un par de <standardAction> (mismo typeCode 17/18 según contexto), por lo que coexisten en la misma fila TableActions y el IDE los renderiza lado a lado.

Para pestañas de WebPanel, prefiera la operación tipada nativa en lugar del reemplazo completo de XML:

{
  "action": "add_tab",
  "name": "SamplePanel",
  "controlName": "IntegrationV3",
  "title": "Integration API V3",
  "position": 5,
  "children": [
    { "type": "variable", "name": "Operation", "basicType": "VarChar", "length": 40 },
    { "type": "userAction", "name": "SendIntegration", "caption": "Send" }
  ],
  "dryRun": true
}

El dry-run devuelve un diff tipado y versionToken. Pásalo como baseVersion en la llamada persistida. La escritura usa comandos de elementos del Pattern SDK, requiere instantáneas exactas de PatternInstance/WebForm, conserva Apply-on-save, vuelve a leer el PatternInstance, proyecta y vuelve a leer el WebForm padre, y revierte ambas partes si falla cualquier confirmación. Nunca invoca operaciones de ciclo de vida.

Cosas que debes saber (orientación, no trampas):

  • WorkWithPlus normaliza algunos atributos después de cada guardado. Ciertos campos están vinculados a la transacción subyacente (por ejemplo, title en grupos de nivel superior se deriva del nombre descriptivo de la transacción). Cuando "Apply this pattern on save" está habilitado en el objeto WorkWithPlus, el motor recalcula esos campos — mismo comportamiento tanto si editas en el IDE como vía MCP. Para que una anulación forzada persista, alterna ese indicador vía MCP: 
    { "tool": "genexus_properties",
  "arguments": { "action": "set", "name": "WorkWithPlus<Object>",
                 "propertyName": "SDPlus_Editor_Apply_On_Save", "value": "False" } }
    Acepta "True" | "False" | "Default" (Default hereda la configuración a nivel de KB). Vuelve a establecerlo en "Default" para re-habilitar el recálculo del motor. Validado en vivo en este repositorio.
  • La seguridad estructural la aplica el SDK. Si envías XML que viola los invariantes del patrón (por ejemplo, un <transaction> sin un <level>, o un <standardAction> cuyo name no es una acción registrada), el SDK rechaza el guardado y el MCP devuelve el error exacto para que puedas corregir la entrada. La KB nunca queda a medio escribir.
  • La vista previa del patrón en el IDE es una maqueta estructural, no un renderizado con estilos. El CSS del tema (buttonClass, themeClass, fuentes, colores) se resuelve en tiempo de ejecución, no en el lienzo de vista previa — así que incluso después de una escritura MCP exitosa, el panel de vista previa se verá genérico. Para verificar el estilo: abre el elemento en el árbol del IDE y revisa el panel Properties de la derecha (las clases aplicadas se muestran allí), o pulsa Run / Live Editing para ver el CSS real. Este es el comportamiento del IDE de GeneXus, independiente de cómo se haya editado el patrón.

AXI CLI (para agentes y automatización)

El comando genexus-mcp en sí mismo también es una CLI orientada a agentes con salida optimizada en tokens:

genexus-mcp status               # gateway/worker state
genexus-mcp doctor --mcp-smoke   # health check + protocol probe
genexus-mcp tools list           # list available tools
genexus-mcp config show          # current resolved config
genexus-mcp layout status        # native layout automation state

Indicadores globales: --format toon|json|text · --fields f1,f2,... · --limit N · --query <text> · --quiet · --no-color.

Contrato completo: docs/axi_cli_contract.md. Guía de mejores prácticas: docs/llm_cli_mcp_playbook.md.

Configuración avanzada

El instalador escribe un config.json por ti. Para personalizar la red, los tiempos de espera o las rutas de sombra:

{
  "Server": {
    "HttpPort": 5000,
    "BindAddress": "127.0.0.1",
    "SessionIdleTimeoutMinutes": 10,
    "WorkerIdleTimeoutMinutes": 60,
    "MaxOpenKbs": 3,
    "ArtifactOutputDirectory": "C:\\GenexusMCP\\Artifacts"
  },
  "GeneXus": {
    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
    "WorkerExecutable": "worker\\GxMcp.Worker.exe"
  },
  "Environment": {
    "DefaultKb": "main",
    "KBs": [
      { "alias": "main",   "path": "C:\\KBs\\YourKB" },
      { "alias": "legacy", "path": "C:\\KBs\\OtherKB" }
    ]
  }
}

Compatibilidad hacia atrás: las configuraciones antiguas con un único Environment.KBPath siguen funcionando — la puerta de enlace las migra automáticamente a KBs[] + DefaultKb al cargar.

Artefactos de documentación generados

genexus_doc mantiene los archivos generados fuera de la instalación del Worker para que una actualización no los deje varados en la copia de seguridad de la instalación. Por defecto, la raíz es %LOCALAPPDATA%\GxMcp\Artifacts; cada KB obtiene un directorio kb-<identity> estable con hijos docs y html. Establece Server.ArtifactOutputDirectory para elegir otra raíz; el hijo por KB se sigue añadiendo. GXMCP_ARTIFACT_OUTPUT_DIR es la anulación equivalente para un Worker iniciado directamente. Las respuestas de Wiki informan result.file; las respuestas del visualizador informan result.url; ambas también informan result.outputDirectory. El visualizador y la salud consumen la instantánea canónica IndexCacheService de la KB activa, no una caché compartida relativa a la instalación.

Trabajo con múltiples KBs

Una vez que declaras más de una KB en Environment.KBs[], cada herramienta acepta un argumento opcional kb:

// LLM example: list procedures in two KBs in parallel
{ "tool": "genexus_list_objects", "arguments": { "kb": "main",   "type": "Procedure" } }
{ "tool": "genexus_list_objects", "arguments": { "kb": "legacy", "type": "Transaction" } }

Reglas de resolución cuando se omite kb:

  • un kb explícito siempre gana; úsalo para trabajo en paralelo o cuando un prompt toque más de una KB
  • cada sesión MCP captura el DefaultKb configurado en initialize; set_default cambia la sesión actual y persiste el valor de inicio por defecto para futuras sesiones
  • open solo inicia/registra un Worker; no cambia silenciosamente el objetivo de otra sesión. Selecciónalo con set_default, o pasa kb explícitamente
  • exactamente 1 KB abierta → usa esa KB cuando la sesión no tiene selección
  • 2+ KBs abiertas sin selección de sesión → el servidor devuelve KB_AMBIGUOUS; elige una con set_default o pasa kb explícitamente

Gestiona el pool en tiempo de ejecución:

{ "tool": "genexus_kb", "arguments": { "action": "list" } }
// → { selectedKb, activeKb, openKbs: [{alias, path, pid, workingSetMB, idleSeconds}], knownKbs, maxOpenKbs, defaultKb, declaredKbs }

{ "tool": "genexus_kb", "arguments": { "action": "open", "alias": "adhoc", "path": "C:/KBs/ScratchKB" } }
{ "tool": "genexus_kb", "arguments": { "action": "close", "alias": "legacy" } }
{ "tool": "genexus_kb", "arguments": { "action": "set_default", "alias": "main" } }   // persists to config.json

Para OpenCode, llama a genexus_whoami una vez al inicio de una sesión. Usa kb.selected, kb.default, kb.openKbs, kb.knownKbs y kb.declaredKbs para entender el objetivo, luego selecciona la KB de trabajo normal con genexus_kb action=set_default. Cada respuesta vinculada a una KB también incluye kbAlias en su carga JSON, lo que permite a OpenCode correlacionar respuestas solo de texto. Mantén kb=<alias> en llamadas que intencionalmente comparen o actualicen otra KB.

El instalador registra ambos diseños de configuración de OpenCode: la entrada directa legada mcp.genexus usada por OpenCode 1.x y el diseño actual mcp.servers.genexus. clients add --clients opencode solo se necesita para reparar o re-registrar explícitamente un cliente después de la instalación; el init normal maneja los clientes detectados automáticamente. Reinicia OpenCode después de un registro para que recargue la configuración MCP.

Cuando el pool está lleno y ningún Worker está inactivo, el servidor devuelve KB_POOL_FULL — cierra uno explícitamente o aumenta Server.MaxOpenKbs. Cada Worker lleva el SDK en su propio proceso (~200–400 MB en reposo, hasta 1–2 GB en KBs pesadas), así que dimensiona el pool según la RAM disponible.

Arquitectura

graph LR
    A[AI Client / Nexus-IDE] -->|MCP stdio or HTTP /mcp| B[Independent Gateway .NET 10]
    B -->|isolated stdio: direct child| C[Worker .NET Framework 4.8]
    B -->|shared-host: named-pipe attachment| H[Per-KB WorkerHost broker]
    H -->|one compatible child| C
    C -->|Native SDK| D[GeneXus KB]
  • Pool de Workers (v2.3.0+): en modo aislado, un proceso Worker .NET 4.8 por KB abierta en cada Gateway, limitado por MaxOpenKbs (por defecto 3). Con shared-host, los Gateways compatibles se conectan a un Worker propiedad del broker por KB física en lugar de iniciar procesos SDK duplicados. Los Workers se generan de forma diferida, se reciclan mediante WorkerIdleTimeoutMinutes y se expulsan LRU cuando el pool está lleno.
  • Paralelismo entre KBs: las llamadas a herramientas de diferentes KBs se ejecutan en diferentes procesos Worker y nunca se bloquean entre sí. Las llamadas a la misma KB siguen serializándose por el requisito STA del SDK de GeneXus.
  • Aislamiento de Gateway: shared-host no convierte un Gateway en maestro o proxy de otro; cada cliente mantiene su propio estado MCP y solo el Worker del SDK se comparte.
  • Reutilización de Gateway: múltiples instancias del IDE comparten un gateway mediante archivos de arrendamiento en %LOCALAPPDATA%\GenexusMCP\gateway-leases.
  • Modo HTTP: también disponible en http://127.0.0.1:5000/mcp con SSE. Cabecera: MCP-Protocol-Version: 2025-11-25.

Desarrollo y compilación desde el código fuente

¿Quieres contribuir o ejecutar una compilación de desarrollo local?

  1. Clona este repositorio en Windows.
  2. Ejecuta .\build.ps1 para restaurar y compilar los componentes C# y empaquetar los artefactos locales. El script verifica el SDK de .NET requerido y la instalación de GeneXus 18.
  3. Si GeneXus está instalado fuera de la ruta predeterminada, establece $env:GX_PATH en su carpeta de instalación antes de ejecutar la compilación. Solo se necesita una Knowledge Base para pruebas en tiempo de ejecución.

Habilidades de IA incluidas (.gemini/skills/)

Este repositorio incluye un conjunto de habilidades de agente bajo .gemini/skills/ que cualquier cliente compatible con MCP con soporte de habilidades (Gemini CLI, Claude Code vía plugin, etc.) puede cargar para fundamentar su razonamiento sobre GeneXus:

HabilidadQué le da al agente
genexus-masteryEl flujo de trabajo MCP preferido de este repositorio + uso multi-KB
genexus18-guidelinesReglas de ingeniería locales superpuestas a Nexa
nexaConjunto de referencia completo para el SDK principal de GeneXus: cada tipo de objeto, comando, tipo, propiedad — importado del oficial genexuslabs/genexus-skills
frontend/chameleon-controls-library58 especificaciones de componentes de UI de Chameleon
frontend/mercury-design-systemTokens, bundles y theming de Mercury
frontend/design-system-builderCreación de sistemas de diseño personalizados
frontend/ui-creatorPlantillas de generación de paneles/pantallas

Las habilidades de terceros son Apache 2.0 (ver .gemini/skills/NOTICE.md). Para actualizar contra el upstream, sigue los pasos en NOTICE.md.

Nexus-IDE (extensión de VS Code — opcional, no se instala automáticamente)

src/nexus-ide es una extensión ligera y experimental de VS Code en el repositorio. El instalador ya no la empaqueta ni la instala — VS Code se configura como cliente MCP nativo en su lugar (ver Clientes de IA compatibles). Si quieres la extensión, compílala e instálala manualmente:

cd src/nexus-ide; npm ci; npm run compile
npx --yes @vscode/vsce package --out nexus-ide.vsix
code --install-extension nexus-ide.vsix --force

Proporciona un sistema de archivos virtual (esquema genexus://), un explorador de KB con edición multiparte y comandos de descubrimiento MCP.

Lanzamiento automatizado

  • Flujo de trabajo: .github/workflows/release.yml
  • Disparador: push a main con un aumento de versión package.json
  • Comportamiento: publica en npm si la versión es nueva + crea un Release de GitHub etiquetado v<version>
  • Secreto requerido: NPM_TOKEN

Licencia

MIT — ver LICENSE.

Palabras clave de búsqueda: GeneXus MCP · GeneXus 18 MCP · GeneXus AI · GeneXus Claude · Model Context Protocol GeneXus · GeneXus low-code AI agent · GeneXus Cursor · GeneXus Antigravity