# domo-mcp-readonly (Nsight fork)

**Read-only build** of [BFullenkampDomo/CommunityDomoMCPHelix](https://github.com/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](https://www.domo.com) 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](https://claude.ai/claude-code), compatible with any MCP client, and designed for future [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview).

---

## Quick Start

**One command to install:**

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

Or if running from source:

```bash
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](https://www.npmjs.com/package/ryuu)) **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 &rarr; access token (`/api/oauth2/token`) &rarr; session ID (`/api/oauth2/sid`) &rarr; `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 &rarr; env var fallback &rarr; 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

```bash
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](https://github.com/stahura/domo-ai-vibe-rules) — Community AI skills and rules for the Domo platform
- [Ryuu CLI](https://www.npmjs.com/package/ryuu) — Official Domo developer CLI (`domo login`, `domo publish`)
- [MCP Specification](https://modelcontextprotocol.io) — Model Context Protocol standard

---

## License

MIT