sql-template-mcp

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

本目录是 uvx 打包版：通过 uvx --from <本目录> 直接运行，无需 pip install 或手动建虚拟环境。含 [project.scripts] 入口 sql-template-mcp（由 sql_template_mcp.server:main 提供）。.env 通过 MCP_ENV_DIR 指定位置（uvx 运行在缓存目录，__file__ 不指向本项目，见 config.py）。

一、能力一览

Related MCP server: mcp-codesearch

二、零基础傻瓜式安装（Mac）

本工具用 uv 管理 Python 环境。uv 会自动下载对应版本的 Python 并拉取依赖，本机可以没有预装 Python。下面每一步照抄执行即可。

2.1 安装 uv（同时自带 uvx）

打开「终端」（Finder → 应用程序 → 实用工具 → 终端），粘贴下面命令回车：

curl -LsSf https://astral.sh/uv/install.sh | sh

（如果你装了 Homebrew，也可以用 brew install uv，二选一即可。）

脚本装完后，把 uv 加进 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2.2 验证 uv 是否装好

uv --version
uvx --version

两条命令都能输出版本号（建议 uv >= 0.5）即成功。若提示 command not found，说明 PATH 没生效：重开一个终端窗口再试；或用绝对路径 ~/.local/bin/uv --version 确认。

2.3 安装 Python（可选但推荐）

uv 会自动下载所需 Python，这步可跳过。想提前手动装一份独立的 Python（不污染系统）就执行：

uv python install 3.11

2.4 拉取依赖（预热，首次必做）

uvx 首次运行要先解析并缓存依赖，耗时较久，可能让 MCP 客户端超时。先手动预热一次：

cd /你的路径/zhenyun-tools/sql-template-mcp
uv sync

看到 Installed <数量> packages 字样即完成。

国内网络受限时可先设置镜像再执行上面的 uv sync：

export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple

2.5 配置 .env

在项目目录下，把模板复制成 .env：

cd /你的路径/zhenyun-tools/sql-template-mcp
cp .env.example .env

用文本编辑器（VSCode / 文本编辑）打开 .env，填写：

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# 可选：语义检索。不填则自动降级为纯关键词检索
NVIDIA_API_KEY=

• SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY：Supabase 控制台 → Project Settings → API 中获取。

• NVIDIA_API_KEY：https://build.nvidia.com/nvidia/nv-embed-v1 免费申请，默认模型 nvidia/nv-embed-v1（2048 维）。

Service Role Key 拥有绕过 RLS 的完整权限，仅限服务端/本地 MCP 使用，切勿暴露给前端或提交到仓库。

2.6 建表

在 Supabase 控制台 SQL Editor 中执行 schema.sql（幂等，可重复执行）。

2.7 写入种子模板 / 回填 embedding（可选）

# 种子模板（幂等，可重复执行）
uv run --directory "$DIR" python scripts/seed_data.py
# 仅在配置 NVIDIA_API_KEY、需要语义检索时回填 embedding
uv run --directory "$DIR" python scripts/backfill_embeddings.py

2.8 注册为 MCP Server

在 MCP 客户端配置中加入（把 $DIR 替换成本目录绝对路径，例如 /你的路径/zhenyun-tools/sql-template-mcp）：

{
  "mcpServers": {
    "sql-template": {
      "command": "uvx",
      "args": ["--from", "$DIR", "sql-template-mcp"],
      "cwd": "$DIR",
      "env": { "MCP_ENV_DIR": "$DIR" }
    }
  }
}

要点：

• 必须使用绝对路径，不要用 ~ 或相对路径。

• MCP_ENV_DIR 指向包含 .env 的目录：uvx 运行在缓存目录，__file__ 不指向本项目，故 .env 需通过 MCP_ENV_DIR 显式指定（见 config.py）；不设置则回退到 cwd 目录的 .env。

• 凭据不写入客户端配置。

2.9 验证

# 连通 Supabase 并预览模板库前 5 条
uvx --from "$DIR" sqltpl

该 MCP 提供 8 个工具，客户端显示 8 tools / 0 prompts 属正常。

三、零基础傻瓜式安装（Windows）

3.1 安装 uv（同时自带 uvx）

按 Win 键搜索「PowerShell」，右键 → 以管理员身份运行，粘贴下面命令回车：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

（如果你装了 winget，也可以用 winget install --id=astral-sh.uv -e，二选一即可。）

3.2 验证 uv 是否装好

安装后重开一个 PowerShell 窗口（让 PATH 生效），再执行：

uv --version
uvx --version

两条命令都能输出版本号（建议 uv >= 0.5）即成功。若提示无法识别，说明 PATH 没生效：重开窗口再试。

3.3 安装 Python（可选但推荐）

uv 会自动下载所需 Python，这步可跳过。想提前装就执行：

uv python install 3.11

3.4 拉取依赖（预热，首次必做）

在 PowerShell 中进入项目目录并预热：

cd C:\你的路径\zhenyun-tools\sql-template-mcp
uv sync

看到 Installed <数量> packages 字样即完成。

国内网络受限时可先设置镜像再执行上面的 uv sync：

$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"

3.5 复制并填写配置文件

在 PowerShell 中复制模板：

Copy-Item .env.example .env

用编辑器（VSCode / 记事本）打开 .env，按「2.5」一节的变量说明填写。

3.6 建表

在 Supabase 控制台 SQL Editor 中执行 schema.sql（幂等，可重复执行）。

3.7 写入种子模板 / 回填 embedding（可选）

uv run --directory "$DIR" python scripts/seed_data.py
uv run --directory "$DIR" python scripts/backfill_embeddings.py

3.8 注册为 MCP Server

在 MCP 客户端配置中加入（把 $DIR 替换成本目录绝对路径，Windows 路径统一用正斜杠，例如 C:/你的路径/zhenyun-tools/sql-template-mcp）：

{
  "mcpServers": {
    "sql-template": {
      "command": "uvx",
      "args": ["--from", "$DIR", "sql-template-mcp"],
      "cwd": "$DIR",
      "env": { "MCP_ENV_DIR": "$DIR" }
    }
  }
}

若客户端找不到 uvx，用 where uvx 查出绝对路径，把 command 改成该路径。

3.9 验证

uvx --from "$DIR" sqltpl

四、语义检索（向量）说明

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

• Embedding 模型：NVIDIA 免费 API nvidia/nv-embed-v1（2048 维），免费 key 在 build.nvidia.com 申请。 因 2048 维超过 pgvector 的 HNSW/IVFFlat 索引维度上限 2000，当前 schema 不创建向量索引，语义检索走顺序扫描（模板库规模小，性能足够）。

• 未配置 NVIDIA_API_KEY 时：search_sql_template 自动降级为纯关键词检索，不破坏原有能力。

• 存量模板：表升级后 embedding 列为空，需跑一次回填脚本（见上文 2.7）。

五、与 ssrc-sql-generator 的协作

• 生成 SQL 前：技能调用 search_sql_template（混合检索，含语义召回）或 semantic_search_sql_template（自然语言查询）检索可复用模板（优先 ✅ 已验证）；命中含 execution_flow 的模板时强制分步执行（逐 STEP QUERY + ASSERT），禁止直接输出最终 SQL。

• 生成 SQL 后：技能询问用户是否 save_sql_template 沉淀本次结果（自动写入 embedding；数据修复类同时沉淀 execution_flow 与 example_case）。

• MCP / NVIDIA 不可用时：技能降级为「纯关键词检索 / 不检索直接生成、提示无法沉淀」，不阻塞主流程。