Snowflake MCP Artifact

聊天 → Snowflake（MCP）→ 艺术品（或“文物”，根据上下文具体含义选择）

一个最小可行性产品（MVP）本地网页应用，它将聊天式提示流式传输到Snowflake模型上下文协议（MCP）适配器，将只读SQL转换为Vega-Lite图表和表格，并在现代React用户界面中渲染所有内容。

特点/功能

• 安全API网关 – Express服务器强制执行只读SQL，增加安全性 LIMIT 默认设置，并暴露 /api/chat 更多 /api/mcp/snowflake.
• 可插拔的MCP客户端 – 在您的Snowflake MCP执行器中插入，或依赖内存中的存根进行本地演示。
• 现代React用户界面 – 使用Vite + Tailwind布局，左侧为聊天面板，右侧为文物查看器。
• 文物渲染 – 仅支持内联数据的Vega-Lite图表和表格回退。
• 测试覆盖率 – 使用 Vitest 对 SQL 守卫和工件渲染合约进行单元测试。

入门指南

1. 安装依赖项（推荐使用 pnpm）：

   pnpm install

1. 复制环境模板并填写凭据：

   cp .env.example .env

- OPENAI_API_KEY （可选）通过OpenAI响应API解锁大型语言模型摘要功能。 - OPENAI_MODEL 选择调用哪个OpenAI Responses模型（默认为 gpt-4.1-mini）。 - MCP_CONFIG_PATH 应指向一个JSON文件，该文件描述了如何加载您的Snowflake MCP适配器。

1. 启动开发服务器（Vite 在 5173 端口，Express 在 8787 端口）：

   pnpm dev

1. 为生产构建：

   pnpm build

1. 提供编译后的包：

   pnpm start

配置说明

• MCP配置JSON可以包含一个 adapterModule 和可选的 executeMethod该模块必须导出一个工厂，该工厂返回一个异步（函数/对象） (sql) => { columns, rows } 功能。若缺少此功能，服务器将回退到一个确定性的模拟数据集。
• 仅 SELECT/WITH 允许陈述。服务器会自动应用 LIMIT 500 （当）丢失时。
• CORS 仅限于 http://localhost:5173 用于POST请求。

为您的Snowflake MCP服务器布线

1. 从提供的框架开始： mcp/snowflake-adapter.example.json将其复制到一个稳定的位置（或者直接重用），然后进行微调 args 以匹配您的启动方式 snowflake-labs-mcp.

   {
     "adapterModule": "../server/mcp/snowflakeAdapter.ts",
     "options": {
       "command": "uvx",
       "args": [
         "snowflake-labs-mcp",
         "--service-config-file",
         "/Users//.mcp/tools_config.yaml",
         "--connection-name",
         "hwhi_mcp_test",
         "--authenticator",
         "externalbrowser"
       ],
       "toolName": "snowflake_sql"
     }
   }

- 当你之后运行时 pnpm build && pnpm start，点 adapterModule 到已发出的JS（../dist-server/mcp/snowflakeAdapter.js）。

1. 设定 MCP_CONFIG_PATH 在 .env 到该JSON文件的绝对路径或相对路径。
2. 确保您的Snowflake CLI连接（~/.snowflake/connections.toml) 与……相匹配 connection-name 上述内容已通过。认证流程（例如。 externalbrowser) 由……处理 snowflake-labs-mcp。

适配器使用STDIO将MCP服务器作为子进程启动，并调用其 snowflake_sql 为每个受保护的查询提供工具。如果您的MCP服务器暴露了不同的工具名称或需要额外的参数（如角色、仓库覆盖等），请进行更新 options.toolName 以及相应的参数列表。

测试

运行 Vitest 套件：

pnpm test

该套件涵盖了SQL防护栏（或SQL安全机制）和工件渲染合约。随着您将实际的MCP适配器集成进来，可以对其进行扩展。

项目结构

该仓库遵循项目简报中概述的规范：

.
├─ server/        # Express app, orchestrator, Snowflake MCP client abstraction
├─ web/           # React + Vite frontend with Tailwind styling
├─ test/          # Vitest suites
├─ dist/          # Vite build output (generated)
└─ dist-server/   # Compiled server (generated)

下一步行动

• 通过实现一个导出模块来连接真实的Snowflake MCP客户端 createSnowflakeExecutor。
• 在生产环境中替换为就绪状态的认证、可观测性和请求追踪功能。
• 增加更丰富的图表启发式方法（多种指标、细分）以及提示级别的防护措施。