Coalesce Transform MCP

聚结变换mcp

](https://www.npmjs.com/package/coalesce-transform-mcp)    

MCP服务器 合并.专为 雪花 Cortex代码 （CoCo） -为所有其他MCP客户端（Claude Code、Claude Desktop、Cursor、VS Code、Windsurf）提供一流的支持。管理节点、管道、环境、作业和运行，并从同一服务器驱动本地第一个Coalesce CLI：验证项目、预览DDL/DML、规划部署并将其应用于云环境。

______________________________________________________________________

我想…

||任务|跳转到| | :-: | ---- | ------- | | 🚀 | 2分钟后开始跑步| 快速开始 | | 🎛️ | 自定义代理行为| 技能 | | 🔍 | 查找特定工具| 工具 | | 📦 | 浏览完整设置| 完整安装 | | 🔑 | 身份验证（env var或 ~/.coa/config) | 凭证 | | 🌐 | 在多个Coalesce环境中运行| 多个环境 | | 📥 | 仓库表中的脚手架源节点| 工具→ 仓库源发现 | | 🔒 | 将触针锁定为只读| 安全模型 |

______________________________________________________________________

快速开始

下面的每个链接都会打开一个简短的安装指南，其中包含一个点击安装按钮（在支持的情况下）和手动配置。

\[！提示\] ❄️ 雪花皮编码+聚结变换mcp。 CoCo是Snowflake的AI编码CLI——它已经知道你的仓库、角色和数据。将此MCP放入，代理可以在单个会话中规划管道、创建节点、运行DML和验证结果，所有这些都在Snowflake的身份验证模型下进行。 在Cortex代码中安装→

❄️ Install in Snowflake Cortex Code (CoCo)

为什么是这种配对？ Cortex Code是Snowflake的AI编码CLI，它已经对您的仓库进行了身份验证，在Snowflake角色下运行，并具有查询实时数据的原生工具。添加 coalesce-transform-mcp 单个代理会话可以规划管道、创建节点、运行DML，并在不离开终端的情况下根据实际行验证结果。

一个衬垫（之后 安装Cortex代码命令行界面):

cortex mcp add coalesce-transform npx coalesce-transform-mcp

或编辑 ~/.snowflake/cortex/mcp.json 直接：

{
  "mcpServers": {
    "coalesce-transform": {
      "type": "stdio",
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": {
        "COALESCE_ACCESS_TOKEN": ""
      }
    }
  }
}

放下 env 如果你正在使用，请屏蔽 ~/.coa/config -Cortex Code和Coalesce都可以从同一配置文件中提取令牌。完整演练： docs/安装指南/cortex-code.md.

Install in Cursor

单击安装： 

手动：粘贴到 .cursor/mcp.json 在项目根目录中（或 ~/.cursor/mcp.json 全球）：

{
  "mcpServers": {
    "coalesce-transform": {
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": {
        "COALESCE_ACCESS_TOKEN": ""
      }
    }
  }
}

光标会 不 扩展 ${VAR} -粘贴文字标记，或删除 env 阻止和使用 ~/.coa/config （参见 凭证).

Install in VS Code

单击安装： 

手册：遵循 VS Code MCP安装指南 并使用此配置：

{
  "name": "coalesce-transform",
  "command": "npx",
  "args": ["coalesce-transform-mcp"]
}

添加 COALESCE_ACCESS_TOKEN 通过VS Code的秘密输入提示，或删除令牌并使用 ~/.coa/config.安装后重新加载VS Code窗口。

Install in VS Code Insiders

单击安装： 

手动：与马厩相同 VS代码安装 -内部人员读取相同的MCP配置。

Install in Claude Code (CLI)

一个衬垫：

claude mcp add coalesce-transform -- npx coalesce-transform-mcp

如果需要，请内联传递env变量：

claude mcp add coalesce-transform \
  --env COALESCE_ACCESS_TOKEN=$COALESCE_ACCESS_TOKEN \
  -- npx coalesce-transform-mcp

手动：粘贴到 .mcp.json 在项目根目录中（或 ~/.claude.json 全球）：

{
  "mcpServers": {
    "coalesce-transform": {
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": {
        "COALESCE_ACCESS_TOKEN": "${COALESCE_ACCESS_TOKEN}"
      }
    }
  }
}

克劳德代码 做 扩展 ${VAR} 加载时从shell环境中- .mcp.json 可以使用变量引用安全地提交到git。省略 env 如果使用，请阻止 ~/.coa/config.

Install in Claude Desktop

还没有深度链接-手动粘贴。

文件： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。

{
  "mcpServers": {
    "coalesce-transform": {
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": {
        "COALESCE_ACCESS_TOKEN": ""
      }
    }
  }
}

克劳德桌面 不 扩展 ${VAR} -粘贴文字标记，或删除 env 阻止和使用 ~/.coa/config.完全退出克劳德桌面(Cmd+Q)编辑后重新启动。

Install in Windsurf

还没有深度链接-手动粘贴。

文件： ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "coalesce-transform": {
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": {
        "COALESCE_ACCESS_TOKEN": ""
      }
    }
  }
}

风帆冲浪 不 扩展 ${VAR} -粘贴文字标记，或删除 env 阻止和使用 ~/.coa/config。编辑后重新启动Windsurf。

\[！提示\] ### 🚀 刚刚安装？ 只需说“帮我设置”，或者逃跑 /coalesce-setup。您的代理将检查您的凭据和项目设置，然后引导您解决缺少的问题。

______________________________________________________________________

技能

技能是可编辑的标记，它决定了代理如何对您的Coalesce项目进行推理。 将团队的命名约定、粒度定义和分层模式作为上下文发送——服务器上的每个代理都会立即获取它们。无需微调，无需即时工程，只需标记您的编辑和提交。

集 COALESCE_MCP_SKILLS_DIR 使技能在磁盘上可编辑。每种技能都可以解析为默认内容、用户增强内容或完全用户覆盖-请参阅 docs/context-skills.md 了解分辨率顺序和自定义演练。

25种技能，分为6个家族：

Foundations — the shared context every agent starts with

• overview -一般联合概念、响应指南和操作限制
• tool-usage -工具批处理、并行化和SQL转换的最佳实践
• id-discovery -解析项目、工作区、环境、作业、运行、节点和组织ID
• storage-mappings -存储位置概念， {{ ref() }} 语法和引用模式
• ecosystem-boundaries -本MCP与相邻数据工程MCP（雪花、菲维特兰、dbt、目录）的范围
• data-engineering-principles -节点类型选择、分层架构、方法检测、物化策略
• sql-platform-selection -从项目元数据确定活动SQL平台
• setup-guide -首次MCP设置流程由以下驱动 diagnose_setup （与 /coalesce-setup 提示）

SQL platform rules — per-warehouse conventions for node SQL

• sql-snowflake -节点SQL的雪花特定SQL约定
• sql-databricks -用于节点SQL的特定于docker的SQL约定
• sql-bigquery -节点SQL的BigQuery特定SQL约定

Node editing & payloads — how the agent reasons about node bodies

• node-creation-decision-tree -在基于前身的创建、更新和完全替换之间进行选择
• node-payloads -处理工作区节点体、元数据、配置和数组替换风险
• hydrated-metadata -整合水合元数据结构，用于高级节点有效载荷编辑
• intelligent-node-configuration -智能配置完成的工作原理、模式解析、自动字段检测
• node-operations -编辑现有节点：联接、列、配置字段和SQL到图形转换
• aggregation-patterns -JOIN ON生成、GROUP BY检测和JOIN到聚合转换

Node type selection — picking the right node type for each step

• node-type-selection-guide -何时使用每种聚合节点类型（阶段/工作vs维度/事实vs专业）
• node-type-corpus -节点类型发现、语料库搜索和元数据模式

Pipeline workflows — end-to-end pipeline building

• pipeline-workflows -端到端构建管道：节点类型选择、多节点序列、执行
• intent-pipeline-guide -使用 build_pipeline_from_intent 从自然语言创建管道
• pipeline-review-guide -使用 review_pipeline 用于管道分析和优化
• pipeline-workshop-guide -使用管道研讨会工具进行迭代式、对话式的管道构建

Run operations — starting, retrying, diagnosing runs

• run-operations -启动、重试、轮询、诊断和取消聚合运行
• run-diagnostics-guide -使用 diagnose_run_failure 分析失败的运行并确定修复方法

______________________________________________________________________

工具

\[！注意\] ### 传说 - ⚠️ 破坏性的 -工具需要 confirmed: true 在它运行之前。 - 🧰 捆绑的 coa 命令行界面 -在项目目录上本地运行。该工具需要一个 projectPath 指向包含以下内容的文件夹 data.yml. - 飞行前验证 -破坏性的🧰 工具在脱壳前会进行安全检查。看 安全模型.

Discovery — list, get, and search across workspaces, nodes, jobs, and runs

环境、工作空间、项目

• list_environments -列出所有可用环境
• get_environment -获取特定环境的详细信息
• list_workspaces -列出所有工作区
• get_workspace -获取特定工作空间的详细信息
• list_projects -列出所有项目
• get_project -获取项目详细信息

节点

• list_environment_nodes -列出环境中的节点
• list_workspace_nodes -列出工作区中的节点
• get_environment_node -获取特定环境节点
• get_workspace_node -获取特定的工作区节点
• analyze_workspace_patterns -检测软件包采用情况、管道层、方法，并生成建议
• list_workspace_node_types -列出当前工作区节点中观察到的不同节点类型

作业、子图、运行

• list_environment_jobs -列出某个环境的所有作业
• find_jobs_by_name -按名称模糊匹配环境作业，并返回每个匹配项及其最近的运行情况
• get_job_run_details_by_name -按名称模糊匹配一个环境作业，并返回其最新运行详细信息+结果
• get_environment_job -获取特定工作的详细信息
• list_job_nodes -将工作区作业的选择器解析为按子图分组的具体节点
• get_workspace_subgraph -通过UUID获取特定子图的详细信息（公共API没有子图列表端点-通过repo的 subgraphs/ 文件夹或创建时填充的本地缓存）
• list_runs -使用可选筛选器运行列表
• get_run -获取特定跑步的详细信息
• get_run_results -获取已完成运行的结果
• get_run_details -在一次调用中运行元数据和结果

搜索

• search_workspace_content -搜索节点SQL、列名、描述和配置值
• audit_documentation_coverage -扫描所有工作区节点/列以查找缺少的描述

本地项目和云CLI

• 🧰 coa_list_project_nodes -列出本地项目中定义的所有节点（预部署）

Pipeline building — plan, create, and iterate on multi-node pipelines

规划和建造

• plan_pipeline -在不改变工作空间的情况下，从SQL或自然语言目标规划管道；从本地仓库中对最合适的节点类型进行排名
• create_pipeline_from_plan -使用基于前置程序的创建执行批准的管道计划
• create_pipeline_from_sql -直接从SQL规划和创建管道
• build_pipeline_from_intent -从具有自动实体解析和节点类型选择的自然语言目标构建管道
• review_pipeline -分析现有管道中的冗余节点、缺失连接、层违规、命名问题和优化机会
• parse_sql_structure -将SQL语句解析为结构组件（CTE、源表、投影列），而无需接触工作区
• select_pipeline_node_type -为管道步骤排名并选择最佳的聚合节点类型

研讨会（迭代式、对话式）

• pipeline_workshop_open -打开预加载工作区上下文的迭代管道构建器会话
• pipeline_workshop_instruct -发送自然语言指令以修改当前车间计划
• get_pipeline_workshop_status -获取研讨会会话的当前状态
• pipeline_workshop_close -结束研讨会并释放资源

当地项目验证和规划

• 🧰 coa_validate -验证YAML模式并扫描本地项目以查找配置问题
• 🧰 coa_plan -通过将本地项目与云环境进行比较来生成JSON部署计划（非破坏性）

Node editing — create, update, delete, and configure workspace nodes

创建

• create_workspace_node_from_scratch -创建一个没有前置节点的工作区节点
• create_workspace_node_from_predecessor -使用列覆盖率验证从前置节点创建节点
• create_node_from_external_schema -创建一个工作区节点，其列与现有仓库表或外部架构匹配

更新

• set_workspace_node -用全文替换工作区节点
• update_workspace_node -安全更新工作区节点的选定字段
• replace_workspace_node_columns -更换 metadata.columns 批发
• delete_workspace_node -从工作区中删除节点⚠️

配置

• complete_node_configuration -通过分析上下文智能地完成节点的配置
• apply_join_condition -为多前置节点自动生成并编写FROM/JOIN/ON子句
• convert_join_to_aggregation -将联接样式节点转换为聚合事实样式节点

磁盘↔ 云往返

• serialize_workspace_node_to_disk_yaml -将云工作区节点转换为磁盘上的 nodes/*.yml shape coa读取（放入coa项目进行模拟渲染）
• parse_disk_node_to_workspace_body -将磁盘上的coa节点YAML转换回云工作区节点体 set_workspace_node / update_workspace_node
• apply_sql_to_workspace_node -用户对渲染的DDL/DML SQL进行往返编辑(coa_dry_run_create / coa_dry_run_run 输出）返回到云节点——列差异、源映射推断、GROUP BY/ORDER BY/LIMIT、INSERT目标重命名

子图和作业

• create_workspace_subgraph -创建子图以直观地对节点进行分组
• update_workspace_subgraph -更新子图的名称和节点成员资格
• delete_workspace_subgraph -删除子图（节点不会被删除）⚠️
• create_workspace_job -使用节点包含/排除选择器在工作区中创建作业
• update_workspace_job -更新作业的名称和节点选择器
• delete_workspace_job -删除作业⚠️

Runs & execution — start, retry, poll, diagnose, and cancel runs

• start_run -开始新的跑步；需要Snowflake身份验证
• run_and_wait -开始运行并轮询，直到完成
• run_status -检查正在运行的作业的状态
• retry_run -重试失败的运行
• retry_and_wait -重试失败的运行并轮询，直到完成
• cancel_run -取消正在运行的作业⚠️
• diagnose_run_failure -对错误进行分类，找出根本原因，提出可行的解决方案
• get_environment_overview -带有完整节点列表的环境详细信息
• get_environment_health -仪表板：节点计数、运行状态、过去24小时内的失败运行、过时节点、依赖关系健康状况

本地执行（捆绑CLI）

• 🧰 coa_dry_run_create -预览DDL而不执行（确实 不 验证仓库中是否存在列/类型）
• 🧰 coa_dry_run_run -预览DML而不执行（同样的警告）
• 🧰 coa_create -对所选节点的仓库运行DDL（CREATE/REPLACE）⚠️
• 🧰 coa_run -运行DML（INSERT/MERGE）以填充所选节点⚠️
• 🧰 coa_deploy -将JSON计划应用于云环境⚠️
• 🧰 coa_refresh -在已部署的环境中为选定节点运行DML（不需要本地项目）⚠️

仓库源代码发现（捆绑的CLI，v0.10中的新功能）

将这三个与板载仓库表配对作为源节点，而无需手动编写YAML。典型流程： list 查看每个位置的计数， add （范围由 location)脚手架，可选 remove 在位置退役时删除节点。每 add 填充源节点的 database/schema 从工作区配置中——之后没有需要修复的占位符值。

• 🧰 coa_list_warehouse_sources -列出每个存储位置的仓库表；摘要或每表详细信息（含 alreadyExists 旗帜）
• 🧰 coa_add_warehouse_sources ⚠️ - 从仓库表中构建源节点YAML文件；支持 dryRun: true 用于预览
• 🧰 coa_remove_warehouse_sources ⚠️ - 删除脚手架源节点YAML；跳过手动重命名的文件

Lineage & impact — trace dependencies, analyze impact, propagate column changes

• get_upstream_nodes -遍历节点的完整上游依赖关系图
• get_downstream_nodes -遍历节点的完整下游依赖关系图
• get_column_lineage -在管道的上游和下游追踪一列
• analyze_impact -更改节点或特定列的下游影响——按深度和关键路径分组的受影响计数
• propagate_column_change -在列重命名或数据类型更改后更新所有下游列⚠️

Repo-backed node types — inspect committed node-type definitions, variants, and templates

• list_repo_packages -列出已提交的Coalesce仓库中的包别名和已启用的节点类型覆盖率
• list_repo_node_types -从中列出确切的可解析已提交节点类型标识符 nodeTypes/
• get_repo_node_type_definition -解析一个节点类型，并返回其外部定义和解析结果 nodeMetadataSpec
• generate_set_workspace_node_template -生成一个对YAML友好的 set_workspace_node 正文模板
• search_node_type_variants -按规范化的族、包、基元或支持状态搜索已提交的节点类型语料库
• get_node_type_variant -按变量键加载一个精确的节点类型语料库变量
• generate_set_workspace_node_template_from_variant -从已提交的语料库变体生成模板

Projects, environments & git accounts — admin CRUD for top-level resources

• create_environment -在项目中创建新环境
• delete_environment -删除环境⚠️
• create_project -创建新项目
• update_project -更新项目
• delete_project -删除项目⚠️
• list_git_accounts -列出所有git帐户
• get_git_account -获取git帐户详细信息
• create_git_account -创建一个新的git帐户
• update_git_account -更新git帐户
• delete_git_account -删除git帐户⚠️

Users & roles — assign and remove org, project, and environment roles

• list_org_users -列出所有组织用户
• get_user_roles -获取特定用户的角色
• list_user_roles -列出所有用户角色
• set_org_role -为用户设置组织角色
• set_project_role -为用户设置项目角色
• delete_project_role -从用户中删除项目角色⚠️
• set_env_role -为用户设置环境角色
• delete_env_role -从用户中删除环境角色⚠️

Cache, skills & setup — local snapshots, customizable skills, and setup diagnostics

缓存快照

• cache_workspace_nodes -获取工作区节点的每一页，写入完整快照，并返回缓存元数据
• cache_environment_nodes -获取环境节点的每一页，写入完整快照
• cache_runs -获取运行结果的每一页，写入完整快照
• cache_org_users -获取组织用户的每一页，写一个完整的快照
• clear_data_cache -删除所有缓存的快照、自动缓存的响应和计划摘要⚠️

技能和设置

• personalize_skills -将捆绑的技能文件导出到本地目录进行自定义
• diagnose_setup -无状态探测报告配置的安装件；与 /coalesce-setup MCP提示
• 🧰 coa_doctor -检查本地项目的端到端配置、凭据和仓库连接
• 🧰 coa_bootstrap_workspaces ⚠️ - 跑 coa doctor --fix 写一个启动器 workspaces.yml 从 locations.yml （占位符值——用户必须在运行仓库操作之前进行编辑）
• 🧰 coa_describe -按主题+可选子主题（也可作为 coalesce://coa/describe/* 资源）

______________________________________________________________________

完整安装

要求：

• 22+
• A. 合并 具有工作区的帐户
• MCP兼容的AI客户端（参见 快速开始)
• Snowflake凭据-仅当您计划使用运行工具或 coa_create/coa_run （参见 凭证)
• 未包装的安装占用空间约为76 MB（捆绑的 @coalescesoftware/coa CLI自带运行时；MCP tarball本身小于1MB）

1.克隆你的项目。 如果你的团队已经在Git中有一个Coalesce项目，请在本地克隆它——捆绑 coa CLI在项目目录上运行，因此大多数本地创建/运行工具都需要磁盘上的一个：

git clone 
cd my-project

还没有Git链接的项目？在Coalesce UI中，打开您的工作区→ 设置→ Git 并连接一个仓库（或通过Git提供程序创建一个仓库并粘贴URL）。Coalesce将在第一次推送时提交项目框架；一旦填充了该仓库，就在本地克隆它。

What's in a Coalesce project directory?

my-project/
├── data.yml                 # Root metadata (fileVersion, platformKind)
├── locations.yml            # Storage location manifest
├── nodes/                   # Pipeline nodes (.yml for V1, .sql for V2)
├── nodeTypes/               # Node type definitions with templates
├── environments/            # Environment configs with storage mappings
├── macros/                  # Reusable SQL macros
├── jobs/                    # Job definitions
└── subgraphs/               # Subgraph definitions

V1与V2 -格式由固定 fileVersion 在 data.yml. 第1版 (fileVersion: 1 或 2)将每个节点存储为一个包含列、转换和配置内联的YAML文件。 V-2型 (fileVersion: 3)SQL优先：节点体位于 .sql 文件使用 @id / @nodeType 注释和 {{ ref() }} 引用，配置时保留YAML。新项目默认为V2；现有的V1项目保持不变。

\[！注意\] V2状态截至v0.10。 支持V2。此MCP的早期版本需要 v2Acknowledged: true 旗子垂下 coa_create / coa_run / coa_plan 因为V2解析器具有无声故障模式。COA 7.35修复了两个最大的问题（双向配置注释同步， UNION ALL 保存），因此旗帜已被移除。编写V2时仍存在两个较小的粗糙边缘-- coa validate 混叠列上的误报和解析错误呈现为零列 CREATE TABLE ... AS SELECT WHERE 1=0The V2_DETECTED 两个飞行前警告面；这 coalesce://context/sql-node-v2-policy 资源部有完整的剧本。

通过设置将MCP指向此目录 repoPath 在 ~/.coa/config 或 COALESCE_REPO_PATH 在您的env块中。

2.创建 workspaces.yml. 此文件是 必需的 为了 coa_create / coa_run 以及它们的模拟运行变体。它映射了中声明的每个存储位置 locations.yml 以物理数据库+模式进行本地开发。它通常是gitignored（每个开发人员），因此克隆项目不会给你——你必须创建它。

这 /coalesce-setup 提示检测到丢失 workspaces.yml 并引导你完成它。如果你更愿意直接做，请选择以下选项之一：

• 让你的经纪人引导它 （最简单）：提示客服拨打 coa_bootstrap_workspaces 工具（它需要 confirmed: true，因此代理将在运行前询问）。

> \[！警告\] > 生成的文件包含占位符值。 引导工具种子 database/schema 默认值与您的实际仓库不匹配。在调用之前，请代理与您一起打开文件并替换每个占位符 coa_create / coa_run -否则，生成的DDL/DML将针对错误的（或不存在的）数据库。

• 手写。 请代理通过以下方式获取权威模式 coa_describe 工具(topic: "schema", subtopic: "workspaces")-没有顶级包装，没有 fileVersion.

Example workspaces.yml

  # workspaces.yml - keys are workspace names; `dev` is the default if --workspace is omitted
  dev:
    connection: snowflake          # required - name of the connection block COA should use
    locations:                     # optional - one entry per storage location name from locations.yml
      SRC_INGEST_TASTY_BITES:
        database: JESSE_DEV        # required
        schema: INGEST_TASTY_BITES # required
      ETL_STAGE:
        database: JESSE_DEV
        schema: ETL_STAGE
      ANALYTICS:
        database: JESSE_DEV
        schema: ANALYTICS

请您的代理验证设置，例如。 *“跑 coa_doctor 对我的项目进行总结。"* 它检查 data.yml, workspaces.yml、凭证和仓库端到端连接。

Simpler alternative: workspace.yml (singular, COA 7.35+)

COA 7.35（与v0.10捆绑的版本）也接受 workspace.yml （注： 单数，不是复数 workspaces.yml 上文）。这只是一套公寓 locations: map--没有顶级工作区名称，没有 connection: 块——当您只需要本地存储映射而不需要在命名工作区之间切换时，它是合适的。

# workspace.yml (singular) - per-repo local storage mappings only
locations:
  SRC_INGEST_TASTY_BITES:
    database: JESSE_DEV
    schema: INGEST_TASTY_BITES
  ANALYTICS:
    database: JESSE_DEV
    schema: ANALYTICS

这两个文件是独立的： workspaces.yml （复数）处理多工作空间云配置文件， workspace.yml （单数）处理每个repo的本地映射。如果不需要多工作区，请选择更简单的形状。通过以下方式获取规范模式 coa_describe (topic: "schema", subtopic: "workspace").

3.选择一个身份验证路径：

Option A - env var Option B - reuse ~/.coa/config

对于首次使用MCP的用户来说，这是最简单的。生成一个 COALESCE_ACCESS_TOKEN 来自Coalesce→ 部署→ 用户设置，然后将其包含在您的客户端配置中：

{
  "env": {
    "COALESCE_ACCESS_TOKEN": ""
  }
}

如果你已经在使用 coa CLI-服务器读取相同的配置文件，因此不需要复制。放下 env 完全封锁：

{
  "command": "npx",
  "args": ["coalesce-transform-mcp"]
}

看 凭证 对于配置文件模式。

当两个源都设置了一个字段时，env var获胜。

4.安装服务器 通过其中一个 快速开始 上面的路径。

5.重新启动客户端， 然后运行 /coalesce-setup 提示验证所有内容是否已连接。

如果要管理多个Coalesce环境，请参阅 多个环境.

凭证

服务器从两个来源读取凭据，并将其与 env优先 -匹配的envvar总是覆盖配置文件值，因此您可以在每个会话中固定一个字段，而无需编辑配置文件。呼叫 diagnose_setup 查看每个值的来源。

来源1： ~/.coa/config （与分享 coa CLI）

COA将凭据存储在标准INI文件中。你手工制作，或者让 coa 在使用CLI时编写它。MCP读取所选的配置文件 COALESCE_PROFILE （默认值 [default])并将下面的键映射到它们匹配的env变量上。

[default]
token=
domain=https://your-org.app.coalescesoftware.io
snowflakeAccount=   # e.g., abc12345.us-east-1 - required by coa CLI
snowflakeUsername=YOUR_USER
snowflakeRole=YOUR_ROLE
snowflakeWarehouse=YOUR_WAREHOUSE
snowflakeKeyPairKey=/Users/you/.coa/rsa_key.p8
snowflakeAuthType=KeyPair
orgID=              # optional; fallback for cancel-run
repoPath=/Users/you/path/to/repo # optional; for repo-backed tools
cacheDir=/Users/you/.coa/cache   # optional; per-profile cache isolation

[staging]
# …additional profiles; select with COALESCE_PROFILE

键映射 -每个配置文件键都映射到一个具有相同概念的环境变量：

笔记：

• snowflakeAuthType 由COA本身读取（无环境变量）-在使用密钥对认证时包含它。
• orgID, repoPath，以及 cacheDir 是MCP特定的，COA CLI会忽略它们。
• 上面只显示了MCP需要的字段。COA的配置支持更多-run npx @coalescesoftware/coa describe config 供权威参考。未知密钥被忽略。

如果 ~/.coa/config 不存在-服务器仅运行env-启动不会在缺少或格式错误的配置文件上失败；它只是记录一个stderr警告。

源2:MCP配置中的env变量

Snowflake凭据（仅限运行工具）

start_run, retry_run, run_and_wait, retry_and_wait，仓库触摸COA工具(coa_create, coa_run)需要雪花证书。这些通常来自 ~/.coa/config.通过env var重写任何字段：

“必需”是指env或匹配项之一 ~/.coa/config 字段必须提供值。 SNOWFLAKE_PAT 仅限于env -COA的配置使用 snowflakePassword 对于基本身份验证（一个不同的概念），此服务器故意不读取。

字段级覆盖

Pin a profile but override one field without editing the config file

{
  "coalesce-transform": {
    "command": "npx",
    "args": ["coalesce-transform-mcp"],
    "env": {
      "COALESCE_PROFILE": "staging",
      "SNOWFLAKE_ROLE": "TRANSFORMER_ADMIN"
    }
  }
}

阅读：“使用 [staging] 配置文件，但覆盖其 snowflakeRole."

多个环境

Register dev / staging / prod as separate namespaced servers

如果您在多个Coalesce环境（dev/stating/prod或多个组织）中工作，请在不同的服务器名称下为每个配置文件注册一次包：

{
  "mcpServers": {
    "coalesce-prod": {
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": {
        "COALESCE_PROFILE": "prod",
        "COALESCE_MCP_READ_ONLY": "true"
      }
    },
    "coalesce-dev": {
      "command": "npx",
      "args": ["coalesce-transform-mcp"],
      "env": { "COALESCE_PROFILE": "dev" }
    }
  }
}

为什么是这种模式：

• 命名空间工具。 客户端表面 coalesce-prod__* vs coalesce-dev__*，因此代理不会意外地改变错误的环境。
• 根据环境安全。 将prod与 COALESCE_MCP_READ_ONLY=true 隐藏该服务器上的每个写入工具，同时使dev完全可写。
• 无需处理每次通话的配置文件。 每台服务器在启动时都被固定。

如果您只使用一个环境，请跳过此模式——单个注册更简单。对于2-3个环境，额外的配置是值得的；除此之外，每个服务器都是一个单独的Node进程，因此请考虑您是否真的需要一次加载它们。

安全模型

三层防止破坏性的意外。看 docs/safety-model.md 用于完整分解（工具注释、只读模式、显式确认、COA飞行前验证）。

• 工具注释 -每个工具都带有MCP readOnlyHint / destructiveHint / idempotentHintThe⚠️ 标记在 工具 标记 destructiveHint: true 工具。
• COALESCE_MCP_READ_ONLY=true 在服务器启动时隐藏所有写入/转换工具。将其用于审计、代理沙盒或与prod配置文件配对。
• 明确确认 论破坏性行动- delete_*, propagate_column_change, cancel_run, clear_data_cache, coa_create, coa_run, coa_deploy, coa_refresh 所有要求 confirmed: true.

更多配置

• 预发布渠道 -点 npx 在 @preview 用于预览版本。
• 诊断设置 -the diagnose_setup 探头和 /coalesce-setup MCP提示。

______________________________________________________________________

设计注意事项

• 不允许SQL重写。 节点是通过YAML/config（列、转换、连接条件）构建的，而不是原始SQL。模板生成条 overrideSQLToggle，写助手拒绝 overrideSQL 领域。
• 缓存。 较大的响应会自动缓存到磁盘。使用 cache_workspace_nodes 当你想要一个可重复使用的快照时，可以使用兄弟姐妹。配置阈值 COALESCE_MCP_AUTO_CACHE_MAX_BYTES.
• 回购支持的工具。 集 COALESCE_REPO_PATH （或添加 repoPath= 到您的~/.coa/config配置文件）到您本地的Coalesce仓库根目录（包含 nodeTypes/, nodes/, packages/)，或通过 repoPath 在单独的工具调用中。服务器不会克隆存储库或安装软件包。
• COA CLI版本控制。 捆绑的COA CLI被固定到精确的alpha版本- *不* 漂浮物 @next 标签。此MCP的每个版本都具有已知的良好COA构建。
• COA描述了缓存。 COA描述输出缓存在 ~/.cache/coalesce-transform-mcp/coa-describe// 在第一次访问之后。缓存是版本键控的——升级MCP会自动使过时内容无效。

______________________________________________________________________

链接

||资源|| | :-: | :-- | :-- | | 📘 | 合并文档 |产品文档| | 🔌 | 合并API文档 |REST API参考| | 🧰 | Coalesce CLI(coa) |捆绑的CLI文档| | 🛒 | 联合市场 |节点类型包| | 🔗 | 模型上下文协议 |MCP规范和生态系统|

______________________________________________________________________

贡献

欢迎发布问题和PR。

• 🐛 错误报告 - 打开一个问题
• 💡 功能请求 - 展开讨论

许可证

麻省理工学院 ©Coalesce-建在开放的顶部 模型上下文协议.