AI导哈

T-SQL语义分析服务

一款用于T-SQL存储过程的智能语义搜索与分析工具，采用混合搜索技术（BM25 + 向量嵌入），可作为MCP服务器与AI助手集成，适用于数据库开发与优化场景。

  • by johnhnguyen97
  • C
  • 本地部署
  • 更新于
在 GitHub 查看 johnhnguyen97/sql-context

使用说明

SQL上下文：语义T-SQL分析和MCP服务器

使用混合搜索（BM25+向量嵌入）对T-SQL存储过程进行智能语义搜索和分析。作为模型上下文协议（MCP）服务器构建，用于AI助手集成。

🎯 项目目标

仅返回相关上下文，不返回整个过程 -灵感来自mem0ai通过选择性检索实现的“90%的低令牌使用率”。每个查询返回元数据+前5个最相关的块。

✨ 特性

目前正在工作

  • ✅ T-SQL解析器 -提取过程元数据（名称、参数、变量）
  • ✅ 表参考检测 -标识使用的所有表
  • ✅ 链接服务器检测 -查找OPENQUERY调用
  • ✅ 复杂度指标 -行数、变量计数、复杂性评分
  • ✅ 分类变量 -按UTC、日期/时间、动态SQL、格式分组
  • ✅ 综合分析报告 -带有粉笔格式的漂亮CLI输出

进行中（已修复但正在测试）

  • 🔧 动态SQL提取 -重建@SQL变量（修复了无限循环错误）
  • 🔧 CTE提取 -解析常用表表达式
  • 🔧 模板占位符检测 -查找 /*__PLACEHOLDER__*/ 模式

计划中的增强功能

  • 📋 控制流分析 -IF/ELS、WHILE、开始/结束嵌套深度
  • 📋 错误处理检测 -TRY/CATCH块，升降机
  • 📋 交易分析 -开始传输、提交、回滚跟踪
  • 📋 性能反模式 -SELECT*，N+1个查询，缺少WHERE
  • 📋 安全漏洞检测 -SQL注入风险
  • 📋 数据流可视化 -美人鱼图（输入→ 处理→ 输出）
  • 📋 代码质量评分 -圈复杂度、可维护性指数

🚀 快速开始

安装

npm install
npm run build

运行分析

node dist/test/analyze-procedure.js

这将分析 Stored_Procedure_Test.sql 并生成一份综合报告，显示：

  • 程序目的执行摘要
  • 带类型和默认值的输入参数
  • 声明变量（按函数分类）
  • 数据源（表、链接服务器）
  • 特殊逻辑（UTC转换、移位感知过滤）
  • 复杂性度量

📊 输出示例

╔════════════════════════════════════════════════════════════════════════════════╗
║                               Executive Summary                                ║
╚════════════════════════════════════════════════════════════════════════════════╝

This stored procedure, [SSRS_Item_Status_Ver5], is a complex reporting query designed
to aggregate item status and production metrics from two primary data sources: a local
SQL Server database and a linked Apriso server (MES).

╔════════════════════════════════════════════════════════════════════════════════╗
║                                Input Parameters                                ║
╚════════════════════════════════════════════════════════════════════════════════╝
  • SubjectDate: DATETIME
  • Available_item: BIT
  • FromTime: TIME (Default: NULL)
  • ToTime: TIME (Default: NULL)
  • GetTimeList: BIT (Default: 0)

🏗️ 建筑

解析器管道

SQL File → Parser → Extractors → Structured Data → Analysis
                      ├─ Procedure Header Extractor
                      ├─ Variable Extractor
                      ├─ Dynamic SQL Extractor
                      └─ CTE Extractor

关键设计决策

  1. 可变解析上下文 -提取器修改共享上下文而不是返回值
  2. 有序提取器管道 头球→ 变量→ 动态结构化查询语言→ CTEs
  3. 优雅降级 -如果主管道发生故障，则回退解析器
  4. ES 模块 -用途 import.meta.url 为了 __dirname 兼容性
  5. 基于正则表达式的解析 -Node.js没有成熟的T-SQL AST解析器

🐛 此会话中修复的错误

1. __dirname is not defined 错误

问题：ES模块不提供 __dirname 全球的 修复：添加了ES模块模式：

import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

2.解析器返回“未知”过程名称

问题: PROCEDURE_HEADER_PATTERN 只有1个捕获组，但访问了代码 match[2] 和 match[3] 修复：更新了模式，分别捕获全名、过程名称和参数：

/(?:CREATE|ALTER)\s+PROCEDURE\s+((?:\[?[^\]]+\]?\.)?(\[?[^\s\]]+\]?))([\s\S]*?)(?=AS\s+BEGIN|AS\s*\n\s*BEGIN)/gi

3. .match() 对比 .exec() 使用全局正则表达式

问题：使用 .match() 随着 /gi flag只返回完整匹配项，不返回捕获组 修复：更改为 .exec() 随着 lastIndex 重置：

PROCEDURE_HEADER_PATTERN.lastIndex = 0;
const headerMatch = PROCEDURE_HEADER_PATTERN.exec(sql);

4.动态SQL提取器无限循环

问题：捕获的变量名没有 @ 前缀，导致正则表达式不匹配和无限循环 修复：已添加 @ 存储变量名时使用前缀：

declaredVariables.add('@' + match[1]);

📂 项目结构

sql-context/
├── src/
│   ├── parser/
│   │   ├── patterns.ts              # Regex patterns for T-SQL elements
│   │   ├── tsql-parser.ts           # Main parser orchestrator
│   │   ├── chunker.ts               # Semantic chunking logic
│   │   └── extractors/
│   │       ├── procedure-header.ts  # Extract name & parameters
│   │       ├── variable-extractor.ts # Extract DECLARE statements
│   │       ├── dynamic-sql-extractor.ts # Extract @SQL variables
│   │       └── cte-extractor.ts     # Extract CTEs
│   ├── types/
│   │   └── index.ts                 # TypeScript type definitions
│   ├── embeddings/                  # Vector embedding generation
│   ├── storage/                     # SQLite database layer
│   ├── search/                      # Hybrid search (BM25 + vector)
│   └── tools/                       # MCP tool implementations
├── test/
│   └── analyze-procedure.ts         # Comprehensive analysis script
├── Stored_Procedure_Test.sql        # Example 914-line procedure
├── package.json
├── tsconfig.json
└── README.md

🔧 技术栈

  • TypeScript -ES2022，严格模式，Node16模块分辨率
  • ES 模块 - "type": "module" 在package.json中
  • SQLite -better-sqlite3（同步API）
  • 嵌入 -@xenova/变压器（全MiniLM-L6-v2，384调光）
  • 搜索 -BM25的FTS5，矢量的JavaScript余弦相似性
  • 主控程序 -人工智能辅助集成的模型上下文协议
  • 格式化 -粉笔用于漂亮的CLI输出

📝 配置

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "Node16",
    "rootDir": ".",
    "outDir": "./dist",
    "strict": true
  }
}

🧪 测试

这 analyze-procedure.ts 脚本提供全面的测试：

npm run build
node dist/test/analyze-procedure.js

对解析器进行测试 Stored_Procedure_Test.sql -一个真正的914行程序，包括：

  • 5个输入参数
  • 35+声明变量
  • 8个动态SQL变量（@SQL01-@SQL05、@SQL11-12、@SQL15）
  • 多个CTE
  • 用于链接服务器访问的OPENQUERY
  • UTC时区转换逻辑
  • 轮班感知时间过滤（跨午夜轮班）

🎨 功能路线图

第1阶段：核心解析（完成✅)

  • [x] 程序头提取
  • [x] 参数解析
  • [x] 变量提取
  • [x] 表参考检测
  • [x] OPENQUERY检测

第二阶段：高级提取（进行中🔧)

  • [x] 动态SQL重建（固定）
  • []CTE提取（已实施，需要测试）
  • []模板占位符检测
  • []控制流分析
  • []错误处理检测

第3阶段：分析和洞察（计划📋)

  • []性能反模式检测
  • []安全漏洞扫描
  • []代码质量度量
  • []依赖关系图可视化
  • []重构建议

第4阶段：MCP服务器集成（计划中📋)

  • [ ] index_sql_files 工具
  • [ ] search_procedures 工具
  • [ ] get_procedure 工具
  • [ ] analyze_dependencies 工具
  • [ ] refresh_index 工具

📚 文档

  • CLAUDE.md -人工智能助手项目指南
  • ARCHITECTURE.md -技术实施细节（计划）
  • MEM0-INSIGHTS.md -mem0ai研究的设计决策（计划中）

🤝 贡献

该项目是通过人工智能辅助的Claude Code和Sage MCP配对编程开发的，使用：

  • Gemini CLI -解析器和分块器实现
  • Claude CLI -嵌入和搜索系统
  • 调试工作流 -系统性故障排除

📄 许可证

麻省理工学院

🙏 致谢

  • 受mem0ai选择性检索方法的启发
  • 采用Sage MCP构建，用于多模型编排
  • 使用Context7获取最新的库文档

相关 MCP