# sql-template-mcp

将 **ssrc-sql-generator** 技能生成的 SQL 步骤沉淀为可检索复用的模板库，解决本地 `.md` 模板手动维护繁琐的问题。与 `zhenyun-pangu-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`）。

---

## 一、能力一览

| 工具 | 作用 |
|------|------|
| `save_sql_template` | 将生成的 SQL 沉淀为模板（含相似去重检查，自动生成 embedding；支持 `execution_flow` / `example_case`） |
| `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` | 记录模板被使用一次（统计使用次数，优化检索排序） |

---

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

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

### 2.1 安装 uv（同时自带 uvx）

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

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

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

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

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

### 2.2 验证 uv 是否装好

```bash
uv --version
uvx --version
```

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

### 2.3 安装 Python（可选但推荐）

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

```bash
uv python install 3.11
```

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

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

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

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

> 国内网络受限时可先设置镜像再执行上面的 `uv sync`：
> ```bash
> export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
> ```

### 2.5 配置 `.env`

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

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

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

```ini
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（可选）

```bash
# 种子模板（幂等，可重复执行）
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`）：

```json
{
  "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 验证

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

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

---

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

### 3.1 安装 uv（同时自带 uvx）

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

```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 生效），再执行：

```powershell
uv --version
uvx --version
```

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

### 3.3 安装 Python（可选但推荐）

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

```powershell
uv python install 3.11
```

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

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

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

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

> 国内网络受限时可先设置镜像再执行上面的 `uv sync`：
> ```powershell
> $env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
> ```

### 3.5 复制并填写配置文件

在 PowerShell 中复制模板：

```powershell
Copy-Item .env.example .env
```

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

### 3.6 建表

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

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

```powershell
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`）：

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

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

### 3.9 验证

```powershell
uvx --from "$DIR" sqltpl
```

---

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

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

- **Embedding 模型**：NVIDIA 免费 API `nvidia/nv-embed-v1`（2048 维），免费 key 在 [build.nvidia.com](https://build.nvidia.com/nvidia/nv-embed-v1) 申请。
  因 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 不可用时：技能降级为「纯关键词检索 / 不检索直接生成、提示无法沉淀」，不阻塞主流程。