Genexus18MCP: Instructions file for Gemini CLI

GeneXus MCP Protocol Guide

Required repo skills before editing KB logic:

1. GeneXus MCP Mastery
2. GeneXus 18 Guidelines

This repository is MCP-first. The official transport is MCP over stdio or HTTP at /mcp. The old /api/command endpoint is no longer part of the gateway surface.

Correct MCP flow

1. Initialize the session with initialize.
2. Discover the live surface with tools/list, resources/list, resources/templates/list, prompts/list, and completion/complete when needed.
3. Execute work with tools/call, resources/read, and prompts/get.
4. For HTTP MCP, send MCP-Protocol-Version: 2025-06-18 and reuse the returned MCP-Session-Id.

Recommended tool usage

• genexus_wire (MANDATORY FIRST STEP): native Rust architectural discovery and call graph engine (sub-10ms). Run action=pack_task or for BEFORE reading large objects or editing KB code to orient on any task, rank affected symbols, and calculate blast radius under a strict token budget. Actions: pack_task (default), status, for (with domain synonym expansion, e.g. fat->faturamento, cli->cliente), callers, impact, path (shortest call path from from to to), slice, safe_delete, index, doctor. Formats: toon (token-efficient tabular ~40% savings, recommended), mermaid (renders flowchart/diagram for markdown artifacts), xml, json. On a native KB only pack_task works without an export: pass targets (object names) and/or name the objects in task; it returns the resolved objects with direct callers/callees and lists what it could not resolve.
• genexus_query: find objects, references, signatures, and dependency entry points. Supports optional typeFilter and domainFilter for server-side narrowing.
• genexus_read: read object parts with pagination. Pass singular name for one object or targets[] for coordinated multi-object reads (mutually exclusive). For MCP clients, keep reads paginated; the server intentionally returns a source-first first page when no explicit offset/limit is provided. For XML metadata parts such as Layout, WebForm, and PatternInstance, the gateway applies a larger metadata budget to avoid truncating the editable XML.
• genexus_edit: apply focused edits to a part or replace content through the MCP write path. Three modes:
  • mode: 'xml' (default): full XML replacement.
  • mode: 'ops': typed semantic op catalog (set_attribute, add_attribute, remove_attribute, add_rule, remove_rule, set_property).
  • mode: 'patch': JSON-Patch (RFC 6902) array over the canonical JSON object representation; legacy string-form text patch is also accepted for backward compatibility. Pass targets[] (array of edit-request objects) for atomic multi-object edits — mutually exclusive with singular name. PatternInstance targets the authoritative WorkWithPlus instance when the requested object is a WebPanel managed by WorkWithPlus.
• All write tools (genexus_edit, genexus_create_object, genexus_refactor, genexus_forge, genexus_import_object) accept:
  • dryRun: true — returns a preview envelope {_meta:{dryRun,schemaVersion}, plan:{touchedObjects, xmlDiff, brokenRefs, warnings}} without mutating the KB.
  • idempotencyKey: '<token>' ([A-Za-z0-9_-]{1,128}) — deduplicates retries; concurrent calls with the same key are coalesced; cache is per-KB, sliding TTL 15 min default. dryRun bypasses the cache.
• genexus_inspect: get structured conversion or object context.
• genexus_analyze: one tool with mode: linter | navigation | hierarchy | impact | data_context | ui_context | pattern_metadata | summary | explain. explain is compatibility-only: it preserves the legacy envelope and returns NotImplemented; use summary for a concise object overview, context for 360° task context, or genexus_read for source. The standalone genexus_summarize and genexus_explain_code were replaced in v2.3.0.
• genexus_lifecycle: build, validate, index, and KB lifecycle operations.
• genexus_sql: action=ddl for Transaction/Table DDL or action=navigation for the SQL of a procedure's For Each (replaces genexus_get_sql and genexus_get_sql_for_navigation in v2.3.0).
• genexus_kb: multi-KB pool management (action: list | open | close | set_default). Replaces genexus_open_kb in v2.3.0.
• genexus_create_object: create new KB objects.
• genexus_refactor: supported rename and extraction refactors.
• genexus_add_variable: add variables through the worker contract.
• genexus_format: format source through the worker formatter.
• genexus_properties: get or set object properties.
• genexus_asset: find, read, and write KB assets such as .xlsx templates. Reads are metadata-first; request includeContent=true only for files small enough to carry as Base64 safely.
• genexus_history: list, read, save, and restore object history.
• genexus_structure: read or update logical and visual structure.
• genexus_doc: access documentation, health, and visualization flows.