db-connector · MCP 落地服务 Demo（TypeScript + DeepSeek/OpenRouter）

让 AI 直接查询你的业务数据库，全程只读、安全可控。 MCP 落地服务的敲门砖作品：TypeScript 实现 + AI 驱动，真实可跑。

技术栈

• MCP 协议：官方 @modelcontextprotocol/sdk（server + client，标准协议）
• 数据库：better-sqlite3（演示）↔ PostgreSQL（生产，改适配层即可）
• AI：默认 DeepSeek，也支持 OpenRouter（含免费模型）——任意 OpenAI 兼容模型只需改 .env

快速开始

npm install
cp .env.example .env      # 填入 API key（DeepSeek 或 OpenRouter，见下）
npm run seed              # 生成演示库 demo.db（电商订单系统）
npm run smoke             # 冒烟测试（不依赖 key，验证协议与只读防护）
npm run e2e               # 端到端测试（3 个自然语言问题，需 key）
npm run chat              # 命令行直接问数据库（AI 自动查库回答）

> 哪个城市销售额最高?
🤖 销售额最高的城市是南京，约 ¥8.7 万（59 单）……

> 最近 30 天卖得最好的商品是?
> 买得最多的 3 个客户?

配置模型（三选一）

# ① DeepSeek 官方（推荐：便宜、快、国内可用）
DEEPSEEK_API_KEY=sk-xxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

# ② OpenRouter 免费模型（demo 零成本，但每天限 50 次请求，充值 $10 解锁 1000 次）
DEEPSEEK_API_KEY=sk-or-v1-xxx
DEEPSEEK_BASE_URL=https://openrouter.ai/api/v1
DEEPSEEK_MODEL=nvidia/nemotron-3-super-120b-a12b:free   # 实测工具调用较稳

# ③ 本地 llama.cpp（零成本、数据不出本机）
#    先启动 llama-server（必须加 --jinja 才能识别 tools；关 qwen3 thinking 用 chat-template-kwargs，
#    注意 JSON 不能有多余空格，否则不生效）：
#      llama-server -m Qwen3-8B-Q4_K_M.gguf --jinja \
#        --chat-template-kwargs '{"enable_thinking": false}' --port 8080
DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=http://localhost:8080/v1
DEEPSEEK_MODEL=Qwen3-8B-Q4_K_M

# ④ 任意 OpenAI 兼容服务（通义/豆包/GPT 等）
DEEPSEEK_BASE_URL=<你的服务地址>
DEEPSEEK_MODEL=<模型名>

本地模型演示建议：Qwen3-8B 的 GGUF（如 Qwen3-8B-Q4_K_M.gguf，从 HuggingFace 下载）经实测能稳定答对「哪个城市销售额最高」「哪个商品卖得最多」，但涉及日期函数/复杂多表的问题会不稳（8B 能力边界）。演示脚本请用稳定问题集。

关键启动参数：

• --jinja：让 llama-server 用模型自带的聊天模板，否则 tools（function calling）不会被识别，工具调用会失败。
• --chat-template-kwargs '{"enable_thinking": false}'：关闭 qwen3 思考链，响应更快、更直接调工具（JSON 内不能有多余空格）。
• --port 8080：默认端口即 8080，.env 里 DEEPSEEK_BASE_URL 指向 http://localhost:8080/v1。

两种演示方式（给客户看）

方式一：CLI 直接问（推荐，最快出效果）

npm run chat → 输入问题 → AI 自动完成「找表 → 看结构 → 写 SQL → 查库 → 分析回答」。全程肉眼可见地调用工具。

方式二：接入 Claude Desktop（展示 MCP 通用性）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "db-connector": {
      "command": "/Users/wjy/.workbuddy/binaries/node/versions/22.22.2/bin/node",
      "args": ["--import", "tsx", "/Users/wjy/Documents/code/apps/mcp-demo-server/src/server.ts"]
    }
  }
}

重启后直接问：「帮我分析订单数据，哪个城市销售额最高？」（推荐先用 npm run build 编译成 dist 再用 node 跑，避免依赖 tsx）

演示问题清单

• 「按城市统计销售额排名，哪个城市卖得最好？」
• 「最近 30 天销售额和订单量是多少？环比上月增长多少？」
• 「哪个商品是爆款？哪个商品卖不动？」
• 「帮我查出买得最多的 3 个客户」

架构

AI 客户端 (DeepSeek Agent / Claude Desktop / Cursor)
        │  MCP 标准协议
        ▼
  db-connector (本仓库)
  ├── list_tables      → 自动发现数据结构
  ├── describe_table   → 查看表结构
  └── query            → 只读 SQL 查询（安全拦截非 SELECT）
        │
        ▼
  SQLite (demo.db) / PostgreSQL (生产)

to B 安全卖点（客户最关心）：

能力	实现
只读防护	非 SELECT/EXPLAIN/WITH 语句一律拦截（src/db.ts）
结果限额	默认 20 行、最多 100 行，防拖库
模型自由	DeepSeek / 任意 OpenAI 兼容模型，不绑定 Claude 订阅
协议标准	MCP 官方协议，所有 AI 客户端通用
图表看板	Web 演示界面自动把查询结果渲染成柱状图（src/agent.ts 提取 + public/index.html）
数据不出内网	支持本地模型（ollama/llama.cpp），模型与数据都在客户内网；演示界面含卖点徽章

部署（公开体验站）

把 demo 变成任何人打开就能试问的线上站点（获客入口 + 信任证明 + 渠道商工具）：

# 1. 配模型 key（部署必需，页面要真实问答）
cp .env.example .env    # 填 DEEPSEEK_API_KEY（DeepSeek 官网充值，很便宜）

# 2. 登录并部署到 Vercel
npx vercel login
npx vercel --prod

# 3. 打开 https://<project>.vercel.app 即可体验

部署架构（无原生依赖，一次改造到处可跑）：

组件	方案
数据库	sql.js（WASM），演示库 52KB 已 base64 内嵌 src/demo-data.ts，无文件依赖
后端	api/index.ts（Vercel serverless）+ vercel.json（rewrites 全路由转发）
流式	SSE 直推（handleRequest 同时兼容 Node http 与 serverless）
模型	DeepSeek / 任意 OpenAI 兼容（.env 配置），无 key 时返回明确错误

本地开发不受影响：npm run web 仍是常驻 http 服务。

生产扩展（接单后按客户需求加）

• 认证与权限：按客户/角色限制可访问的表（白名单）
• 操作日志：记录 AI 执行的每条 SQL（审计）
• 只读账号：接数据库只读副本，从源头杜绝写操作
• 更多工具：除数据库外可接 ERP/CRM API、内部知识库、审批流

目录结构

src/
├── db.ts        # 数据库适配(sql.js WASM) + 只读防护
├── demo-data.ts # 演示库 base64 内嵌(消除部署文件依赖)
├── server.ts    # MCP Server（stdio 模式 + setupServer 复用）
├── agent.ts     # DeepSeek Agent（自然语言 → MCP 工具 → 回答，含图表数据提取）
├── cli.ts       # 命令行问答入口
├── seed.ts      # 生成演示数据库（better-sqlite3）
├── smoke.ts     # 冒烟测试（不依赖 API key）
├── web.ts       # Web 演示服务（SSE + 图表透传，handleRequest 可部署）
└── public/      # 客户演示界面（聊天 + 步骤可视化 + 柱状图 + 安全徽章 + wasm）
api/             # Vercel serverless 入口
vercel.json      # 部署路由配置

常见问题

Q: AI 会不会乱改数据？ 不会。服务端强制只读：非查询类 SQL 直接拦截报错；生产再加只读账号双保险。

Q: 必须用 DeepSeek 吗？ 不用。改 .env 里的 DEEPSEEK_BASE_URL / DEEPSEEK_MODEL 就能换任意 OpenAI 兼容模型（通义/豆包/GPT 等）。