GenieClient (CLI + MCP)

GenieClient is a standalone tool in the monorepo at tools/GenieClient that talks to a running Genie deployment over its JSON API. It authenticates with a System-role account and then exercises the framework end-to-end: running scripts, importing seed data, and verifying views, CRUD, imports, exports, and relations — from the terminal or as an MCP server an external LLM (Claude Code, Codex, …) drives.

It embeds no LLM. GenieClient is a deterministic client; the intelligence is the agent that calls its MCP tools — cooking test data, deciding what to verify, and interpreting the structured JSON it returns. The full command reference and MCP setup live in the tool’s own README.md/USAGE.md; this page is the framework-level overview.

What it verifies

• Views — metadata resolves, the grid query runs, and form/view values load, per object.
• CRUD — add → list/verify → update → verify → delete → verify, with runtime fake data (Bogus). Lookup fields are resolved to real existing options via the field-dataset endpoint so foreign keys hold. Primary-key/hidden/disabled/attachment/sequence fields are skipped.
• Import — a seed-models.xml map (<Map ObjectName="" ImportFile="" />) loads each file into its object, then verification re-queries the object to confirm rows landed.
• Export — export to a file, download it, and check it is non-empty (and that expected rows came through as per the view’s logic).
• Relations — lookups resolve, sub-views load under a parent key, and (given a model directory) where the object is referenced by other views.

Endpoints used

It matches the current object API — the unified *.view.xml (one object = table + form) and the metadata + object/{name}/{table,form,view} split, not the legacy render endpoints:

Purpose	Endpoint
Auth	POST /api/v1/auth/login, /mfa/verify, /refresh; GET /auth/me
Scripts	POST /api/v1/genie/execute-script (System role)
Metadata	GET /api/v1/genie/object/{name}/metadata
Data	POST /api/v1/genie/object/{name}/table · /form · /view
Mutations	POST /api/v1/genie/object/{submit,delete-row}
Lookups	POST /api/v1/genie/object/field-dataset
Import / Export	POST /object/import-data · POST /object/export-data + GET /object/export-file/{name}
Company / RPC	POST /company/switch · POST /rpc/call

Definition transfer — RBAC / Workflows / Wizards

Beyond the object test suite, GenieClient exports and imports the authorization RBAC, workflow, and wizard definitions as XML — the export → verify → merge → import loop:

• Export each subsystem’s live definition to a directory: rbac.xml, <Name>.workflow.xml, <Name>.wizard.xml.
• Verify with --against <models-dir>: RBAC uses a semantic diff (it ignores the export’s canonical ordering and reports real resource/grant changes); workflows and wizards use a canonical-XML compare against your source-of-truth file.
• Merge manually, then import back.

GenieClient export-rbac      -o ./out --against ./models
GenieClient import-rbac      ./out/rbac.xml            # full add/update/delete sync (--no-prune to opt out)
GenieClient export-workflows -o ./out --against ./models
GenieClient import-workflow  ./out/Approval.workflow.xml
GenieClient export-wizards   -o ./out --against ./models
GenieClient import-wizard    ./out/Onboarding.wizard.xml

RBAC has real file endpoints (export-rbac / import-rbac); workflows and wizards have none, so GenieClient drives their JSON designer APIs (workflow/definitions[/{id}/save], wizard/list, wizard/{key}, wizard/save) to read each definition’s verbatim XML and write it back.

Importing a wizard cannot rename one that already has submissions: the name fixes its response table, so the save is rejected — see Storage and indexes. Response-table changes an import implies (a new Indexed field, a new index) are applied in the background, so give provisioning a moment before submitting through the imported wizard.

import-rbac defaults to the server’s full-sync prune mode — deleting orphan roles/resources while guarding the seeded System/Admin/AccessManager roles and roles with active user assignments.

The MCP surface mirrors these as genie_export_rbac, genie_import_rbac, genie_export_workflows, genie_import_workflow, genie_export_wizards, genie_import_wizard.

Workspaces (concurrent, multi-deployment)

A workspace is one deployment, identified automatically by its endpoint URL — no naming or setup. Each endpoint gets isolated token storage, so multiple clients/agents operate at once without sharing credentials. Independent CLI/stdio processes pick their workspace from -e / GENIE_ENDPOINT; a single HTTP MCP server multiplexes many deployments — every authenticated tool takes an optional endpoint (omit for the server’s GENIE_ENDPOINT default), and each call runs in its own isolated ambient scope so concurrent calls never cross tokens. Credentials resolve automatically per endpoint (a stored token from a prior auth -e <endpoint>, else the env default). workspaces lists them.

As an MCP server

GenieClient mcp --transport stdio        # for Claude Code / Codex (default)
GenieClient mcp --transport http --url http://localhost:5177   # SSE, remote/shared clients — multiplexes workspaces

Credentials come from environment variables the MCP client sets — GENIE_ENDPOINT, GENIE_USER, GENIE_PASSWORD — and the server authenticates lazily on the first tool call. It exposes tools such as genie_health, genie_run_view_tests, genie_test_crud, genie_import_data, genie_export_data, and genie_test_relations, each returning structured JSON so an agent can chain execute-script → import → verify → export → verify → crud → relations autonomously.

System credentials

execute-script and arbitrary company switching require the System role, so GenieClient is typically run with a System service account. The HTTP MCP transport carries those credentials — bind it to localhost / a trusted network only and terminate TLS at a reverse proxy. MFA accounts can’t be used by the MCP server non-interactively; use a service account or authenticate once via the CLI.

See tools/GenieClient/README.md for build/run instructions, the full command table, and ready-to-paste Claude Code / Codex MCP config, and tools/GenieClient/USAGE.md for step-by-step recipes.