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关键设计决策
- 可变解析上下文 -提取器修改共享上下文而不是返回值
- 有序提取器管道 头球→ 变量→ 动态结构化查询语言→ CTEs
- 优雅降级 -如果主管道发生故障，则回退解析器
- ES 模块 -用途
import.meta.url为了__dirname兼容性 - 基于正则表达式的解析 -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)/gi3. .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获取最新的库文档