coalesce-transform-mcp 0.5.0-alpha.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +598 -344
- package/dist/coalesce/run-schemas.d.ts +50 -10
- package/dist/coalesce/run-schemas.d.ts.map +1 -1
- package/dist/coalesce/run-schemas.js +24 -5
- package/dist/coalesce/run-schemas.js.map +1 -1
- package/dist/mcp/runs.js +1 -1
- package/dist/mcp/runs.js.map +1 -1
- package/dist/mcp/tool-helpers.d.ts.map +1 -1
- package/dist/mcp/tool-helpers.js +14 -3
- package/dist/mcp/tool-helpers.js.map +1 -1
- package/dist/resources/context/run-operations.md +6 -0
- package/dist/tasks/run-and-wait-task.d.ts.map +1 -1
- package/dist/tasks/run-and-wait-task.js +3 -2
- package/dist/tasks/run-and-wait-task.js.map +1 -1
- package/dist/tasks/start-run-task.d.ts.map +1 -1
- package/dist/tasks/start-run-task.js +3 -2
- package/dist/tasks/start-run-task.js.map +1 -1
- package/dist/workflows/run-and-wait.d.ts.map +1 -1
- package/dist/workflows/run-and-wait.js +2 -2
- package/dist/workflows/run-and-wait.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,113 +1,154 @@
|
|
|
1
1
|
# coalesce-transform-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/coalesce-transform-mcp)
|
|
4
|
+
[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522coalesce-transform%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522coalesce-transform-mcp%2522%255D%257D)
|
|
5
|
+
[](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522coalesce-transform%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522coalesce-transform-mcp%2522%255D%257D)
|
|
6
|
+
[](https://cursor.com/install-mcp?name=coalesce-transform&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJjb2FsZXNjZS10cmFuc2Zvcm0tbWNwIl19)
|
|
7
|
+
[](LICENSE)
|
|
4
8
|
|
|
5
|
-
|
|
6
|
-
- **Local COA CLI tools** — validate projects before check-in, preview generated DDL/DML (`--dry-run`), iterate on V2 `.sql` node files, run `plan → deploy → refresh` cycles. COA is bundled — no separate install.
|
|
9
|
+
MCP server for [Coalesce](https://coalesce.io/). Built for **Snowflake [Cortex Code](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code-cli) (CoCo)** - with first-class support for every other MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf). Manage nodes, pipelines, environments, jobs, and runs, and drive the local-first [`coa`](https://www.npmjs.com/package/@coalescesoftware/coa) CLI from the same server: validate a project, preview DDL/DML, plan a deployment, and apply it to a cloud environment.
|
|
7
10
|
|
|
8
|
-
|
|
11
|
+
- **Cloud REST tools** - build pipelines declaratively, edit node YAML, review lineage, run deployed jobs, audit documentation.
|
|
12
|
+
- **Local COA CLI tools** - validate projects before check-in, preview generated DDL/DML (`--dry-run`), run `plan → deploy → refresh` cycles. COA is bundled - no separate install.
|
|
13
|
+
|
|
14
|
+
---
|
|
9
15
|
|
|
10
16
|
## I want to…
|
|
11
17
|
|
|
12
|
-
| Task | Jump to |
|
|
13
|
-
| ---- | ------- |
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
|
20
|
-
|
|
|
21
|
-
|
|
|
22
|
-
|
|
|
23
|
-
|
|
|
18
|
+
| | Task | Jump to |
|
|
19
|
+
| :-: | ---- | ------- |
|
|
20
|
+
| 📦 | Install for my AI client | [Installation](#installation) |
|
|
21
|
+
| 🚀 | Get running in 2 minutes | [Quick start](#quick-start) |
|
|
22
|
+
| 🎛️ | Customize agent behavior | [Skills](#skills) |
|
|
23
|
+
| 🔍 | Find a specific tool | [Tools](#tools) |
|
|
24
|
+
| 🔑 | Authenticate (env var or `~/.coa/config`) | [Credentials](#credentials) |
|
|
25
|
+
| 🌐 | Run against multiple Coalesce environments | [Multiple environments](#multiple-environments) |
|
|
26
|
+
| 🔒 | Lock prod down to read-only | [Safety model](docs/safety-model.md) |
|
|
27
|
+
| 🧰 | Use the `coa` CLI tools | [Using the COA CLI tools](#using-the-coa-cli-tools) |
|
|
28
|
+
| 🧪 | Try a prerelease build | [Prerelease channel](docs/prerelease.md) |
|
|
29
|
+
| 🩺 | Debug "why isn't auth working?" | [Diagnosing setup](docs/diagnosing-setup.md) |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
Each link below opens a short install guide with a click-to-install button (where supported) and the manual config.
|
|
36
|
+
|
|
37
|
+
| Client | Install guide |
|
|
38
|
+
| ------ | ------------- |
|
|
39
|
+
| ❄️ **Snowflake Cortex Code (CoCo)** | [docs/installation-guides/cortex-code.md](docs/installation-guides/cortex-code.md) |
|
|
40
|
+
| Cursor | [docs/installation-guides/cursor.md](docs/installation-guides/cursor.md) |
|
|
41
|
+
| VS Code | [docs/installation-guides/vscode.md](docs/installation-guides/vscode.md) |
|
|
42
|
+
| VS Code Insiders | [docs/installation-guides/vscode-insiders.md](docs/installation-guides/vscode-insiders.md) |
|
|
43
|
+
| Claude Code (CLI) | [docs/installation-guides/claude-code.md](docs/installation-guides/claude-code.md) |
|
|
44
|
+
| Claude Desktop | [docs/installation-guides/claude-desktop.md](docs/installation-guides/claude-desktop.md) |
|
|
45
|
+
| Windsurf | [docs/installation-guides/windsurf.md](docs/installation-guides/windsurf.md) |
|
|
46
|
+
|
|
47
|
+
Or expand the dropdown for your client below to paste directly without leaving this page.
|
|
24
48
|
|
|
25
|
-
|
|
49
|
+
<details>
|
|
50
|
+
<summary><b>❄️ Install in Snowflake Cortex Code (CoCo)</b></summary>
|
|
26
51
|
|
|
27
|
-
**
|
|
52
|
+
**Why this pairing?** Cortex Code is Snowflake's AI coding CLI - it already authenticates to your warehouse, runs under your Snowflake role, and has native tools for querying live data. Add `coalesce-transform-mcp` and a single agent session can plan pipelines, create nodes, run DML, and verify results against real rows without leaving the terminal.
|
|
28
53
|
|
|
29
|
-
- [
|
|
30
|
-
- A [Coalesce](https://coalesce.io/) account with a workspace
|
|
31
|
-
- An MCP-compatible AI client (Claude Code, Claude Desktop, Cursor, Windsurf)
|
|
32
|
-
- Snowflake credentials — only if you plan to use run tools or `coa_create`/`coa_run` (see [Credentials](#credentials))
|
|
33
|
-
- Install footprint is ~76 MB unpacked (the bundled `@coalescesoftware/coa` CLI ships its own runtime; the MCP tarball itself is under 1 MB)
|
|
54
|
+
One-liner (after [installing the Cortex Code CLI](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code-cli)):
|
|
34
55
|
|
|
35
|
-
|
|
56
|
+
```bash
|
|
57
|
+
cortex mcp add coalesce-transform npx coalesce-transform-mcp
|
|
58
|
+
```
|
|
36
59
|
|
|
37
|
-
|
|
60
|
+
Or edit `~/.snowflake/cortex/mcp.json` directly:
|
|
38
61
|
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"coalesce-transform": {
|
|
66
|
+
"type": "stdio",
|
|
67
|
+
"command": "npx",
|
|
68
|
+
"args": ["coalesce-transform-mcp"],
|
|
69
|
+
"env": {
|
|
70
|
+
"COALESCE_ACCESS_TOKEN": "<YOUR_TOKEN>"
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
42
75
|
```
|
|
43
76
|
|
|
44
|
-
|
|
77
|
+
Drop the `env` block if you're using `~/.coa/config` - Cortex Code and Coalesce can both pick the token up from the same profile. Full walkthrough: **[docs/installation-guides/cortex-code.md](docs/installation-guides/cortex-code.md)**.
|
|
45
78
|
|
|
46
|
-
|
|
79
|
+
</details>
|
|
47
80
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
81
|
+
<details>
|
|
82
|
+
<summary><b>Install in Cursor</b></summary>
|
|
83
|
+
|
|
84
|
+
Click-to-install: [](https://cursor.com/install-mcp?name=coalesce-transform&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJjb2FsZXNjZS10cmFuc2Zvcm0tbWNwIl19)
|
|
85
|
+
|
|
86
|
+
Manual: paste into `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"mcpServers": {
|
|
91
|
+
"coalesce-transform": {
|
|
92
|
+
"command": "npx",
|
|
93
|
+
"args": ["coalesce-transform-mcp"],
|
|
94
|
+
"env": {
|
|
95
|
+
"COALESCE_ACCESS_TOKEN": "<YOUR_TOKEN>"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
58
100
|
```
|
|
59
101
|
|
|
60
|
-
|
|
102
|
+
Cursor does **not** expand `${VAR}` - paste the literal token, or drop the `env` block and use `~/.coa/config` (see [Credentials](#credentials)).
|
|
61
103
|
|
|
62
|
-
|
|
104
|
+
</details>
|
|
63
105
|
|
|
64
|
-
|
|
106
|
+
<details>
|
|
107
|
+
<summary><b>Install in VS Code</b></summary>
|
|
65
108
|
|
|
66
|
-
|
|
109
|
+
Click-to-install: [](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522coalesce-transform%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522coalesce-transform-mcp%2522%255D%257D)
|
|
67
110
|
|
|
68
|
-
|
|
111
|
+
Manual: follow the [VS Code MCP install guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) and use this config:
|
|
69
112
|
|
|
70
|
-
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"name": "coalesce-transform",
|
|
116
|
+
"command": "npx",
|
|
117
|
+
"args": ["coalesce-transform-mcp"]
|
|
118
|
+
}
|
|
119
|
+
```
|
|
71
120
|
|
|
72
|
-
|
|
73
|
-
npx @coalescesoftware/coa doctor --fix
|
|
74
|
-
```
|
|
121
|
+
Add the `COALESCE_ACCESS_TOKEN` via VS Code's secret input prompt, or drop the token and use `~/.coa/config`. Reload the VS Code window after install.
|
|
75
122
|
|
|
76
|
-
|
|
123
|
+
</details>
|
|
77
124
|
|
|
78
|
-
|
|
79
|
-
|
|
125
|
+
<details>
|
|
126
|
+
<summary><b>Install in VS Code Insiders</b></summary>
|
|
80
127
|
|
|
81
|
-
|
|
82
|
-
# workspaces.yml — keys are workspace names; `dev` is the default if --workspace is omitted
|
|
83
|
-
dev:
|
|
84
|
-
connection: snowflake # required — name of the connection block COA should use
|
|
85
|
-
locations: # optional — one entry per storage location name from locations.yml
|
|
86
|
-
SRC_INGEST_TASTY_BITES:
|
|
87
|
-
database: JESSE_DEV # required
|
|
88
|
-
schema: INGEST_TASTY_BITES # required
|
|
89
|
-
ETL_STAGE:
|
|
90
|
-
database: JESSE_DEV
|
|
91
|
-
schema: ETL_STAGE
|
|
92
|
-
ANALYTICS:
|
|
93
|
-
database: JESSE_DEV
|
|
94
|
-
schema: ANALYTICS
|
|
95
|
-
```
|
|
128
|
+
Click-to-install: [](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522coalesce-transform%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522coalesce-transform-mcp%2522%255D%257D)
|
|
96
129
|
|
|
97
|
-
|
|
130
|
+
Manual: identical to the stable [VS Code install](docs/installation-guides/vscode.md) - Insiders reads the same MCP config.
|
|
98
131
|
|
|
99
|
-
|
|
132
|
+
</details>
|
|
100
133
|
|
|
101
|
-
|
|
102
|
-
|
|
134
|
+
<details>
|
|
135
|
+
<summary><b>Install in Claude Code (CLI)</b></summary>
|
|
103
136
|
|
|
104
|
-
|
|
137
|
+
One-liner:
|
|
105
138
|
|
|
106
|
-
|
|
139
|
+
```bash
|
|
140
|
+
claude mcp add coalesce-transform -- npx coalesce-transform-mcp
|
|
141
|
+
```
|
|
107
142
|
|
|
108
|
-
|
|
143
|
+
Pass env vars inline if you need them:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
claude mcp add coalesce-transform \
|
|
147
|
+
--env COALESCE_ACCESS_TOKEN=$COALESCE_ACCESS_TOKEN \
|
|
148
|
+
-- npx coalesce-transform-mcp
|
|
149
|
+
```
|
|
109
150
|
|
|
110
|
-
|
|
151
|
+
Manual: paste into `.mcp.json` in your project root (or `~/.claude.json` for global):
|
|
111
152
|
|
|
112
153
|
```json
|
|
113
154
|
{
|
|
@@ -123,9 +164,14 @@ File: `.mcp.json` in project root (or `~/.claude.json` for global).
|
|
|
123
164
|
}
|
|
124
165
|
```
|
|
125
166
|
|
|
126
|
-
Claude Code
|
|
167
|
+
Claude Code **does** expand `${VAR}` from your shell env at load time - `.mcp.json` can stay safely committed to git with variable references. Omit the `env` block if using `~/.coa/config`.
|
|
168
|
+
|
|
169
|
+
</details>
|
|
170
|
+
|
|
171
|
+
<details>
|
|
172
|
+
<summary><b>Install in Claude Desktop</b></summary>
|
|
127
173
|
|
|
128
|
-
|
|
174
|
+
No deeplink yet - paste manually.
|
|
129
175
|
|
|
130
176
|
File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
|
|
131
177
|
|
|
@@ -143,11 +189,16 @@ File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
|
|
|
143
189
|
}
|
|
144
190
|
```
|
|
145
191
|
|
|
146
|
-
Claude Desktop does **not** expand `${VAR}`
|
|
192
|
+
Claude Desktop does **not** expand `${VAR}` - paste the literal token, or drop the `env` block and use `~/.coa/config`. Fully quit Claude Desktop (`Cmd+Q`) and relaunch after editing.
|
|
147
193
|
|
|
148
|
-
|
|
194
|
+
</details>
|
|
195
|
+
|
|
196
|
+
<details>
|
|
197
|
+
<summary><b>Install in Windsurf</b></summary>
|
|
149
198
|
|
|
150
|
-
|
|
199
|
+
No deeplink yet - paste manually.
|
|
200
|
+
|
|
201
|
+
File: `~/.codeium/windsurf/mcp_config.json`.
|
|
151
202
|
|
|
152
203
|
```json
|
|
153
204
|
{
|
|
@@ -163,39 +214,149 @@ File: `.cursor/mcp.json` in project root (or `~/.cursor/mcp.json` for global).
|
|
|
163
214
|
}
|
|
164
215
|
```
|
|
165
216
|
|
|
166
|
-
|
|
217
|
+
Windsurf does **not** expand `${VAR}` - paste the literal token, or drop the `env` block and use `~/.coa/config`. Restart Windsurf after editing.
|
|
218
|
+
|
|
219
|
+
</details>
|
|
167
220
|
|
|
168
|
-
|
|
221
|
+
> [!CAUTION]
|
|
222
|
+
> **Never hardcode credentials in git-tracked config files.** Only Claude Code's `.mcp.json` expands `${VAR}` from your shell env. For any other client, keep secrets in `~/.coa/config` or a secrets manager your client integrates with - don't commit literals into these JSON files.
|
|
169
223
|
|
|
170
|
-
|
|
224
|
+
> [!TIP]
|
|
225
|
+
> **❄️ Snowflake Cortex Code + coalesce-transform-mcp.** CoCo is Snowflake's AI coding CLI - it already knows your warehouse, role, and data. Drop this MCP in and an agent can plan pipelines, create nodes, run DML, and verify results in a single session, all under Snowflake's auth model. **[Install in Cortex Code →](docs/installation-guides/cortex-code.md)**
|
|
226
|
+
|
|
227
|
+
> [!TIP]
|
|
228
|
+
> The two surfaces are orthogonal. Use both, one, or neither. Every destructive tool - on either surface - requires explicit confirmation before running. New? Run the `/coalesce-setup` prompt after install - it walks you through anything missing.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## Quick start
|
|
233
|
+
|
|
234
|
+
**Requirements:**
|
|
235
|
+
|
|
236
|
+
- [Node.js](https://nodejs.org/) 22+
|
|
237
|
+
- A [Coalesce](https://coalesce.io/) account with a workspace
|
|
238
|
+
- An MCP-compatible AI client (see [Installation](#installation))
|
|
239
|
+
- Snowflake credentials - only if you plan to use run tools or `coa_create`/`coa_run` (see [Credentials](#credentials))
|
|
240
|
+
- Install footprint is ~76 MB unpacked (the bundled `@coalescesoftware/coa` CLI ships its own runtime; the MCP tarball itself is under 1 MB)
|
|
241
|
+
|
|
242
|
+
**1. Clone your project.** If your team already has a Coalesce project in Git, clone it locally - the bundled `coa` CLI operates on a project directory, so most local create/run tools require one on disk:
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
git clone <your-coalesce-project-repo-url>
|
|
246
|
+
cd my-project
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Don't have a Git-linked project yet? In the Coalesce UI, open your workspace → **Settings → Git** and connect a repo (or create one via your Git provider and paste the URL). Coalesce will commit the project skeleton on first push; clone that repo locally once it's populated.
|
|
250
|
+
|
|
251
|
+
<details>
|
|
252
|
+
<summary>What's in a Coalesce project directory?</summary>
|
|
253
|
+
|
|
254
|
+
```text
|
|
255
|
+
my-project/
|
|
256
|
+
├── data.yml # Root metadata (fileVersion, platformKind)
|
|
257
|
+
├── locations.yml # Storage location manifest
|
|
258
|
+
├── nodes/ # Pipeline nodes (.yml for V1, .sql for V2)
|
|
259
|
+
├── nodeTypes/ # Node type definitions with templates
|
|
260
|
+
├── environments/ # Environment configs with storage mappings
|
|
261
|
+
├── macros/ # Reusable SQL macros
|
|
262
|
+
├── jobs/ # Job definitions
|
|
263
|
+
└── subgraphs/ # Subgraph definitions
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
**V1 vs V2** - the format is pinned by `fileVersion` in `data.yml`. **V1** (`fileVersion: 1` or `2`) stores each node as a single YAML file with columns, transforms, and config inline. **V2** (`fileVersion: 3`) is SQL-first: the node body lives in a `.sql` file using `@id` / `@nodeType` annotations and `{{ ref() }}` references, with YAML retained for config. New projects default to V2; existing V1 projects keep working unchanged.
|
|
267
|
+
|
|
268
|
+
</details>
|
|
269
|
+
|
|
270
|
+
Point the MCP at this directory by setting `repoPath` in `~/.coa/config` or `COALESCE_REPO_PATH` in your env block.
|
|
271
|
+
|
|
272
|
+
**2. Create `workspaces.yml`.** This file is **required** for `coa_create` / `coa_run` and their dry-run variants. It maps each storage location declared in `locations.yml` to a physical database + schema for local development. It's typically gitignored (per-developer), so cloning the project does not give it to you - you have to create it.
|
|
273
|
+
|
|
274
|
+
The `/coalesce-setup` prompt detects a missing `workspaces.yml` and walks you through it. If you'd rather do it directly, pick one of:
|
|
275
|
+
|
|
276
|
+
- **Let COA bootstrap it** (easiest): from the project root, run
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
npx @coalescesoftware/coa doctor --fix
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Or from your MCP client, call the `coa_bootstrap_workspaces` tool (requires `confirmed: true`) which runs the same command.
|
|
283
|
+
|
|
284
|
+
> [!WARNING]
|
|
285
|
+
> **The generated file contains placeholder values.** `coa doctor --fix` seeds `database`/`schema` with defaults that won't match your real warehouse. Open the file and replace every placeholder before running `coa_create` / `coa_run` - otherwise the generated DDL/DML will target the wrong (or non-existent) database.
|
|
286
|
+
|
|
287
|
+
- **Hand-write it.** Authoritative schema (from `coa describe schema workspaces` - no top-level wrapper, no `fileVersion`):
|
|
288
|
+
|
|
289
|
+
```yaml
|
|
290
|
+
# workspaces.yml - keys are workspace names; `dev` is the default if --workspace is omitted
|
|
291
|
+
dev:
|
|
292
|
+
connection: snowflake # required - name of the connection block COA should use
|
|
293
|
+
locations: # optional - one entry per storage location name from locations.yml
|
|
294
|
+
SRC_INGEST_TASTY_BITES:
|
|
295
|
+
database: JESSE_DEV # required
|
|
296
|
+
schema: INGEST_TASTY_BITES # required
|
|
297
|
+
ETL_STAGE:
|
|
298
|
+
database: JESSE_DEV
|
|
299
|
+
schema: ETL_STAGE
|
|
300
|
+
ANALYTICS:
|
|
301
|
+
database: JESSE_DEV
|
|
302
|
+
schema: ANALYTICS
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Verify with `coa_doctor` (or `npx @coalescesoftware/coa doctor`) - it checks `data.yml`, `workspaces.yml`, credentials, and warehouse connectivity end to end.
|
|
306
|
+
|
|
307
|
+
**3. Pick an auth path:**
|
|
308
|
+
|
|
309
|
+
<table>
|
|
310
|
+
<tr>
|
|
311
|
+
<th>Option A - env var</th>
|
|
312
|
+
<th>Option B - reuse <code>~/.coa/config</code></th>
|
|
313
|
+
</tr>
|
|
314
|
+
<tr valign="top">
|
|
315
|
+
<td>
|
|
316
|
+
|
|
317
|
+
Simplest for first-time MCP users. Generate a `COALESCE_ACCESS_TOKEN` from Coalesce → Deploy → User Settings, then include it in your client config:
|
|
171
318
|
|
|
172
319
|
```json
|
|
173
320
|
{
|
|
174
|
-
"
|
|
175
|
-
"
|
|
176
|
-
"command": "npx",
|
|
177
|
-
"args": ["coalesce-transform-mcp"],
|
|
178
|
-
"env": {
|
|
179
|
-
"COALESCE_ACCESS_TOKEN": "<YOUR_TOKEN>"
|
|
180
|
-
}
|
|
181
|
-
}
|
|
321
|
+
"env": {
|
|
322
|
+
"COALESCE_ACCESS_TOKEN": "<YOUR_TOKEN>"
|
|
182
323
|
}
|
|
183
324
|
}
|
|
184
325
|
```
|
|
185
326
|
|
|
186
|
-
|
|
327
|
+
</td>
|
|
328
|
+
<td>
|
|
329
|
+
|
|
330
|
+
Best if you already use the `coa` CLI - the server reads the same profile file, so nothing to duplicate. Drop the `env` block entirely:
|
|
331
|
+
|
|
332
|
+
```json
|
|
333
|
+
{
|
|
334
|
+
"command": "npx",
|
|
335
|
+
"args": ["coalesce-transform-mcp"]
|
|
336
|
+
}
|
|
337
|
+
```
|
|
187
338
|
|
|
188
|
-
|
|
339
|
+
See [Credentials](#credentials) for the profile schema.
|
|
189
340
|
|
|
190
|
-
>
|
|
341
|
+
</td>
|
|
342
|
+
</tr>
|
|
343
|
+
</table>
|
|
344
|
+
|
|
345
|
+
When both sources set a field, the env var wins.
|
|
346
|
+
|
|
347
|
+
**4. Install the server** via one of the [Installation](#installation) paths above.
|
|
348
|
+
|
|
349
|
+
**5. Restart your client,** then run the `/coalesce-setup` prompt to verify everything is wired up.
|
|
191
350
|
|
|
192
351
|
If you have more than one Coalesce environment to manage, see [Multiple environments](#multiple-environments).
|
|
193
352
|
|
|
353
|
+
---
|
|
354
|
+
|
|
194
355
|
## Configuration
|
|
195
356
|
|
|
196
357
|
### Credentials
|
|
197
358
|
|
|
198
|
-
The server reads credentials from two sources and merges them with **env-wins precedence**
|
|
359
|
+
The server reads credentials from two sources and merges them with **env-wins precedence** - a matching env var always overrides the profile value, so you can pin a single field per session without editing the config file. Call `diagnose_setup` to see which source supplied each value.
|
|
199
360
|
|
|
200
361
|
#### Source 1: `~/.coa/config` (shared with the `coa` CLI)
|
|
201
362
|
|
|
@@ -205,11 +366,11 @@ COA stores credentials in a standard INI file. You create it by hand, or let `co
|
|
|
205
366
|
[default]
|
|
206
367
|
token=<your-coalesce-refresh-token>
|
|
207
368
|
domain=https://your-org.app.coalescesoftware.io
|
|
208
|
-
snowflakeAccount=<your-snowflake-account> # e.g., abc12345.us-east-1
|
|
369
|
+
snowflakeAccount=<your-snowflake-account> # e.g., abc12345.us-east-1 - required by coa CLI
|
|
209
370
|
snowflakeUsername=YOUR_USER
|
|
210
371
|
snowflakeRole=YOUR_ROLE
|
|
211
372
|
snowflakeWarehouse=YOUR_WAREHOUSE
|
|
212
|
-
snowflakeKeyPairKey=/Users/you/.coa/rsa_key.p8
|
|
373
|
+
snowflakeKeyPairKey=/Users/you/.coa/rsa_key.p8
|
|
213
374
|
snowflakeAuthType=KeyPair
|
|
214
375
|
orgID=<your-org-id> # optional; fallback for cancel-run
|
|
215
376
|
repoPath=/Users/you/path/to/repo # optional; for repo-backed tools
|
|
@@ -219,11 +380,24 @@ cacheDir=/Users/you/.coa/cache # optional; per-profile cache isolation
|
|
|
219
380
|
# …additional profiles; select with COALESCE_PROFILE
|
|
220
381
|
```
|
|
221
382
|
|
|
222
|
-
|
|
383
|
+
**Key mapping** - each profile key maps to an env var of the same concept:
|
|
384
|
+
|
|
385
|
+
| Profile key | Env var |
|
|
386
|
+
| ----------- | ------- |
|
|
387
|
+
| `token` | `COALESCE_ACCESS_TOKEN` |
|
|
388
|
+
| `domain` | `COALESCE_BASE_URL` |
|
|
389
|
+
| `snowflake*` (all keys) | `SNOWFLAKE_*` (matching suffix) |
|
|
390
|
+
| `orgID` | `COALESCE_ORG_ID` |
|
|
391
|
+
| `repoPath` | `COALESCE_REPO_PATH` |
|
|
392
|
+
| `cacheDir` | `COALESCE_CACHE_DIR` |
|
|
223
393
|
|
|
224
|
-
|
|
394
|
+
Notes:
|
|
225
395
|
|
|
226
|
-
|
|
396
|
+
- `snowflakeAuthType` is read by COA itself (no env var) - include it when using key-pair auth.
|
|
397
|
+
- `orgID`, `repoPath`, and `cacheDir` are MCP-specific - the COA CLI ignores them.
|
|
398
|
+
- Only the fields the MCP needs are shown above. COA's config supports many more - run `npx @coalescesoftware/coa describe config` for the authoritative reference. Unknown keys are ignored.
|
|
399
|
+
|
|
400
|
+
If `~/.coa/config` doesn't exist the server runs env-only - startup never fails on a missing or malformed profile file; it just logs a stderr warning.
|
|
227
401
|
|
|
228
402
|
#### Source 2: env vars in your MCP config
|
|
229
403
|
|
|
@@ -259,11 +433,12 @@ If `~/.coa/config` doesn't exist the server runs env-only — startup never fail
|
|
|
259
433
|
| `SNOWFLAKE_ROLE` | Yes | Snowflake user role |
|
|
260
434
|
<!-- ENV_METADATA_SNOWFLAKE_TABLE_END -->
|
|
261
435
|
|
|
262
|
-
"Required" means one of env OR the matching `~/.coa/config` field must supply the value. **`SNOWFLAKE_PAT` is env-only**
|
|
436
|
+
"Required" means one of env OR the matching `~/.coa/config` field must supply the value. **`SNOWFLAKE_PAT` is env-only** - COA's config uses `snowflakePassword` for Basic auth (a different concept), which this server deliberately doesn't read.
|
|
263
437
|
|
|
264
438
|
#### Field-level overrides
|
|
265
439
|
|
|
266
|
-
|
|
440
|
+
<details>
|
|
441
|
+
<summary>Pin a profile but override one field without editing the config file</summary>
|
|
267
442
|
|
|
268
443
|
```json
|
|
269
444
|
{
|
|
@@ -280,8 +455,13 @@ To pin a profile but override one field without editing the config file:
|
|
|
280
455
|
|
|
281
456
|
Reads: "use the `[staging]` profile, but override its `snowflakeRole`."
|
|
282
457
|
|
|
458
|
+
</details>
|
|
459
|
+
|
|
283
460
|
### Multiple environments
|
|
284
461
|
|
|
462
|
+
<details>
|
|
463
|
+
<summary>Register dev / staging / prod as separate namespaced servers</summary>
|
|
464
|
+
|
|
285
465
|
If you work across several Coalesce environments (dev/staging/prod, or multiple orgs), register the package once per profile under distinct server names:
|
|
286
466
|
|
|
287
467
|
```json
|
|
@@ -310,353 +490,427 @@ Why this pattern:
|
|
|
310
490
|
- **Per-environment safety.** Pair prod with `COALESCE_MCP_READ_ONLY=true` to hide every write tool on that server while leaving dev fully writable.
|
|
311
491
|
- **No per-call profile juggling.** Each server is pinned at startup.
|
|
312
492
|
|
|
313
|
-
Skip this pattern if you only use one environment
|
|
314
|
-
|
|
315
|
-
### Safety model
|
|
316
|
-
|
|
317
|
-
Three layers prevent destructive surprises:
|
|
318
|
-
|
|
319
|
-
1. **Tool annotations.** Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`). Clients that respect them can filter proactively. The ⚠️ marker in [Tool reference](#tool-reference) marks `destructiveHint: true` tools.
|
|
320
|
-
2. **`COALESCE_MCP_READ_ONLY=true`** hides all write/mutation tools at server startup. Only read, list, search, cache, analyze, review, diagnose, and plan tools are registered. Use it for audits, agent sandboxes, or pairing with a prod profile (see [Multiple environments](#multiple-environments)).
|
|
321
|
-
3. **Explicit confirmation for destructive ops.** Tools marked destructive require `confirmed: true`. When the MCP client supports elicitation, the server prompts interactively; otherwise it returns a `STOP_AND_CONFIRM` response the agent must surface before retrying with `confirmed: true`. Applies to: `delete_*`, `propagate_column_change`, `cancel_run`, `clear_data_cache`, `coa_create`, `coa_run`, `coa_deploy`, `coa_refresh`.
|
|
322
|
-
|
|
323
|
-
**COA preflight.** Local COA write tools run preflight validation before shelling out. Errors block execution; warnings pass through in the tool response as `preflightWarnings` so agents can surface them.
|
|
493
|
+
Skip this pattern if you only use one environment - a single registration is simpler. For 2–3 environments it's worth the extra config; beyond that, each server is a separate Node process, so consider whether you actually need them all loaded at once.
|
|
324
494
|
|
|
325
|
-
|
|
326
|
-
| ---- | ----- | --------------- |
|
|
327
|
-
| `SQL_DOUBLE_QUOTED_REF` | error | `.sql` nodes using `ref("…")` — silently returns `UNKNOWN` columns; must be single-quoted |
|
|
328
|
-
| `WORKSPACES_YML_MISSING` | error | `workspaces.yml` not in project root — required for local create/run |
|
|
329
|
-
| `SELECTOR_COMBINED_OR` | error | `{ A \|\| B }` selector form — matches zero nodes; must be `{ A } \|\| { B }` |
|
|
330
|
-
| `SQL_LITERAL_UNION_ALL` | warning | Literal `UNION ALL` in a V2 `.sql` node — silently dropped by the V2 parser; use `insertStrategy: UNION ALL` instead |
|
|
331
|
-
| `DATA_YML_UNEXPECTED_FILEVERSION` | warning | `data.yml` missing or not `fileVersion: 3` |
|
|
332
|
-
| `DATA_YML_NO_FILEVERSION` | warning | `data.yml` has no `fileVersion` field |
|
|
495
|
+
</details>
|
|
333
496
|
|
|
334
497
|
### Using the COA CLI tools
|
|
335
498
|
|
|
336
|
-
COA is bundled
|
|
499
|
+
COA is bundled - no extra install. Usage notes:
|
|
337
500
|
|
|
338
501
|
- **Local commands** (`coa_doctor`, `coa_validate`, `coa_dry_run_create`, `coa_dry_run_run`, `coa_create`, `coa_run`, `coa_plan`) need a COA project directory (one that contains `data.yml`). Pass the path via the `projectPath` tool argument.
|
|
339
|
-
- **Cloud commands** (`coa_list_environments`, `coa_list_environment_nodes`, `coa_list_runs`, `coa_deploy`, `coa_refresh`) read credentials from `~/.coa/config`
|
|
340
|
-
- **Profile resolution.** Cloud tools accept an optional `profile` arg. When omitted, they fall back to `COALESCE_PROFILE`, then to COA's own `[default]`
|
|
502
|
+
- **Cloud commands** (`coa_list_environments`, `coa_list_environment_nodes`, `coa_list_runs`, `coa_deploy`, `coa_refresh`) read credentials from `~/.coa/config` - the same file the MCP uses. Populate it once and both surfaces agree.
|
|
503
|
+
- **Profile resolution.** Cloud tools accept an optional `profile` arg. When omitted, they fall back to `COALESCE_PROFILE`, then to COA's own `[default]` - so you don't have to pass it on every call.
|
|
341
504
|
- **Warehouse-touching commands** (`coa_create`, `coa_run`) need a valid `workspaces.yml` in the project root with storage-location mappings. Preflight catches a missing file before execution.
|
|
342
505
|
|
|
343
|
-
###
|
|
506
|
+
### Safety model
|
|
344
507
|
|
|
345
|
-
|
|
508
|
+
Three layers prevent destructive surprises. See [docs/safety-model.md](docs/safety-model.md) for the full breakdown (tool annotations, read-only mode, explicit confirmation, COA preflight validation).
|
|
346
509
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
"command": "npx",
|
|
351
|
-
"args": ["coalesce-transform-mcp@alpha"]
|
|
352
|
-
}
|
|
353
|
-
}
|
|
354
|
-
```
|
|
510
|
+
- **Tool annotations** - every tool carries MCP `readOnlyHint` / `destructiveHint` / `idempotentHint`. The ⚠️ marker in [Tools](#tools) marks `destructiveHint: true` tools.
|
|
511
|
+
- **`COALESCE_MCP_READ_ONLY=true`** hides all write/mutation tools at server startup. Use it for audits, agent sandboxes, or pairing with a prod profile.
|
|
512
|
+
- **Explicit confirmation** on destructive ops - `delete_*`, `propagate_column_change`, `cancel_run`, `clear_data_cache`, `coa_create`, `coa_run`, `coa_deploy`, `coa_refresh` all require `confirmed: true`.
|
|
355
513
|
|
|
356
|
-
|
|
514
|
+
### More configuration
|
|
357
515
|
|
|
358
|
-
|
|
516
|
+
- [Prerelease channel](docs/prerelease.md) - point `npx` at `@alpha` for preview builds.
|
|
517
|
+
- [Diagnosing setup](docs/diagnosing-setup.md) - the `diagnose_setup` probe and `/coalesce-setup` MCP prompt.
|
|
359
518
|
|
|
360
|
-
|
|
519
|
+
---
|
|
361
520
|
|
|
362
|
-
|
|
521
|
+
## Skills
|
|
363
522
|
|
|
364
|
-
|
|
523
|
+
**Skills are editable markdown that shapes how the agent reasons about your Coalesce project.** Ship your team's naming conventions, grain definitions, and layering patterns as context - every agent on the server instantly picks them up. No fine-tuning, no prompt engineering, just markdown you edit and commit.
|
|
365
524
|
|
|
366
|
-
|
|
525
|
+
Set `COALESCE_MCP_SKILLS_DIR` to make skills editable on disk. Each skill resolves to default content, user-augmented content, or a full user override - see [docs/context-skills.md](docs/context-skills.md) for the resolution order and customization walkthrough.
|
|
367
526
|
|
|
368
|
-
|
|
527
|
+
**24 skills, grouped into 6 families:**
|
|
369
528
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
529
|
+
| | Family | Skills | Covers |
|
|
530
|
+
| --- | ------ | :----: | ------ |
|
|
531
|
+
| <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/book-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/book-light.png"><img src="docs/icons/book-light.png" width="20" height="20" alt="book"></picture> | **Foundations** | 7 | Core concepts, tool usage, ID discovery, storage mappings, ecosystem scope |
|
|
532
|
+
| <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/file-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/file-light.png"><img src="docs/icons/file-light.png" width="20" height="20" alt="file"></picture> | **SQL platform rules** | 3 | Per-warehouse conventions for node SQL (Snowflake, Databricks, BigQuery) |
|
|
533
|
+
| <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/git-commit-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/git-commit-light.png"><img src="docs/icons/git-commit-light.png" width="20" height="20" alt="git-commit"></picture> | **Node editing & payloads** | 6 | Decision tree, payload shape, hydrated metadata, joins, config completion |
|
|
534
|
+
| <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/repo-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/repo-light.png"><img src="docs/icons/repo-light.png" width="20" height="20" alt="repo"></picture> | **Node type selection** | 2 | When to use Stage/Work vs Dimension/Fact vs specialized node types |
|
|
535
|
+
| <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/workflow-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/workflow-light.png"><img src="docs/icons/workflow-light.png" width="20" height="20" alt="workflow"></picture> | **Pipeline workflows** | 4 | End-to-end pipeline building, intent, review, and workshop patterns |
|
|
536
|
+
| <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/beaker-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/beaker-light.png"><img src="docs/icons/beaker-light.png" width="20" height="20" alt="beaker"></picture> | **Run operations** | 2 | Starting, retrying, polling, diagnosing, and canceling runs |
|
|
374
537
|
|
|
375
|
-
|
|
376
|
-
{
|
|
377
|
-
"cortex": {
|
|
378
|
-
"command": "cortex",
|
|
379
|
-
"args": ["--mcp-server"]
|
|
380
|
-
}
|
|
381
|
-
}
|
|
382
|
-
```
|
|
538
|
+
<details>
|
|
383
539
|
|
|
384
|
-
|
|
540
|
+
<summary>
|
|
541
|
+
<picture>
|
|
542
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/icons/book-dark.png">
|
|
543
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/icons/book-light.png">
|
|
544
|
+
<img src="docs/icons/book-light.png" width="20" height="20" alt="book">
|
|
545
|
+
</picture>
|
|
546
|
+
<b>Foundations</b> — the shared context every agent starts with
|
|
547
|
+
</summary>
|
|
548
|
+
|
|
549
|
+
- **`overview`** - General Coalesce concepts, response guidelines, and operational constraints
|
|
550
|
+
- **`tool-usage`** - Best practices for tool batching, parallelization, and SQL conversion
|
|
551
|
+
- **`id-discovery`** - Resolving project, workspace, environment, job, run, node, and org IDs
|
|
552
|
+
- **`storage-mappings`** - Storage location concepts, `{{ ref() }}` syntax, and reference patterns
|
|
553
|
+
- **`ecosystem-boundaries`** - Scope of this MCP vs adjacent data-engineering MCPs (Snowflake, Fivetran, dbt, Catalog)
|
|
554
|
+
- **`data-engineering-principles`** - Node type selection, layered architecture, methodology detection, materialization strategies
|
|
555
|
+
- **`sql-platform-selection`** - Determining the active SQL platform from project metadata
|
|
385
556
|
|
|
386
|
-
|
|
557
|
+
</details>
|
|
387
558
|
|
|
388
|
-
|
|
559
|
+
<details>
|
|
389
560
|
|
|
390
|
-
|
|
561
|
+
<summary>
|
|
562
|
+
<picture>
|
|
563
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/icons/file-dark.png">
|
|
564
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/icons/file-light.png">
|
|
565
|
+
<img src="docs/icons/file-light.png" width="20" height="20" alt="file">
|
|
566
|
+
</picture>
|
|
567
|
+
<b>SQL platform rules</b> — per-warehouse conventions for node SQL
|
|
568
|
+
</summary>
|
|
391
569
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
570
|
+
- **`sql-snowflake`** - Snowflake-specific SQL conventions for node SQL
|
|
571
|
+
- **`sql-databricks`** - Databricks-specific SQL conventions for node SQL
|
|
572
|
+
- **`sql-bigquery`** - BigQuery-specific SQL conventions for node SQL
|
|
573
|
+
|
|
574
|
+
</details>
|
|
575
|
+
|
|
576
|
+
<details>
|
|
395
577
|
|
|
396
|
-
|
|
578
|
+
<summary>
|
|
579
|
+
<picture>
|
|
580
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/icons/git-commit-dark.png">
|
|
581
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/icons/git-commit-light.png">
|
|
582
|
+
<img src="docs/icons/git-commit-light.png" width="20" height="20" alt="git-commit">
|
|
583
|
+
</picture>
|
|
584
|
+
<b>Node editing & payloads</b> — how the agent reasons about node bodies
|
|
585
|
+
</summary>
|
|
586
|
+
|
|
587
|
+
- **`node-creation-decision-tree`** - Choosing between predecessor-based creation, updates, and full replacements
|
|
588
|
+
- **`node-payloads`** - Working with workspace node bodies, metadata, config, and array-replacement risks
|
|
589
|
+
- **`hydrated-metadata`** - Coalesce hydrated metadata structures for advanced node payload editing
|
|
590
|
+
- **`intelligent-node-configuration`** - How intelligent config completion works, schema resolution, automatic field detection
|
|
591
|
+
- **`node-operations`** - Editing existing nodes: joins, columns, config fields, and SQL-to-graph conversion
|
|
592
|
+
- **`aggregation-patterns`** - JOIN ON generation, GROUP BY detection, and join-to-aggregation conversion
|
|
397
593
|
|
|
398
|
-
|
|
399
|
-
- `user_skills.<name>.md` — your customization file (starts as an inactive stub with instructions)
|
|
594
|
+
</details>
|
|
400
595
|
|
|
401
|
-
|
|
596
|
+
<details>
|
|
402
597
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
598
|
+
<summary>
|
|
599
|
+
<picture>
|
|
600
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/icons/repo-dark.png">
|
|
601
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/icons/repo-light.png">
|
|
602
|
+
<img src="docs/icons/repo-light.png" width="20" height="20" alt="repo">
|
|
603
|
+
</picture>
|
|
604
|
+
<b>Node type selection</b> — picking the right node type for each step
|
|
605
|
+
</summary>
|
|
407
606
|
|
|
408
|
-
|
|
607
|
+
- **`node-type-selection-guide`** - When to use each Coalesce node type (Stage/Work vs Dimension/Fact vs specialized)
|
|
608
|
+
- **`node-type-corpus`** - Node type discovery, corpus search, and metadata patterns
|
|
609
|
+
|
|
610
|
+
</details>
|
|
409
611
|
|
|
410
612
|
<details>
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
| Node Payloads | `node-payloads` | Working with workspace node bodies, metadata, config, and array-replacement risks |
|
|
426
|
-
| Hydrated Metadata | `hydrated-metadata` | Coalesce hydrated metadata structures for advanced node payload editing |
|
|
427
|
-
| Run Operations | `run-operations` | Starting, retrying, polling, diagnosing, and canceling Coalesce runs |
|
|
428
|
-
| Node Type Corpus | `node-type-corpus` | Node type discovery, corpus search, and metadata patterns |
|
|
429
|
-
| Aggregation Patterns | `aggregation-patterns` | JOIN ON generation, GROUP BY detection, and join-to-aggregation conversion |
|
|
430
|
-
| Intelligent Node Configuration | `intelligent-node-configuration` | How intelligent config completion works, schema resolution, and automatic field detection |
|
|
431
|
-
| Pipeline Workflows | `pipeline-workflows` | Building pipelines end-to-end: node type selection, multi-node sequences, and execution |
|
|
432
|
-
| Node Operations | `node-operations` | Editing existing nodes: joins, columns, config fields, and SQL-to-graph conversion |
|
|
433
|
-
| Node Type Selection Guide | `node-type-selection-guide` | When to use each Coalesce node type (Stage/Work vs Dimension/Fact vs specialized) |
|
|
434
|
-
| Intent Pipeline Guide | `intent-pipeline-guide` | Using `build_pipeline_from_intent` to create pipelines from natural language |
|
|
435
|
-
| Run Diagnostics Guide | `run-diagnostics-guide` | Using `diagnose_run_failure` to analyze failed runs and determine fixes |
|
|
436
|
-
| Pipeline Review Guide | `pipeline-review-guide` | Using `review_pipeline` for pipeline analysis and optimization |
|
|
437
|
-
| Pipeline Workshop Guide | `pipeline-workshop-guide` | Using pipeline workshop tools for iterative, conversational pipeline building |
|
|
438
|
-
| Ecosystem Boundaries | `ecosystem-boundaries` | Scope of this MCP vs adjacent data engineering MCPs (Snowflake, Fivetran, dbt, Catalog) |
|
|
613
|
+
|
|
614
|
+
<summary>
|
|
615
|
+
<picture>
|
|
616
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/icons/workflow-dark.png">
|
|
617
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/icons/workflow-light.png">
|
|
618
|
+
<img src="docs/icons/workflow-light.png" width="20" height="20" alt="workflow">
|
|
619
|
+
</picture>
|
|
620
|
+
<b>Pipeline workflows</b> — end-to-end pipeline building
|
|
621
|
+
</summary>
|
|
622
|
+
|
|
623
|
+
- **`pipeline-workflows`** - Building pipelines end-to-end: node type selection, multi-node sequences, execution
|
|
624
|
+
- **`intent-pipeline-guide`** - Using `build_pipeline_from_intent` to create pipelines from natural language
|
|
625
|
+
- **`pipeline-review-guide`** - Using `review_pipeline` for pipeline analysis and optimization
|
|
626
|
+
- **`pipeline-workshop-guide`** - Using pipeline workshop tools for iterative, conversational pipeline building
|
|
439
627
|
|
|
440
628
|
</details>
|
|
441
629
|
|
|
442
|
-
|
|
630
|
+
<details>
|
|
631
|
+
|
|
632
|
+
<summary>
|
|
633
|
+
<picture>
|
|
634
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/icons/beaker-dark.png">
|
|
635
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/icons/beaker-light.png">
|
|
636
|
+
<img src="docs/icons/beaker-light.png" width="20" height="20" alt="beaker">
|
|
637
|
+
</picture>
|
|
638
|
+
<b>Run operations</b> — starting, retrying, diagnosing runs
|
|
639
|
+
</summary>
|
|
443
640
|
|
|
444
|
-
|
|
641
|
+
- **`run-operations`** - Starting, retrying, polling, diagnosing, and canceling Coalesce runs
|
|
642
|
+
- **`run-diagnostics-guide`** - Using `diagnose_run_failure` to analyze failed runs and determine fixes
|
|
445
643
|
|
|
446
|
-
|
|
644
|
+
</details>
|
|
447
645
|
|
|
448
|
-
|
|
646
|
+
> [!TIP]
|
|
647
|
+
> **Companion resources:** 10 topics under `coalesce://coa/describe/*` surface the bundled COA CLI's self-describing documentation, version-pinned to the shipping CLI. Topics: `overview`, `commands`, `selectors`, `schemas`, `workflow`, `structure`, `concepts`, `sql-format`, `node-types`, `config`. Use the `coa_describe` tool for parameterized variants.
|
|
648
|
+
|
|
649
|
+
---
|
|
650
|
+
|
|
651
|
+
## Tools
|
|
449
652
|
|
|
450
653
|
⚠️ = Destructive (requires `confirmed: true`). 🧰 = Runs bundled `coa` CLI.
|
|
451
654
|
|
|
655
|
+
<!-- start of tool reference -->
|
|
656
|
+
|
|
452
657
|
<details>
|
|
453
|
-
<summary><strong>Cloud REST tools (49)</strong> — Coalesce platform resources via the Deploy API</summary>
|
|
454
658
|
|
|
455
|
-
|
|
659
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/project-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/project-light.png"><img src="docs/icons/project-light.png" width="20" height="20" alt="project"></picture> Discovery</summary>
|
|
660
|
+
|
|
661
|
+
**Environments, workspaces, projects**
|
|
456
662
|
|
|
457
|
-
-
|
|
458
|
-
-
|
|
459
|
-
-
|
|
460
|
-
-
|
|
663
|
+
- **`list_environments`** - List all available environments
|
|
664
|
+
- **`get_environment`** - Get details of a specific environment
|
|
665
|
+
- **`list_workspaces`** - List all workspaces
|
|
666
|
+
- **`get_workspace`** - Get details of a specific workspace
|
|
667
|
+
- **`list_projects`** - List all projects
|
|
668
|
+
- **`get_project`** - Get project details
|
|
461
669
|
|
|
462
|
-
|
|
670
|
+
**Nodes**
|
|
463
671
|
|
|
464
|
-
-
|
|
465
|
-
-
|
|
672
|
+
- **`list_environment_nodes`** - List nodes in an environment
|
|
673
|
+
- **`list_workspace_nodes`** - List nodes in a workspace
|
|
674
|
+
- **`get_environment_node`** - Get a specific environment node
|
|
675
|
+
- **`get_workspace_node`** - Get a specific workspace node
|
|
676
|
+
- **`analyze_workspace_patterns`** - Detect package adoption, pipeline layers, methodology, and generate recommendations
|
|
677
|
+
- **`list_workspace_node_types`** - List distinct node types observed in current workspace nodes
|
|
466
678
|
|
|
467
|
-
|
|
679
|
+
**Jobs, subgraphs, runs**
|
|
468
680
|
|
|
469
|
-
-
|
|
470
|
-
-
|
|
471
|
-
-
|
|
472
|
-
-
|
|
473
|
-
-
|
|
474
|
-
-
|
|
475
|
-
-
|
|
681
|
+
- **`list_environment_jobs`** - List all jobs for an environment
|
|
682
|
+
- **`get_environment_job`** - Get details of a specific job
|
|
683
|
+
- **`list_workspace_subgraphs`** - List subgraphs in a workspace
|
|
684
|
+
- **`get_workspace_subgraph`** - Get details of a specific subgraph
|
|
685
|
+
- **`list_runs`** - List runs with optional filters
|
|
686
|
+
- **`get_run`** - Get details of a specific run
|
|
687
|
+
- **`get_run_results`** - Get results of a completed run
|
|
688
|
+
- **`get_run_details`** - Run metadata plus results in one call
|
|
476
689
|
|
|
477
|
-
|
|
690
|
+
**Search**
|
|
478
691
|
|
|
479
|
-
-
|
|
480
|
-
-
|
|
481
|
-
- `get_environment_job` — Get details of a specific job (via environment)
|
|
482
|
-
- `update_workspace_job` — Update a job's name and node selectors
|
|
483
|
-
- `delete_workspace_job` — Delete a job ⚠️
|
|
692
|
+
- **`search_workspace_content`** - Search node SQL, column names, descriptions, and config values
|
|
693
|
+
- **`audit_documentation_coverage`** - Scan all workspace nodes/columns for missing descriptions
|
|
484
694
|
|
|
485
|
-
|
|
695
|
+
</details>
|
|
486
696
|
|
|
487
|
-
|
|
488
|
-
- `get_workspace_subgraph` — Get details of a specific subgraph
|
|
489
|
-
- `create_workspace_subgraph` — Create a subgraph to group nodes visually
|
|
490
|
-
- `update_workspace_subgraph` — Update a subgraph's name and node membership
|
|
491
|
-
- `delete_workspace_subgraph` — Delete a subgraph (nodes are NOT deleted) ⚠️
|
|
697
|
+
<details>
|
|
492
698
|
|
|
493
|
-
|
|
699
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/workflow-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/workflow-light.png"><img src="docs/icons/workflow-light.png" width="20" height="20" alt="workflow"></picture> Pipeline building</summary>
|
|
494
700
|
|
|
495
|
-
|
|
496
|
-
- `list_runs` — List runs with optional filters
|
|
497
|
-
- `get_run` — Get details of a specific run
|
|
498
|
-
- `get_run_results` — Get results of a completed run
|
|
499
|
-
- `start_run` — Start a new run; requires Snowflake auth (Key Pair or PAT, credentials from env vars)
|
|
500
|
-
- `run_status` — Check status of a running job
|
|
501
|
-
- `retry_run` — Retry a failed run; requires Snowflake auth (Key Pair or PAT, credentials from env vars)
|
|
502
|
-
- `cancel_run` — Cancel a running job (requires `runID` and `environmentID`; `orgID` may come from `COALESCE_ORG_ID` or the `orgID` field in your ~/.coa/config profile) ⚠️
|
|
701
|
+
**Plan & build**
|
|
503
702
|
|
|
504
|
-
|
|
703
|
+
- **`plan_pipeline`** - Plan a pipeline from SQL or a natural-language goal without mutating the workspace; ranks best-fit node types from the local repo
|
|
704
|
+
- **`create_pipeline_from_plan`** - Execute an approved pipeline plan using predecessor-based creation
|
|
705
|
+
- **`create_pipeline_from_sql`** - Plan and create a pipeline directly from SQL
|
|
706
|
+
- **`build_pipeline_from_intent`** - Build a pipeline from a natural language goal with automatic entity resolution and node type selection
|
|
707
|
+
- **`review_pipeline`** - Analyze an existing pipeline for redundant nodes, missing joins, layer violations, naming issues, and optimization opportunities
|
|
708
|
+
- **`parse_sql_structure`** - Parse a SQL statement into structural components (CTEs, source tables, projected columns) without touching the workspace
|
|
709
|
+
- **`select_pipeline_node_type`** - Rank and select the best Coalesce node type for a pipeline step
|
|
505
710
|
|
|
506
|
-
|
|
507
|
-
- `get_project` — Get project details
|
|
508
|
-
- `create_project` — Create a new project
|
|
509
|
-
- `update_project` — Update a project
|
|
510
|
-
- `delete_project` — Delete a project ⚠️
|
|
711
|
+
**Workshop (iterative, conversational)**
|
|
511
712
|
|
|
512
|
-
|
|
713
|
+
- **`pipeline_workshop_open`** - Open an iterative pipeline builder session with workspace context pre-loaded
|
|
714
|
+
- **`pipeline_workshop_instruct`** - Send a natural language instruction to modify the current workshop plan
|
|
715
|
+
- **`get_pipeline_workshop_status`** - Get the current state of a workshop session
|
|
716
|
+
- **`pipeline_workshop_close`** - Close a workshop session and release resources
|
|
513
717
|
|
|
514
|
-
|
|
515
|
-
- `get_git_account` — Get git account details
|
|
516
|
-
- `create_git_account` — Create a new git account
|
|
517
|
-
- `update_git_account` — Update a git account
|
|
518
|
-
- `delete_git_account` — Delete a git account ⚠️
|
|
718
|
+
</details>
|
|
519
719
|
|
|
520
|
-
|
|
720
|
+
<details>
|
|
521
721
|
|
|
522
|
-
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
-
|
|
527
|
-
-
|
|
528
|
-
-
|
|
529
|
-
|
|
722
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/git-commit-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/git-commit-light.png"><img src="docs/icons/git-commit-light.png" width="20" height="20" alt="git-commit"></picture> Node editing</summary>
|
|
723
|
+
|
|
724
|
+
**Create**
|
|
725
|
+
|
|
726
|
+
- **`create_workspace_node_from_scratch`** - Create a workspace node with no predecessors
|
|
727
|
+
- **`create_workspace_node_from_predecessor`** - Create a node from predecessor nodes with column coverage verification
|
|
728
|
+
- **`create_node_from_external_schema`** - Create a workspace node whose columns match an existing warehouse table or external schema
|
|
729
|
+
|
|
730
|
+
**Update**
|
|
731
|
+
|
|
732
|
+
- **`set_workspace_node`** - Replace a workspace node with a full body
|
|
733
|
+
- **`update_workspace_node`** - Safely update selected fields of a workspace node
|
|
734
|
+
- **`replace_workspace_node_columns`** - Replace `metadata.columns` wholesale
|
|
735
|
+
- **`delete_workspace_node`** - Delete a node from a workspace ⚠️
|
|
736
|
+
|
|
737
|
+
**Configure**
|
|
738
|
+
|
|
739
|
+
- **`complete_node_configuration`** - Intelligently complete a node's configuration by analyzing context
|
|
740
|
+
- **`apply_join_condition`** - Auto-generate and write a FROM/JOIN/ON clause for a multi-predecessor node
|
|
741
|
+
- **`convert_join_to_aggregation`** - Convert a join-style node into an aggregated fact-style node
|
|
742
|
+
|
|
743
|
+
**Subgraphs & jobs**
|
|
744
|
+
|
|
745
|
+
- **`create_workspace_subgraph`** - Create a subgraph to group nodes visually
|
|
746
|
+
- **`update_workspace_subgraph`** - Update a subgraph's name and node membership
|
|
747
|
+
- **`delete_workspace_subgraph`** - Delete a subgraph (nodes are NOT deleted) ⚠️
|
|
748
|
+
- **`create_workspace_job`** - Create a job in a workspace with node include/exclude selectors
|
|
749
|
+
- **`update_workspace_job`** - Update a job's name and node selectors
|
|
750
|
+
- **`delete_workspace_job`** - Delete a job ⚠️
|
|
530
751
|
|
|
531
752
|
</details>
|
|
532
753
|
|
|
533
754
|
<details>
|
|
534
|
-
<summary><strong>Intelligent tools (46)</strong> — pipeline planning, config completion, join analysis, lineage</summary>
|
|
535
755
|
|
|
536
|
-
|
|
756
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/beaker-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/beaker-light.png"><img src="docs/icons/beaker-light.png" width="20" height="20" alt="beaker"></picture> Runs & execution</summary>
|
|
537
757
|
|
|
538
|
-
-
|
|
539
|
-
-
|
|
540
|
-
-
|
|
541
|
-
-
|
|
542
|
-
-
|
|
543
|
-
-
|
|
544
|
-
-
|
|
545
|
-
-
|
|
546
|
-
-
|
|
758
|
+
- **`start_run`** - Start a new run; requires Snowflake auth
|
|
759
|
+
- **`run_and_wait`** - Start a run and poll until completion
|
|
760
|
+
- **`run_status`** - Check status of a running job
|
|
761
|
+
- **`retry_run`** - Retry a failed run
|
|
762
|
+
- **`retry_and_wait`** - Retry a failed run and poll until completion
|
|
763
|
+
- **`cancel_run`** - Cancel a running job ⚠️
|
|
764
|
+
- **`diagnose_run_failure`** - Classify errors, surface root cause, suggest actionable fixes
|
|
765
|
+
- **`get_environment_overview`** - Environment details with full node list
|
|
766
|
+
- **`get_environment_health`** - Dashboard: node counts, run statuses, failed runs in last 24h, stale nodes, dependency health
|
|
547
767
|
|
|
548
|
-
|
|
768
|
+
</details>
|
|
549
769
|
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
-
|
|
553
|
-
|
|
554
|
-
-
|
|
555
|
-
-
|
|
556
|
-
-
|
|
770
|
+
<details>
|
|
771
|
+
|
|
772
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/git-branch-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/git-branch-light.png"><img src="docs/icons/git-branch-light.png" width="20" height="20" alt="git-branch"></picture> Lineage & impact</summary>
|
|
773
|
+
|
|
774
|
+
- **`get_upstream_nodes`** - Walk the full upstream dependency graph for a node
|
|
775
|
+
- **`get_downstream_nodes`** - Walk the full downstream dependency graph for a node
|
|
776
|
+
- **`get_column_lineage`** - Trace a column through the pipeline upstream and downstream
|
|
777
|
+
- **`analyze_impact`** - Downstream impact of changing a node or specific column - impacted counts, grouped by depth, and critical path
|
|
778
|
+
- **`propagate_column_change`** - Update all downstream columns after a column rename or data type change ⚠️
|
|
779
|
+
|
|
780
|
+
</details>
|
|
557
781
|
|
|
558
|
-
|
|
782
|
+
<details>
|
|
559
783
|
|
|
560
|
-
-
|
|
561
|
-
- `pipeline_workshop_instruct` — Send a natural language instruction to modify the current workshop plan
|
|
562
|
-
- `get_pipeline_workshop_status` — Get the current state of a workshop session
|
|
563
|
-
- `pipeline_workshop_close` — Close a workshop session and release resources
|
|
784
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/repo-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/repo-light.png"><img src="docs/icons/repo-light.png" width="20" height="20" alt="repo"></picture> Repo-backed node types</summary>
|
|
564
785
|
|
|
565
|
-
|
|
786
|
+
- **`list_repo_packages`** - List package aliases and enabled node-type coverage from a committed Coalesce repo
|
|
787
|
+
- **`list_repo_node_types`** - List exact resolvable committed node-type identifiers from `nodeTypes/`
|
|
788
|
+
- **`get_repo_node_type_definition`** - Resolve one node type and return its outer definition plus parsed `nodeMetadataSpec`
|
|
789
|
+
- **`generate_set_workspace_node_template`** - Generate a YAML-friendly `set_workspace_node` body template
|
|
790
|
+
- **`search_node_type_variants`** - Search the committed node-type corpus by normalized family, package, primitive, or support status
|
|
791
|
+
- **`get_node_type_variant`** - Load one exact node-type corpus variant by variant key
|
|
792
|
+
- **`generate_set_workspace_node_template_from_variant`** - Generate a template from a committed corpus variant
|
|
566
793
|
|
|
567
|
-
|
|
568
|
-
- `list_repo_node_types` — List exact resolvable committed node-type identifiers from `nodeTypes/`
|
|
569
|
-
- `get_repo_node_type_definition` — Resolve one exact committed node type and return its outer definition plus parsed `nodeMetadataSpec`
|
|
570
|
-
- `generate_set_workspace_node_template` — Generate a YAML-friendly `set_workspace_node` body template from a definition object or committed repo definition
|
|
571
|
-
- `search_node_type_variants` — Search the committed node-type corpus by normalized family, package, primitive, or support status
|
|
572
|
-
- `get_node_type_variant` — Load one exact node-type corpus variant by variant key
|
|
573
|
-
- `generate_set_workspace_node_template_from_variant` — Generate a `set_workspace_node` body template from a committed corpus variant
|
|
794
|
+
</details>
|
|
574
795
|
|
|
575
|
-
|
|
796
|
+
<details>
|
|
576
797
|
|
|
577
|
-
-
|
|
578
|
-
- `get_downstream_nodes` — Walk the full downstream dependency graph for a node
|
|
579
|
-
- `get_column_lineage` — Trace a column through the pipeline upstream and downstream via column-level references
|
|
580
|
-
- `analyze_impact` — Analyze downstream impact of changing a node or specific column — returns impacted counts, grouped by depth, and critical path
|
|
581
|
-
- `propagate_column_change` — Update all downstream columns after a column rename or data type change ⚠️
|
|
582
|
-
- `search_workspace_content` — Search across node SQL, column names, descriptions, and config values using the lineage cache as a searchable index
|
|
583
|
-
- `audit_documentation_coverage` — Scan all workspace nodes and columns for missing descriptions and report coverage statistics
|
|
798
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/tools-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/tools-light.png"><img src="docs/icons/tools-light.png" width="20" height="20" alt="tools"></picture> COA CLI</summary>
|
|
584
799
|
|
|
585
|
-
|
|
800
|
+
All local tools accept a `projectPath` argument and validate that it contains `data.yml` before shelling out. Destructive tools run preflight validation; see [Safety model](docs/safety-model.md).
|
|
586
801
|
|
|
587
|
-
-
|
|
588
|
-
- `cache_environment_nodes` — Fetch every page of environment nodes, write a full snapshot, and return cache metadata
|
|
589
|
-
- `cache_runs` — Fetch every page of run results, write a full snapshot, and return cache metadata
|
|
590
|
-
- `cache_org_users` — Fetch every page of organization users, write a full snapshot, and return cache metadata
|
|
591
|
-
- `clear_data_cache` — Delete all cached snapshots, auto-cached responses, and plan summaries ⚠️
|
|
802
|
+
**Read-only, local**
|
|
592
803
|
|
|
593
|
-
|
|
804
|
+
- 🧰 **`coa_doctor`** - Check config, credentials, and warehouse connectivity
|
|
805
|
+
- 🧰 **`coa_validate`** - Validate YAML schemas and scan for configuration problems
|
|
806
|
+
- 🧰 **`coa_list_project_nodes`** - List all nodes defined in a local project (pre-deploy)
|
|
807
|
+
- 🧰 **`coa_dry_run_create`** - Preview DDL without executing (does **not** validate columns/types exist in warehouse)
|
|
808
|
+
- 🧰 **`coa_dry_run_run`** - Preview DML without executing (same caveat)
|
|
594
809
|
|
|
595
|
-
-
|
|
596
|
-
- `retry_and_wait` — Retry a failed run and poll until completion; requires Snowflake auth (Key Pair or PAT)
|
|
597
|
-
- `get_run_details` — Get run metadata and results in one call
|
|
598
|
-
- `get_environment_overview` — Get environment details with full node list
|
|
599
|
-
- `get_environment_health` — Comprehensive health dashboard: node counts by type, run statuses, failed runs in last 24h, stale nodes, dependency health, and overall health score (walks all paginated environment runs before scoring — slower on busy environments)
|
|
810
|
+
**Read-only, cloud**
|
|
600
811
|
|
|
601
|
-
|
|
812
|
+
- 🧰 **`coa_list_environments`** - List deployment environments
|
|
813
|
+
- 🧰 **`coa_list_environment_nodes`** - List deployed nodes in an environment
|
|
814
|
+
- 🧰 **`coa_list_runs`** - List pipeline runs in a cloud environment
|
|
602
815
|
|
|
603
|
-
|
|
816
|
+
**Describe**
|
|
604
817
|
|
|
605
|
-
|
|
818
|
+
- 🧰 **`coa_describe`** - Fetch a section of COA's self-describing documentation by topic + optional subtopic
|
|
606
819
|
|
|
607
|
-
|
|
820
|
+
**Write & deploy**
|
|
821
|
+
|
|
822
|
+
- 🧰 **`coa_plan`** - Generate a deployment plan JSON by diffing local project against a cloud environment (non-destructive)
|
|
823
|
+
- 🧰 **`coa_create`** - Run DDL (CREATE/REPLACE) against the warehouse for selected nodes ⚠️
|
|
824
|
+
- 🧰 **`coa_run`** - Run DML (INSERT/MERGE) to populate selected nodes ⚠️
|
|
825
|
+
- 🧰 **`coa_deploy`** - Apply a plan JSON to a cloud environment ⚠️
|
|
826
|
+
- 🧰 **`coa_refresh`** - Run DML for selected nodes in an already-deployed environment (no local project required) ⚠️
|
|
827
|
+
|
|
828
|
+
</details>
|
|
829
|
+
|
|
830
|
+
<details>
|
|
831
|
+
|
|
832
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/file-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/file-light.png"><img src="docs/icons/file-light.png" width="20" height="20" alt="file"></picture> Projects, environments & git accounts</summary>
|
|
833
|
+
|
|
834
|
+
- **`create_environment`** - Create a new environment within a project
|
|
835
|
+
- **`delete_environment`** - Delete an environment ⚠️
|
|
836
|
+
- **`create_project`** - Create a new project
|
|
837
|
+
- **`update_project`** - Update a project
|
|
838
|
+
- **`delete_project`** - Delete a project ⚠️
|
|
839
|
+
- **`list_git_accounts`** - List all git accounts
|
|
840
|
+
- **`get_git_account`** - Get git account details
|
|
841
|
+
- **`create_git_account`** - Create a new git account
|
|
842
|
+
- **`update_git_account`** - Update a git account
|
|
843
|
+
- **`delete_git_account`** - Delete a git account ⚠️
|
|
608
844
|
|
|
609
845
|
</details>
|
|
610
846
|
|
|
611
847
|
<details>
|
|
612
|
-
<summary><strong>COA CLI tools (14)</strong> — bundled <code>@coalescesoftware/coa</code> CLI</summary>
|
|
613
848
|
|
|
614
|
-
|
|
849
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/shield-lock-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/shield-lock-light.png"><img src="docs/icons/shield-lock-light.png" width="20" height="20" alt="shield-lock"></picture> Users & roles</summary>
|
|
615
850
|
|
|
616
|
-
|
|
851
|
+
- **`list_org_users`** - List all organization users
|
|
852
|
+
- **`get_user_roles`** - Get roles for a specific user
|
|
853
|
+
- **`list_user_roles`** - List all user roles
|
|
854
|
+
- **`set_org_role`** - Set organization role for a user
|
|
855
|
+
- **`set_project_role`** - Set project role for a user
|
|
856
|
+
- **`delete_project_role`** - Remove project role from a user ⚠️
|
|
857
|
+
- **`set_env_role`** - Set environment role for a user
|
|
858
|
+
- **`delete_env_role`** - Remove environment role from a user ⚠️
|
|
617
859
|
|
|
618
|
-
|
|
619
|
-
- 🧰 `coa_validate` — Validate YAML schemas and scan a project for configuration problems. Wraps `coa validate --json`
|
|
620
|
-
- 🧰 `coa_list_project_nodes` — List all nodes defined in a local project (pre-deploy). Wraps `coa create --list-nodes`
|
|
621
|
-
- 🧰 `coa_dry_run_create` — Preview DDL without executing against the warehouse. Forces `--dry-run --verbose`. Does **not** validate that referenced columns/types exist in the warehouse — catches SQL generation bugs, not schema-drift bugs
|
|
622
|
-
- 🧰 `coa_dry_run_run` — Preview DML without executing against the warehouse. Forces `--dry-run --verbose`. Same caveat as `coa_dry_run_create`: SQL that looks valid here can still fail at run-time on missing columns
|
|
860
|
+
</details>
|
|
623
861
|
|
|
624
|
-
|
|
862
|
+
<details>
|
|
625
863
|
|
|
626
|
-
-
|
|
627
|
-
- 🧰 `coa_list_environment_nodes` — List deployed nodes in an environment. Wraps `coa nodes list --environmentID ...`
|
|
628
|
-
- 🧰 `coa_list_runs` — List pipeline runs in a cloud environment (or across all environments). Wraps `coa runs list`
|
|
864
|
+
<summary><picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/book-dark.png"><source media="(prefers-color-scheme: light)" srcset="docs/icons/book-light.png"><img src="docs/icons/book-light.png" width="20" height="20" alt="book"></picture> Cache, skills & setup</summary>
|
|
629
865
|
|
|
630
|
-
|
|
866
|
+
**Cache snapshots**
|
|
631
867
|
|
|
632
|
-
-
|
|
868
|
+
- **`cache_workspace_nodes`** - Fetch every page of workspace nodes, write a full snapshot, and return cache metadata
|
|
869
|
+
- **`cache_environment_nodes`** - Fetch every page of environment nodes, write a full snapshot
|
|
870
|
+
- **`cache_runs`** - Fetch every page of run results, write a full snapshot
|
|
871
|
+
- **`cache_org_users`** - Fetch every page of organization users, write a full snapshot
|
|
872
|
+
- **`clear_data_cache`** - Delete all cached snapshots, auto-cached responses, and plan summaries ⚠️
|
|
633
873
|
|
|
634
|
-
|
|
874
|
+
**Skills & setup**
|
|
635
875
|
|
|
636
|
-
-
|
|
637
|
-
-
|
|
638
|
-
- 🧰 `coa_run` — Run DML (INSERT/MERGE) to populate selected nodes. Preflight-gated. ⚠️
|
|
639
|
-
- 🧰 `coa_deploy` — Apply a plan JSON to a cloud environment. Verifies the plan file exists before running. ⚠️
|
|
640
|
-
- 🧰 `coa_refresh` — Run DML for selected nodes in an already-deployed environment (no local project required). ⚠️
|
|
876
|
+
- **`personalize_skills`** - Export bundled skill files to a local directory for customization
|
|
877
|
+
- **`diagnose_setup`** - Stateless probe reporting configured setup pieces; pairs with the `/coalesce-setup` MCP prompt
|
|
641
878
|
|
|
642
879
|
</details>
|
|
643
880
|
|
|
881
|
+
<!-- end of tool reference -->
|
|
882
|
+
|
|
883
|
+
---
|
|
884
|
+
|
|
644
885
|
## Design notes
|
|
645
886
|
|
|
646
887
|
- **SQL override is disallowed.** Nodes are built via YAML/config (columns, transforms, join conditions), not raw SQL. Template generation strips `overrideSQLToggle`, and write helpers reject `overrideSQL` fields.
|
|
647
888
|
- **Caching.** Large responses are auto-cached to disk. Use `cache_workspace_nodes` and siblings when you want a reusable snapshot. Configure the threshold with `COALESCE_MCP_AUTO_CACHE_MAX_BYTES`.
|
|
648
889
|
- **Repo-backed tools.** Set `COALESCE_REPO_PATH` (or add `repoPath=` to your ~/.coa/config profile) to your local Coalesce repo root (containing `nodeTypes/`, `nodes/`, `packages/`), or pass `repoPath` on individual tool calls. The server does not clone repos or install packages.
|
|
649
|
-
- **COA CLI versioning.** The bundled COA CLI is pinned to an exact alpha version
|
|
650
|
-
- **COA describe cache.** COA describe output is cached under `~/.cache/coalesce-transform-mcp/coa-describe/<coa-version>/` after first access. Cache is version-keyed
|
|
890
|
+
- **COA CLI versioning.** The bundled COA CLI is pinned to an exact alpha version - *not* a floating `@next` tag. Every release of this MCP ships with a known-good COA build.
|
|
891
|
+
- **COA describe cache.** COA describe output is cached under `~/.cache/coalesce-transform-mcp/coa-describe/<coa-version>/` after first access. Cache is version-keyed - upgrading the MCP automatically invalidates stale content.
|
|
892
|
+
|
|
893
|
+
---
|
|
651
894
|
|
|
652
895
|
## Links
|
|
653
896
|
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
897
|
+
| | Resource | |
|
|
898
|
+
| :-: | :-- | :-- |
|
|
899
|
+
| 📘 | [Coalesce Docs](https://docs.coalesce.io/docs) | Product documentation |
|
|
900
|
+
| 🔌 | [Coalesce API Docs](https://docs.coalesce.io/docs/api/authentication) | REST API reference |
|
|
901
|
+
| 🧰 | [Coalesce CLI (`coa`)](https://docs.coalesce.io/docs/cli) | Bundled CLI docs |
|
|
902
|
+
| 🛒 | [Coalesce Marketplace](https://docs.coalesce.io/docs/marketplace) | Node type packages |
|
|
903
|
+
| 🔗 | [Model Context Protocol](https://modelcontextprotocol.io/) | MCP spec & ecosystem |
|
|
904
|
+
|
|
905
|
+
---
|
|
906
|
+
|
|
907
|
+
## Contributing
|
|
908
|
+
|
|
909
|
+
Issues and PRs welcome.
|
|
910
|
+
|
|
911
|
+
- 🐛 **Bug reports** - [open an issue](https://github.com/coalesceio/coalesce-transform-mcp/issues/new?labels=bug)
|
|
912
|
+
- 💡 **Feature requests** - [start a discussion](https://github.com/coalesceio/coalesce-transform-mcp/discussions)
|
|
659
913
|
|
|
660
914
|
## License
|
|
661
915
|
|
|
662
|
-
MIT
|
|
916
|
+
[MIT](LICENSE) © Coalesce - built on top of the open [Model Context Protocol](https://modelcontextprotocol.io/).
|