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

Prueba este MCPPatrocinado

Documentación

GeneXus MCP Server — GeneXus 18 para Claude, Cursor y Agentes de IA

¿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 de GeneXus 18. Se comunica con el SDK nativo de GeneXus, por lo que el agente trabaja con la KB real, no con una copia o una aproximación analizada.

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.

Lo que puedes hacer con él

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

Área	Lo que el agente puede hacer
🔎 Explorar	Buscar y listar objetos, leer cualquier parte (código fuente, reglas, eventos, estructura, documentación, XML de patrón), inspeccionar metadatos y llamadores, búsqueda por regex en el código fuente, ver el informe de navegación
✏️ Editar código	Editar cualquier parte del objeto (modos `full`/`patch`/`ops`), CRUD de variables, formato, crear y eliminar objetos, generar un Procedure a partir de un comando curl, editar y reconstruir llamadores de una sola vez
🗄️ Crear el modelo de datos	Estructura de transacciones (DSL), índices únicos/no únicos (crear y eliminar), fórmulas y subtipos de atributos, atributos de Descripción/Imagen a nivel de nivel, valores de enumeración de dominios, carpetas y módulos, relaciones tabla↔transacción y detección de atributos redundantes
🧩 Crear otros objetos	Métodos y propiedades de External Objects, opciones de menú, objetos REST API, patrones WorkWithPlus / WorkWith
🎨 UI y WorkWithPlus	Lectura/escritura completa del XML de patrón (controles, acciones, grillas, órdenes, grupos), clases de tema y estilos, edición nativa de WebForm/layout, catálogo de controles y tokens/clases/imágenes del sistema de diseño, verificación con navegador headless
🔬 Analizar	Aná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 desplegar	Compilar (completo o rápido `compile_check`), validar, reorganizar, indexar, ejecutar pruebas nativas GXtest, desplegar la aplicación (objetivos + despliegue)
🔀 Refactorizar y comparar	Renombrar en toda la KB, extraer procedimiento, comparar y fusionar objetos (paridad con el IDE)
🌿 Versionado, transferencia y equipos	Versiones/ramas del modelo de KB, exportación/importación XPZ real (consciente de dependencias), sincronización con GXserver (Team Development) + pipelines de CI, historial estilo git, trabajo paralelo con múltiples KB
🔐 Seguridad	Aprovisionamiento de GAM / seguridad integrada, auditoría de seguridad de la KB + escáner de seguridad 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 parches de texto sobre archivos de KB.

Requisitos previos

Antes de comenzar, asegúrate de tener:

✅ Windows (GeneXus es solo para Windows)
✅ GeneXus 18 instalado localmente (ruta predeterminada: C:\Program Files (x86)\GeneXus\GeneXus18)
✅ Una Knowledge Base de GeneXus 18 abierta al menos una vez en el IDE (para que esté inicializada)
✅ Node.js 18+ — 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 se encarga de ello.

¿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:

Carpeta de instalación de GeneXus — donde vive GeneXus.exe. Generalmente C:\Program Files (x86)\GeneXus\GeneXus18.
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 está 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):

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

Paso 2 — Registra el MCP en tu cliente de IA

El Paso 1 registra automáticamente con Claude Desktop, Claude Code, Cursor y Antigravity cuando los detecta. Si el tuyo no fue detectado, copia el fragmento JSON del Paso 1 en la configuración de MCP de tu cliente manualmente. Consulta la guía de configuración de clientes si no estás seguro de dónde vive 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 de nuevo. (Cerrar la ventana no es suficiente.)
Claude Code: finaliza la sesión y comienza una nueva.
Cursor / Antigravity: cierra todas las ventanas y vuelve a abrirlas.

Luego pega esta indicación:

"Usando el GeneXus MCP, 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 GeneXus MCP. 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 mi configuración de 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 pida.

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

Si tu máquina tiene Microsoft Defender ASR, SmartScreen u otra política de endpoint que bloquee 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 por versión, por lo que TI no puede permitir una ruta estable sin un comodín sobre toda la caché de npm (que es demasiado amplio).

Usa el instalador corporativo en su lugar. Extrae los binarios a un directorio estable y registra los clientes de IA para iniciar 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 18+ 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 estas como tus primeras indicaciones:

Exploración

"Lista todos los objetos de tipo Procedure en la 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 del 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 external object PaymentGateway."
"Agrega una opción de menú 'Customers' a MainMenu que abra CustomerWW."

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

"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 WorkWithPlusInvoice, agrega un nuevo ordenamiento por InvoiceDate descendente."
"Estiliza el botón Save en WorkWithPlusOrder con buttonClass='btn ButtonGreen' y aplica BigTitle al encabezado del formulario."
"Elimina la acción Export de la grilla Selection 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, paso a paso."
"¿Qué SQL genera la consulta en el WebPanel CustomerList?"
"Resume la estructura del módulo Sales."

Compilación y ciclo de vida

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

El agente elige la herramienta correcta de las 40+ herramientas que expone el MCP (leer, editar, refactorizar, analizar, compilar, creación del modelo de datos, automatización de layout, DB/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:

Cliente	Auto-configuración	Notas
Claude Desktop	✅	Reinicio requerido después de la instalación
Claude Code (CLI)	✅	Recargar sesión
Cursor	✅	Reinicio requerido
Antigravity	✅	Reinicio requerido; detectado incluso antes de que exista su configuración de MCP
Gemini CLI	✅	—
OpenCode (CLI)	✅	Lee `opencode.json` / `opencode.jsonc`
Codex CLI	✅	Escribe `~/.codex/config.toml`
VS Code / VS Code Insiders	✅	MCP nativo (`User/mcp.json`); reinicio requerido
OpenCode Desktop	Solo detección	Informado como instalado; agrega el servidor desde la configuración de la aplicación
Cualquier cliente MCP	Manual	Usa 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.

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 caen en unas pocas categorías — consulta TROUBLESHOOTING.md para las soluciones:

El instalador no puede encontrar GeneXus o la 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 de KB / artefactos bloqueados
Puerto 5000 ya en uso
Permisos en %LOCALAPPDATA%\GenexusMCP\ ¿Sigue atascado? Abra un issue con la salida de npx genexus-mcp doctor --mcp-smoke.

Superficie de herramientas

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

Orientación y salud

genexus_whoami — contexto de KB, versión, salud del worker/índice/base de datos, verificación de auto-actualización, sugerencias de siguientes pasos
genexus_doctor — verificación de salud de conexión + instalación + caché
genexus_recipe — playbooks nombrados / macros auto-extensibles
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 paginado de objetos con agregados
genexus_read — leer cualquier parte de un objeto (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 fuente de Procedure/DataProvider/WebPanel/Transaction
genexus_navigation — el informe "Ver navegación" 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 uniones resueltas para este tipo de objeto, por lo que projection y joins se devuelven en unsupportedParts con la razón técnica en lugar de arreglos vacíos engañosos. Los objetos base y los índices declarados se informan solo cuando pueden resolverse 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 de objeto; modos full / patch / ops
genexus_edit_and_build — editar + especificación opcional + reconstruir llamadores en una sola llamada, con reversión compensatoria ante fallo de validación
genexus_edit_form — ediciones semánticas de WebForm
genexus_variable — CRUD de la parte de Variables
genexus_create — paraguas de creación (Transaction, Procedure, Domain, SDT, API, Folder, Module, curl_procedure = andamiaje de un Procedure a partir de un comando curl, …); object_atomic redacta definición + variables + Reglas + propiedades + Fuente con verificación previa/lectura posterior/reversión
genexus_delete_object — eliminar un objeto
genexus_format — formatear un fragmento de código con las reglas del worker

Modelo de datos y redacción de estructura

genexus_structure — leer/escribir el 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 (Fórmula, subtipo, Título/Título de columna, IsCollection, basedOnDomain), set_level (atributo de Descripción/Imagen de nivel), set_domain (editar los valores de enumeración / 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 relee y verifica exactamente, con reversión de instantánea ante fallo. Nunca dispara Specify, Generate, Build, Rebuild, compilación, reorganización, ejecución o 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 (Menús)
genexus_properties — leer/actualizar propiedades a nivel de objeto

Refactorización, 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 cuadrícula y Grupos de acciones de WorkWithPlus tipados
genexus_wwp — edición de Grupo de acciones / acción de cuadrícula de WorkWithPlus: list, add_action, update_action, move_action, remove_action
genexus_compare — paridad con "Comparar objetos" 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, explicación, kb_stats = actividad/actualidad de KB, table_relations = relaciones tabla↔transacción + atributos redundantes, …)
genexus_doc — generar wiki / diagramas de secuencia / informes de salud
genexus_api — inspeccionar endpoints REST expuestos por procedimientos HTTP
genexus_security — auditar seguridad de KB: audit_gam (propiedades de entorno/GAM), scan_secrets (regex sobre Fuente), scan_native (el propio Security Scanner del SDK, ISecurityScannerService)

Ciclo de vida, compilación, prueba y BD

genexus_lifecycle — compilar (incl. compile_check), validar, indexar, reorganizar, 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, introspección de tipos Domain/SDT, importación de traducciones, reorg_impact y reorg_preview no mutante con DDL exacto solo a partir de un artefacto actual de Análisis de impacto
genexus_deploy — desplegar aplicación (IDeploymentService): list_targets (lectura) / deploy (destructivo, confirm=true)
genexus_run_object / genexus_browser — resolver URL de ejecución y verificación con navegador sin interfaz

Diseño nativo / UI

genexus_layout — operaciones de diseño/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 de modelo (Crear/Activar/Revertir)
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 de 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/propiedades) 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 verdaderamente en paralelo. Consulte Configuración avanzada para el esquema KBs[].

WorkWithPlus y tematización (mediante `genexus_read` / `genexus_edit`)

Lectura/escritura completa de XML de PatternInstance / PatternVirtual: contenedores (<table>, grupos), controles (<textBlock>, <attribute>, <gridAttribute>, <filterAttribute>, <errorViewer>), acciones (<standardAction>, <userAction>), cuadrículas, órdenes, reglas, bloques de eventos. Las vistas de Transacción y Selección 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, por defecto), patch (Reemplazar/Insertar_después/Anexar sobre un ancla de contexto — funciona en código fuente Y XML de patrón), ops (operaciones semánticas tipadas como set_attribute, add_rule para partes con fuente).

Reconciliación automática de XML de patrón: 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 pudo inferirse 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 — qué puede hacer realmente

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

Capacidad	Herramienta / patrón	Estado
Leer XML de `PatternInstance` / `PatternVirtual`	`genexus_read --part PatternInstance`	✅
Reemplazar patrón completo (`mode: full`)	`genexus_edit --mode full --part PatternInstance`	✅ verificado en vivo
Buscar/reemplazar parches estilo 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 de Transacción (diseño de formulario, fila de acciones)	editar bajo `/instance/transaction/...`	✅ verificado en vivo
Reorganizar vista de Selección (lista/cuadrícula, filtros, órdenes)	editar bajo `/instance/level/selection/...`	✅ verificado en vivo
Reconstruir automáticamente `childrenOrderedList` desde el orden XML	se hace implícitamente en cada escritura; informe bajo `childrenOrderedListReconciliation`	✅ verificado en vivo

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

genexus_list_objects --typeFilter ThemeClass --nameFilter Button — descubra las clases de botones reales disponibles en esta KB (ButtonGreen, ButtonBlue, ButtonRed, etc. — los nombres varían por KB).
genexus_read --name WorkWithPlus<Object> --part PatternInstance — obtenga el XML actual.
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.
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.
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 (Duplicar, Auditoría, Exportar, 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.

Cosas que debe 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 — el mismo comportamiento ya sea que edites en el IDE o mediante MCP. Para que una anulación forzada persista, alterna ese indicador mediante MCP:
```
{ "tool": "genexus_properties",
  "arguments": { "action": "set", "name": "WorkWithPlus<Object>",
                 "propertyName": "SDPlus_Editor_Apply_On_Save", "value": "False" } }
```
Acepta "True" | "False" | "Default" (Por defecto hereda la configuración a nivel de KB). Vuelve a "Default" para re-habilitar el recálculo del motor. Validado en vivo en este repositorio.
La seguridad estructural es aplicada por 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. El 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 Propiedades a la derecha (las clases aplicadas se muestran allí), o usa Ejecutar / Edición en vivo para ver el CSS real. Esto es comportamiento del IDE de GeneXus, independiente de cómo se editó el patrón.

CLI de AXI (para agentes y automatización)

El comando genexus-mcp en sí mismo también es una CLI orientada a agentes con salida optimizada para 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 redes, tiempos de espera o rutas de sombra:

{
  "Server": {
    "HttpPort": 5000,
    "BindAddress": "127.0.0.1",
    "SessionIdleTimeoutMinutes": 10,
    "WorkerIdleTimeoutMinutes": 5,
    "MaxOpenKbs": 3
  },
  "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.

Trabajar con múltiples KBs

Una vez que declaras más de un 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:

exactamente 1 KB abierto → usa ese KB
0 KBs abiertos + DefaultKb configurado → abre DefaultKb de forma diferida
2+ KBs abiertos → el servidor devuelve KB_AMBIGUOUS y debes pasar kb explícitamente

Gestiona el grupo en tiempo de ejecución:

{ "tool": "genexus_kb", "arguments": { "action": "list" } }
// → { openKbs: [{alias, path, pid, workingSetMB, idleSeconds}], 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

Cuando el grupo 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 pesados), así que dimensiona el grupo según la RAM disponible.

Arquitectura

graph LR
    A[AI Client / Nexus-IDE] -->|MCP stdio or HTTP /mcp| B[Gateway .NET 8]
    B -->|JSON-RPC over process boundary| C[Worker .NET Framework 4.8]
    C -->|Native SDK| D[GeneXus KB]

Grupo de Workers (v2.3.0+): un proceso Worker .NET 4.8 por KB abierto, limitado por MaxOpenKbs (por defecto 3). Los Workers se generan de forma diferida, se reciclan mediante WorkerIdleTimeoutMinutes y se expulsan por LRU cuando el grupo está lleno.
Paralelismo entre KBs: las llamadas a herramientas en diferentes KBs se ejecutan en diferentes procesos Worker y nunca se bloquean entre sí. Las llamadas al mismo KB siguen serializadas por el requisito STA del SDK de GeneXus.
Reutilización de la puerta de enlace: múltiples instancias del IDE comparten una puerta de enlace 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?

Clona este repositorio en Windows.
Ejecuta .\setup.bat — verifica los requisitos previos, compila los componentes de C# y registra automáticamente la compilación local con los clientes de IA detectados.
Si GeneXus o tu KB no se detectan automáticamente, sigue las indicaciones.

Habilidades de IA incluidas (`.gemini/skills/`)

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

Habilidad	Qué le da al agente
`genexus-mastery`	El flujo de trabajo MCP preferido de este repositorio + uso de múltiples KBs
`genexus18-guidelines`	Reglas de ingeniería locales superpuestas sobre Nexa
`nexa`	Conjunto de referencia completo de GeneXus 18: cada tipo de objeto, comando, tipo, propiedad — importado de la `genexuslabs/genexus-skills` oficial
`frontend/chameleon-controls-library`	58 especificaciones de componentes de UI de Chameleon
`frontend/mercury-design-system`	Tokens de Mercury, paquetes, tematización
`frontend/design-system-builder`	Creación de sistemas de diseño personalizados
`frontend/ui-creator`	Plantillas 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 de múltiples partes y comandos de descubrimiento de MCP.

Publicación automatizada

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 una Release de GitHub etiquetada v<version>
Secreto requerido: NPM_TOKEN

Licencia

MIT — ver LICENCIA.

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