Skip to content
  • There are no suggestions because the search field is empty.

Model a biGENIUS-X project with Claude Code

Applies to
License: MCP Server

Describe in business terms what your model needs, and Claude Code plans and builds the model objects with the biGENIUS-X MCP server. Use it to build a slice from a discovery or to change an existing model. Afterwards the changed model files are in your Git branch, ready for review in biGENIUS-X.

Prerequisites

Model with Claude Code

  1. Open Claude Code in the root folder of the repository (the folder with project.yml) and describe what you need in business terms. Claude uploads the project files into a workspace on the server: it calls open_workspace and runs the upload command it returns.
  2. The upload command normally runs without a prompt. If Claude Code asks, approve it when it is a tar and curl command with a mcp.bigenius-x.com URL.
  3. Read the plan. Claude reads the model objects, the discovery and the model object types your generator offers. It shows the model objects per layer with business keys, relationships and historization. The plugin's skill tells Claude to wait for your confirmation and to ask when grain, life cycle, historization or the formula of a measure is unclear. Correct the plan before you confirm it.
  4. Confirm the plan. Claude builds layer by layer from the sources upward, a small slice through all layers first. After each layer it runs validate_project, fixes errors and reports warnings to you.
  5. After each layer, Claude calls download_changes and runs the download command, which writes the changes into your working tree. When files must be deleted, it also runs a delete command; the plugin never allows delete commands without a prompt, so Claude Code asks you first.
  6. At the hand-over, Claude lists the new and changed model objects, open warnings and its assumptions. It asks whether to run the semantic model validation (validate_semantic_model) or the architecture model calculation (calculate_architecture_model); either runs only when you agree. The calculation sends the workspace files to biGENIUS-X and replaces the architecture model of the project for the branch Claude names, main when it names none.
  7. Review the diff, then commit and push the branch.
  8. Open the branch in biGENIUS-X, check the model objects and generate the artifacts. See Generate artifacts.
  9. When biGENIUS-X reports findings, paste them into Claude Code and ask it to fix them.

Tools you see in the chat

  • Open the project: open_workspace, then the upload command; sync_workspace uploads again.
  • Read: list_project_objects, list_views, show_project_object, get_generator_catalog, describe_type.
  • Build: create_model_object, add_terms, add_relationship, build_dataflow, often grouped in run_batch.
  • Check: validate_project.
  • Write back: download_changes, then the download command.
  • On request only: validate_semantic_model, calculate_architecture_model.

Edit model files by hand

You can edit expressions in mappings and filters, descriptions and properties directly in the YAML files. Edit only after Claude has downloaded its changes, then tell Claude, so that it uploads the files again with sync_workspace. Leave model objects, terms, relationships and business keys to the tools. The tools also create the derived content, such as foreign key terms, hash keys, Default Terms and mapping stubs, which a manual edit leaves out.

Work effectively with Claude

  • Start small: build one business concept, for example Customer, through all layers, check it in biGENIUS-X, then continue.
  • Answer questions in business terms ("a customer can have several addresses; only the current one counts"), not with the model object to build.
  • Name the Dataflow Modeling View. Without one, new model objects go to the default view. The tools place model objects only on Dataflow Modeling Views; add them to a Relationship Modeling View in biGENIUS-X.
  • Ask explicitly when existing model objects should change. The skill tells Claude to change them only on request.
  • Start a new session for a new task. Long sessions lose precision.

Example

Example: a Data Vault and Mart project with the discovery CRM. The prompts show wording; which model object types exist depends on your generator.

Plan the Raw Vault for customer and account from the CRM
discovery. Show me the business keys and relationships first.

After you confirm the plan, ask for the next slice:

Build a Customer dimension in the mart from the Raw Vault.
Address changes are historized. Validate after each layer.

Other prompts that work in every project:

Which layers and model objects does the project have?
Show me Customer with its terms and relationships.
Rename the term CUST_NBR to CustomerNumber in all objects.
biGENIUS-X reports these findings: <findings>. Fix them.

Replace <findings> with the findings that biGENIUS-X shows.

Check the result

git status lists the changed files under modelobjects/ and views/. After you push the branch and open it in biGENIUS-X, the new model objects appear in their view, and the validation of the branch shows no errors. See Validate a Local Branch.

Failure symptoms and recovery

The workspace has expired

Message: Workspace <workspace ID> does not exist or has expired (2 hours without use). Call open_workspace.
Cause: the server deletes a workspace after 2 hours without use.
Fix: ask Claude to open the project again. Changes that were downloaded are already in your working tree.

More symptoms, such as a refused model object type, are in MCP server troubleshooting.

Related articles