domo-mcp-readonly (Nsight fork)

Read-only build of BFullenkampDomo/CommunityDomoMCPHelix, maintained by the Nsight Automation team for the faster.nsightcare.com /adp/ installer.

• Base: upstream commit 9fc6e5e272717473a7a965356e9aa6ce6493ed67, byte-for-byte (see this repo's first commit).
• Change: a default-deny allowlist in src/tools/registry.ts permits only the 23 query/get/list tools to register. The 17 write/execute tools (create, update, upload, etl_run, code_engine_run, layout lock/unlock, app_add_view) and anything a future upstream merge might add cannot register, so this build structurally cannot change anything in Domo regardless of token permissions.
• package.json and package-lock.json are untouched from upstream; install with npm ci so the lockfile's integrity checksums are enforced.
• Review the full delta: git diff <first-commit> HEAD.

Upstream README follows.

---

Helix — Domo MCP Server

A native-first MCP server that gives AI agents full control of the Domo BI platform. Build analytics experiences end-to-end — from raw data to polished App Studio dashboards — without leaving your AI coding environment.

Built for Claude Code, compatible with any MCP client, and designed for future Claude Managed Agents.

---

Quick Start

One command to install:

claude mcp add --transport stdio domo -- npx -y community-domo-mcp-helix

Or if running from source:

git clone https://github.com/BFullenkampDomo/CommunityDomoMCPHelix.git
cd CommunityDomoMCPHelix
npm install && npm run build
claude mcp add --transport stdio domo -- node $(pwd)/dist/index.js

Prerequisites:

• Node.js 18+
• An active domo login session (via the Domo CLI) or a DOMO_TOKEN environment variable

That's it. The server auto-detects your most recent Domo login and handles authentication transparently.

---

Authentication

Helix resolves credentials automatically in this order:

Priority	Source	How
1	Explicit config	DOMO_INSTANCE + DOMO_TOKEN env vars
2	Ryuu CLI	Reads ~/.config/configstore/ryuu/{instance}.json from your last domo login
3	Auto-detect	Picks the most recently used instance if multiple logins exist

Under the hood:
Refresh token → access token (/api/oauth2/token) → session ID (/api/oauth2/sid) → X-Domo-Authentication header. SIDs are cached for 55 minutes and auto-refresh. Developer tokens (X-Domo-Developer-Token) are used directly when provided via env var.

---

Philosophy: Native First

Domo has two ways to build analytics:

	Native (preferred)	Custom Apps (supplement)
What	Cards, BeastModes, App Studio pages	React/JS apps in iframes
When	Bar charts, KPIs, tables, trend lines — anything Domo's 207 chart types can handle	Complex interactivity, custom UI, data entry forms
Tool	domo_card_create, domo_app_create	domo_custom_app_list

Helix encodes this preference in every tool description. An AI agent using these tools will always reach for native Domo capabilities first and only suggest custom apps when native cards genuinely can't do the job.

---

Tools (36)

Data Layer

Discover, query, and transform data.

Tool	Description
domo_dataset_list	Search datasets by name (nameLike filter, max 50 per call)
domo_dataset_get	Full dataset metadata — schema, row count, owner, cloud info
domo_dataset_schema	Column names, types, and AI metadata
domo_dataset_query	Run SQL against any dataset (SELECT ... FROM table)
domo_dataset_create	Create an empty dataset with a defined schema
domo_search	Cross-entity keyword search (datasets, cards, pages)

Magic ETL

Build and run data pipelines. Always prefer Magic ETL over custom code.

Tool	Description
domo_etl_list	List all dataflows
domo_etl_get	Full dataflow definition (actions, DAG, canvas layout)
domo_etl_create	Create a dataflow with full DAG definition (joins, aggregations, formulas)
domo_etl_update	Update a dataflow definition (PUT replaces entire definition)
domo_etl_run	Trigger execution
domo_etl_execution_status	Poll execution state until SUCCESS or FAILED

Snowflake native? When input datasets come from a Snowflake integration, set computeCloud on the dataflow to the input datasets' cloudId. Check dataset metadata first — mismatched clouds cause indexing failures.

Analytics — Cards & BeastModes

Create native visualizations. Always create BeastModes on the dataset (persisted) for reuse across cards.

Tool	Description
domo_page_cards	List all cards on a page/view
domo_card_get_details	Column definitions, dataset binding, BeastMode references
domo_card_get_data	Rendered data with chart role mappings (ITEM, VALUE, TARGET, SERIES)
domo_card_create	Create a native card (207 chart types) on a page
domo_card_update	Update a card definition (full replacement)
domo_beastmode_validate	Pre-flight formula validation — checks syntax and column references
domo_beastmode_create	Create a persisted calculated field on a dataset

Analytics — App Studio

Build multi-page analytics applications. App Studio is the preferred delivery method — not classic Domo pages.

Tool	Description
domo_app_list	List all App Studio apps
domo_app_create	Create a new app with a default landing view
domo_app_get	Full app structure (views, navigation, theme)
domo_app_update	Update app config (nav orientation, theme, title)
domo_app_add_view	Add a page/view to an app
domo_app_navigation_update	Reorder, rename, and set icons for nav items
domo_stack_get	Full page structure including layout grid and card positions
domo_layout_lock	Acquire write lock (required before layout edits)
domo_layout_update	Position cards on the canvas grid
domo_layout_unlock	Release write lock
domo_page_list	List classic pages (legacy — use domo_app_list for new work)

Administration

Tool	Description
domo_user_list	List users
domo_user_get	User details
domo_group_list	List groups
domo_pdp_list	Personalized Data Permission policies for a dataset
domo_whoami	Current authenticated user

Custom App Platform

Only use when native cards are insufficient.

Tool	Description
domo_custom_app_list	List published custom apps
domo_appdb_query	Query an AppDB collection
domo_code_engine_run	Invoke a Code Engine function

---

End-to-End Workflow

The typical demo build follows this sequence:

 1. Explore          domo_dataset_list → domo_dataset_query
                     Find and understand the source data

 2. Transform        domo_etl_create → domo_etl_run
                     Join, aggregate, compute — output a gold dataset

 3. BeastModes       domo_beastmode_validate → domo_beastmode_create
                     Build reusable calculated fields on the dataset

 4. App Studio       domo_app_create → domo_app_add_view
                     Create the container and pages

 5. Cards            domo_card_create (repeat per card)
                     Build native charts on each view

 6. Layout           domo_stack_get → domo_layout_lock →
                     domo_layout_update → domo_layout_unlock
                     Position cards on the canvas grid

 7. Polish           domo_app_update → domo_app_navigation_update
                     Set nav orientation, icons, theme

---

App Studio vs Classic Pages

These are completely separate systems with different APIs:

	Classic Pages (legacy)	App Studio Apps (preferred)
Create	POST /content/v1/pages	POST /content/v1/dataapps
Layout API	None	Full canvas grid (v4 write locks)
Navigation	Domo global nav	Custom per-app (LEFT / TOP / BOTTOM)
Theming	Instance defaults	Custom themes, colors, icons
Multi-page	Flat hierarchy	Views with parent/child structure
Use for	Discovery / listing only	All new work

---

Layout Grid Reference

App Studio uses a unit-based grid system:

Property	Desktop (standard)	Mobile (compact)
Grid width	60 units	12 units
Aspect ratio	1.67	1.0
Frame margin	4	4
Frame padding	8	8

Content types: CARD, HEADER, SEPARATOR, PAGE_BREAK

Key rule: Every contentKey in the content[] array must appear in both standard.template and compact.template. Missing entries cause 400 Bad Request.

Cards on the main canvas: virtual: false, virtualAppendix: false
Cards in the appendix: virtual: true, virtualAppendix: true

Cards created via the API land in the appendix by default. Use domo_layout_update to move them to the main canvas.

---

Magic ETL Reference

Action Types

Type	Description	Key Fields
LoadFromVault	Input dataset	dataSourceId
MergeJoin	Join two streams	joinType, keys1/keys2, step1/step2, schemaModification2
GroupBy	Aggregation	groups, fields (SUM, COUNT_ALL, AVERAGE, MIN, MAX)
ExpressionEvaluator	Computed columns	expressions[].expression, expressions[].fieldName
WindowAction	Rank, lag/lead	groupRules, orderRules, additions
SelectValues	Pick/rename columns	fields[].name, fields[].rename
SplitFilter	Conditional branches	branches[].predicate, elseTable
UnionAll	Append rows	inputs[], schemaSource
PublishToVault	Output dataset	dataSource, versionChainType

Canvas Sections

Organize tiles into colored zones for readability:

Color Variable	Suggested Use
var(--colorChartBlue6)	Input / staging
var(--colorChartOrange6)	Transforms / enrichment
var(--colorChartGreen6)	Validation / aggregation
var(--colorChartPurple6)	Output / publishing

Join Types

joinType	relationshipType
LEFT OUTER	MTM (not MANY_TO_MANY)
INNER	MTM
RIGHT OUTER	MTM
FULL OUTER	MTM

---

Architecture

Claude Code / Claude Managed Agent
         |
    MCP Protocol (stdio or HTTP)
         |
   Helix MCP Server (Node.js / TypeScript)
         |
    +----+----+
    |         |
  Auth      Tools
    |         |
    |    +----+--------+----------+----------+
    |    |    Data     | Analytics |  Admin   | Custom App
    |    |  datasets   | cards     | users    | appdb
    |    |  etl        | beastmode | groups   | code engine
    |    |  search     | app studio| pdp      |
    |    |             | layout    |          |
    |    +----+--------+----------+----------+
    |         |
    +----+----+
         |
    Domo REST APIs
    (X-Domo-Authentication: {SID})

Auth resolution: Ryuu CLI configstore → env var fallback → helpful error message.
SID caching: 55-minute TTL, auto-refresh on expiry.
Multi-instance: Supports all instances from domo login — auto-selects most recent.

---

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm start            # Run the MCP server

npx tsx src/test-auth.ts [instance]   # Smoke test authentication

Project Structure

src/
  index.ts                  MCP server entry point (stdio transport)
  auth/
    domo-auth.ts            Unified auth class (resolve, cache, fetch)
    ryuu-store.ts           Read ryuu CLI credentials
    token-exchange.ts       Refresh token -> access token -> SID
    types.ts                Type definitions
  tools/
    registry.ts             Registers all tool groups
    data/index.ts           Dataset, ETL, and search tools
    analytics/index.ts      Cards, BeastMode, App Studio, layout tools
    admin/index.ts          User, group, PDP tools
    custom-app/index.ts     AppDB, Code Engine tools

---

Related Projects

• domo-ai-vibe-rules — Community AI skills and rules for the Domo platform
• Ryuu CLI — Official Domo developer CLI (domo login, domo publish)
• MCP Specification — Model Context Protocol standard

---

License

MIT