Snowflake规则引擎 - MCP服务器

![License](LICENSE) ![Snowflake](https://www.snowflake.com)

A. 由Snowflake托管的MCP服务器 该工具提供了全面的规则，用于解决Snowflake问题、构建存储过程以及创建复现案例。它利用Cortex Search进行语义搜索，并使用Cortex Analyst进行自然语言查询。

注这是一个专为支持工程工作流设计的Snowflake内部项目。它需要访问Snowflake的内部系统和数据。

🎯 目的

这个规则引擎作为 单一真实来源 针对多个项目中的Snowflake故障排除知识。它提供：

DPO → 表映射如何将Snowflake对象映射到Snowhouse表
源代码访问GitHub上的MCP模式用于探索Snowflake存储库
文档访问Snowflake Docs MCP模式的官方指南
代码质量示例和最佳实践的Context7 MCP模式
调查工作流程系统化的故障排除程序
SQL 模式高效的Snowhouse查询技术

🏗️ 建筑学

Snowflake组件

┌─────────────────────────────────────────────────────┐
│                    Cursor AI                        │
│                                                     │
│  ┌───────────────────────────────────────────────┐ │
│  │         MCP Client (snow mcp connect)         │ │
│  └───────────────┬───────────────────────────────┘ │
└──────────────────┼─────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│         Snowflake MCP Server                        │
│         (temp.support_sp_dev.support_rules_mcp)     │
│                                                     │
│  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │  get-snowflake-rule │  │ list-snowflake-rules│  │
│  │  (Cortex Search)    │  │  (Cortex Analyst)   │  │
│  └──────────┬──────────┘  └──────────┬──────────┘  │
└─────────────┼────────────────────────┼─────────────┘
              │                        │
              ▼                        ▼
   ┌─────────────────────┐  ┌─────────────────────┐
   │   rules_search      │  │   rules_metadata    │
   │ (Cortex Search)     │  │  (Semantic View)    │
   └──────────┬──────────┘  └──────────┬──────────┘
              │                        │
              └────────────┬───────────┘
                           ▼
                  ┌─────────────────┐
                  │   rules table   │
                  │  (42 rules)     │
                  └─────────────────┘

规则层级

rules/
├── _meta/                     # Meta-rules (composite workflows)
│   ├── troubleshooting.mdc   # Complete troubleshooting workflow
│   ├── stored-procedures.mdc # Complete SP generation workflow
│   └── reproductions.mdc     # Complete reproduction workflow
│
├── core/                      # Core knowledge (reusable)
│   ├── 01-github-mcp.mdc     # Source code access patterns
│   ├── 02-docs-mcp.mdc       # Documentation access patterns
│   ├── 03-code-quality-mcp.mdc # Code examples and best practices
│   ├── 04-dpo-mappings.mdc   # DPO→table mappings (critical!)
│   └── 05-snowhouse-querying.mdc # Query patterns
│
├── workflows/                 # Workflow-specific guidance
│   ├── troubleshooting.mdc   # Investigation workflows
│   ├── stored-procedures.mdc # SP generation patterns
│   └── reproductions.mdc     # Reproduction building
│
├── connectors/                # Connector-specific rules (11 files)
│   ├── python.mdc
│   ├── jdbc.mdc
│   └── ...
│
└── spcs/                      # SPCS-specific rules (10 files)
    ├── architecture.mdc
    └── ...

🚀 快速入门

1. 配置光标MCP

添加到您的Cursor MCP配置中（~/.cursor/mcp.json 或光标设置 → MCP)：

{
  "mcpServers": {
    "snowflake-rules": {
      "command": "snow",
      "args": [
        "mcp",
        "connect",
        "--connection",
        "snowhouse",
        "--mcp-server",
        "temp.support_sp_dev.support_rules_mcp"
      ],
      "env": {}
    }
  }
}

2. 重启光标（或：重新启动光标工具）

重启光标以加载MCP服务器。

3. 遵守规则

在 Cursor 聊天中，提出有关 Snowflake 故障排除的问题：

"How do I troubleshoot Python connector authentication issues?"
"Show me the DPO mappings for image repositories"
"What are the best practices for writing stored procedures?"

Cursor AI 将自动调用 MCP 工具来检索相关规则。

📊 已部署内容

创建的对象

数据库： temp
模式/架构： support_sp_dev
桌子： rules （42条规则：14条核心规则，11条连接规则，10条特殊规则，7条工作流规则）
Cortex Search 翻译为中文是“皮层搜索”或“大脑皮层搜索”（具体翻译可能根据上下文有所调整，但“皮层搜索”是较为直接的译法）。不过，需要注意的是，“Cortex”一词在计算机科学或人工智能领域中，有时也可能被用作特定技术或系统的名称，因此其翻译可能需要结合具体语境来确定。但在此处，若仅从字面意义翻译，“皮层搜索”是一个合理的选项： rules_search （对所有规则进行语义搜索）
语义视图： rules_metadata (可查询的元数据)
MCP 服务器: support_rules_mcp （2个工具）

可用的MCP工具

get-snowflake-rule - 搜索并检索规则内容

- 类型： CORTEX_SEARCH_SERVICE_QUERY - 查询示例： "troubleshooting"， "dpo mappings"， "python connector" - 按以下条件筛选 rule_type： meta， core， connector， spcs， workflow

list-snowflake-rules - 列出并发现可用规则

- 类型： CORTEX_ANALYST_MESSAGE - 自然语言查询： "list all rules"， "show me connector rules"， "how many core rules?"

访问

具有访问权限的角色： ENGINEER， ENGINEER_BASIC
所有者： SUPPORT_ENGINEER

🔧 安装与部署

初始设置（运行一次）

# 1. Create rules table
snow sql -c snowhouse -f sql/01_create_table.sql

# 2. Upload rules from local files
python upload_rules.py

# 3. Create Cortex Search service
snow sql -c snowhouse -f sql/02_create_single_service.sql

# 4. Force immediate indexing (or wait ~1 hour)
snow sql -c snowhouse -f sql/04_force_refresh.sql

# 5. Create semantic view for Cortex Analyst
snow sql -c snowhouse -f sql/05_create_semantic_view.sql

# 6. Create MCP server
snow sql -c snowhouse -f sql/06_create_mcp_server.sql

# 7. Test the setup
snow sql -c snowhouse -f sql/test_queries.sql

更新工作流

当规则需要更新时：

# 1. Edit rules locally in rules/ directory
vim rules/core/04-dpo-mappings.mdc

# 2. Upload changes to Snowflake
python upload_rules.py

# 3. Force immediate refresh
snow sql -c snowhouse -f sql/04_force_refresh.sql

🎯 使用场景

1. 故障排除项目

目标调查客户SPCS镜像仓库创建失败的原因。

在光标处:

"Load troubleshooting rules for SPCS image repository issues"

工作流程：

查看文档： mcp_snowflake-docs_CKESnowflakeDocs("SPCS image repository")
查询Snowhouse：已确认 stage_etl_v 和；与 stage_type = 'IMAGE_REPOSITORY' （不是专用的桌子！）
搜索来源： mcp_github_search_code("imageRepositoryDPO repo:snowflakedb/snowflake")
分析日志：获取时间戳 job_etl_v，查询 gs_logs_v 有界限/限制

2. 存储过程项目

目标创建一个过程，用于检索特定工单的失败查询。

在光标处：

"Help me write a stored procedure to query failed jobs in Snowhouse"

工作流：

地图需求：查询失败 → job_etl_v
获取示例： mcp_context7_get-library-docs("/snowflakedb/snowpark-python", "stored procedures")
构建查询：从...开始 job_etl_v按 account_id 和 error_code 过滤
编写程序的步骤：使用类型提示、错误处理、日志记录
测试并记录

3. 繁殖项目

目标重现Python连接器的认证问题。

在光标处:

"Show me how to create a minimal reproduction for a Python connector auth bug"

工作流程：

检查文档： mcp_snowflake-docs_CKESnowflakeDocs("authentication methods")
查找来源： mcp_github_search_code("auth repo:snowflakedb/snowflake-connector-python")
获取示例： mcp_context7_get-library-docs("/snowflakedb/snowflake-connector-python", "authentication")
构建最小可复现示例：自包含、可运行的代码
验证并记录

🔍 维护

查看最近更新

SELECT rule_name, rule_type, version, updated_at
FROM temp.support_sp_dev.rules
ORDER BY updated_at DESC
LIMIT 10;

通过关键词查找规则

SELECT rule_name, rule_type, rule_description
FROM temp.support_sp_dev.rules
WHERE rule_content ILIKE '%keyword%';

检查规则统计

SELECT 
    rule_type,
    COUNT(*) AS count,
    AVG(LENGTH(rule_content)) AS avg_size
FROM temp.support_sp_dev.rules
GROUP BY rule_type;

刷新搜索索引

ALTER CORTEX SEARCH SERVICE temp.support_sp_dev.rules_search REFRESH;

🚨 关键知识

最大的错误：依赖舞台支持的对象

并非所有对象都有专用的表格！

这些对象使用 stage_etl_v：

❌ 错误： image_repository_etl_v （不存在！）
✅ 正确： stage_etl_v （与……一起）带着；用；凭借 stage_type = 'IMAGE_REPOSITORY'

舞台支持的对象：

镜像仓库 → stage_etl_v （介词）和……一起；带着；用 stage_type = 'IMAGE_REPOSITORY'
Git 仓库 → stage_etl_v 和；与 stage_type = 'GIT_REPOSITORY'
命名阶段 → stage_etl_v 和；与；带着 stage_type = 'INTERNAL'
外部舞台 → stage_etl_v 与；带有；使用 stage_type IN ('S3', 'AZURE', 'GCS')

💡 核心原则

适用于所有项目：

永远使用GitHub MCP进行源代码管理（永远不要使用本地路径）
永远使用 Snowflake Docs MCP 作为官方文档
永远按以下条件筛选Snowhouse查询 account_id
永远以……开始；从……着手 job_etl_v 用于时间戳
永远检查对象是否为舞台支持对象

对于代码项目（SP & Repro）：

永远使用Context7 MCP作为代码示例
永远包含类型提示和错误处理
永远验证输入并添加日志记录

🎯 优势/好处

对比本地Python MCP服务器

✅ 无需设置Python环境
✅ 适用于所有具有ENGINEER角色的用户
✅ 集中化规则管理
✅ 自动扩展和可用性
✅ 数据库中的版本追踪
✅ 内置语义搜索功能

🛠️ 故障排除

未找到MCP服务器

# List available MCP servers
snow sql -c snowhouse -Q "SHOW MCP SERVERS IN SCHEMA temp.support_sp_dev;"

搜索未找到规则

# Force immediate refresh
snow sql -c snowhouse -f sql/04_force_refresh.sql

权限被拒绝

# Check grants
snow sql -c snowhouse -Q "SHOW GRANTS ON MCP SERVER temp.support_sp_dev.support_rules_mcp;"

上传失败

# Check connection
snow connection test --connection snowhouse

# Verify table exists
snow sql -c snowhouse -Q "SELECT COUNT(*) FROM temp.support_sp_dev.rules;"

🔀 替代实现方案

主要方法采用的是 单一统一的Cortex搜索服务 对于所有规则，这是推荐用于大多数使用场景的。

一 替代性的多服务方法 有……可供选择/有……版本 sql/alternatives/ 这为每种规则类型（元规则、核心规则、连接器规则、SPCS规则、工作流规则）创建了独立的Cortex Search服务。这样提供了更精细的控制，但同时也增加了复杂性。

何时考虑替代方案：

每种规则类型需要不同的刷新计划
只想授予对特定规则类别的访问权限
要求严格区分规则类型

见 sql/alternatives/README.md 以了解详细信息和权衡取舍。

📁 项目结构

.
├── sql/                          # Setup SQL scripts
│   ├── 01_create_table.sql       # Create rules table
│   ├── 02_create_single_service.sql # Create Cortex Search
│   ├── 04_force_refresh.sql      # Force indexing
│   ├── 05_create_semantic_view.sql # Create semantic view
│   ├── 06_create_mcp_server.sql  # Create MCP server
│   ├── test_queries.sql          # Validation queries
│   └── alternatives/             # Alternative implementations
│       └── README.md             # Multi-service approach
│
├── rules/                        # Rule content (42 .mdc files)
│   ├── _meta/                    # Meta-rules
│   ├── core/                     # Core knowledge
│   ├── workflows/                # Workflow guidance
│   ├── connectors/               # Connector-specific
│   └── spcs/                     # SPCS-specific
│
├── upload_rules.py               # Upload script
├── rules_semantic_model.yaml     # Cortex Analyst model
├── cursor-mcp-config.json        # Cursor MCP configuration
├── README.md                     # This file
├── QUICK_START.md                # Fast setup guide
│
└── archive/                      # Archived implementations
    └── python-mcp-server/        # Original Python MCP server

⚡ 快速参考

最常见的规则

规则	目的
`_meta/troubleshooting.mdc`	完整的故障排除设置
`_meta/stored-procedures.mdc`	完整的SP（软件平台/服务提供商等，具体含义需根据上下文确定）开发环境设置
`core/04-dpo-mappings.mdc`	对象→表映射
`core/05-snowhouse-querying.mdc`	查询模式

最常见的映射

对象	表格	过滤器
图片库	`stage_etl_v`	`stage_type = 'IMAGE_REPOSITORY'`
Git 仓库	`stage_etl_v`	`stage_type = 'GIT_REPOSITORY'`
查询	`job_etl_v`	`start_time` 范围
仓库	`warehouse_etl_v`	`warehouse_name`

MCP服务器快速参考指南

# From Cursor - these tools are called automatically
mcp_snowflake-rules_get-snowflake-rule(query="troubleshooting", filter={...})
mcp_snowflake-rules_list-snowflake-rules(message="list all core rules")

📞 支持

问题在你内部的错误跟踪系统中提交文件
更新规则由中央统一更新，并自动提供使用
问题先检查现有规则，再寻求帮助
替代方案Python MCP服务器现已可用 archive/python-mcp-server/

______________________________________________________________________

状态✅ 准备就绪，可投入生产\ 最后更新时间2025年10月10日\ 规则计数42（14个核心，11个连接器，10个特殊组件，7个工作流程）\ 由……维护Snowflake支持工程团队