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获取最新的库文档