sql-template-mcp

将 ssrc-sql-generator 技能生成的 SQL 步骤沉淀为可检索复用的模板库，解决本地 .md 模板手动维护繁琐的问题。与 sql-ops-mcp 解耦：后者负责查询公司内部生产库（依赖 Archery 登录态），本工具负责读写自有模板库（Supabase / Postgres）。

随模板库增长，日常运维中可复用的场景越来越多，技能生成 SQL 前先检索模板、完成后询问用户是否沉淀，形成「生成 → 检索复用 → 沉淀 → 再复用」的闭环。

能力一览

工具	作用
save_sql_template	将生成的 SQL 沉淀为模板（含相似去重检查，自动生成 embedding）
search_sql_template	混合检索：语义向量召回 + 关键词匹配，按相似度/使用次数排序
semantic_search_sql_template	纯语义召回，适合自然语言/口语化、同义改写查询
get_sql_template	按 id 获取单个模板完整内容
list_sql_templates	总览模板库（可按分类/单据类型/验证状态过滤）
update_sql_template	更新已有模板（如补充 ✅ 已验证标记、修正 SQL，同步刷新 embedding）
delete_sql_template	删除错误/过期模板
record_template_usage	记录模板被使用一次（统计使用次数，优化检索排序）

表结构

在 Supabase SQL Editor 执行 schema.sql 建表。关键字段：

• verified / verified_at：是否 ✅ 已验证，验证过的模板可被技能免 MCP 校验复用
• usage_count / last_used_at：使用统计，用于评估模板价值、优化检索排序
• created_by / source：作者与来源（migrated 手工迁移 / auto 自动沉淀 / manual 手工新增），为团队共享预留
• keywords / core_tables：数组字段，配合 pg_trgm + GIN 索引支持模糊与标签检索
• embedding：vector(2048) 语义向量，由 NVIDIA 免费 Embedding 生成，配合 match_sql_templates RPC 做语义召回

语义检索（向量）

采用混合检索：保留原有表存储（SQL 原文、元数据、统计、去重指纹），新增 embedding 向量列做语义召回。无需替换表，只是能力升级。

• Embedding 模型：NVIDIA 免费 API nvidia/nv-embed-v1（2048 维），免费 key 在 build.nvidia.com 申请。 因 2048 维超过 pgvector 索引上限 2000，语义检索走顺序扫描（模板库规模小，性能足够）。 （注：原 nvidia/llama-3.2-nv-embedqa-1b-v2 已于 2026-05-18 下架；若想启用 HNSW 索引可改用 ≤2000 维模型如 baai/bge-m3（1024 维）。）
• 未配置 NVIDIA_API_KEY 时：search_sql_template 自动降级为纯关键词检索，不破坏原有能力。
• 存量模板：表升级后 embedding 列为空，需跑一次回填脚本（见下）。

快速开始

# 1. 建虚拟环境并安装
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# 2. 配置 Supabase 连接与（可选）NVIDIA key
cp .env.example .env
# 编辑 .env 填入 SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY
# 如需语义检索，再填 NVIDIA_API_KEY

# 3. 建表：在 Supabase 控制台 SQL Editor 执行 schema.sql
#    （已含 pgvector 扩展、embedding 列、HNSW 索引与 match_sql_templates RPC）

# 4. 迁移本地模板入库（幂等，可重复执行）
python scripts/seed_data.py

# 5. 回填存量模板的 embedding 向量（仅首次升级表结构后需要；--all 可重算全部）
python scripts/backfill_embeddings.py

# 6. 自检
sqltpl          # 或 python -m sql_template_mcp.cli

MCP 注册（stdio）

在 MCP 客户端配置中加入（路径替换为你本地的 venv）：

{
  "mcpServers": {
    "sql-template": {
      "command": "/path/to/sql-template-mcp/.venv/bin/python",
      "args": ["-m", "sql_template_mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Service Role Key 拥有绕过 RLS 的完整权限，仅限服务端/本地 MCP 使用，切勿暴露给前端或提交到仓库。若部署到共享环境并改用 anon key，需在 Supabase 侧配置 RLS 策略控制写入权限。

与 ssrc-sql-generator 的协作

• 生成 SQL 前：技能调用 search_sql_template（混合检索，含语义召回）或 semantic_search_sql_template（自然语言查询）检索可复用模板（优先 ✅ 已验证）
• 生成 SQL 后：技能询问用户是否 save_sql_template 沉淀本次结果（自动写入 embedding）
• MCP / NVIDIA 不可用时：技能降级为「纯关键词检索 / 不检索直接生成、提示无法沉淀」，不阻塞主流程

后续优化方向（预留，未实现）

• 模板版本管理：parent_id + 历史表，沉淀更新时保留旧版本
• 相似度推荐增强：保存前用 embedding 余弦相似度给出更精准的「是否重复」建议（目前为 SQL 指纹去重）
• 共享/权限：基于 created_by 的团队可见性控制（配合 RLS）