AI导哈

文本转SQL工具

一个具有安全防护、日志记录、下载功能和LLM集成测试的只读SQL Server MCP服务器。

  • by AmiSharabi
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 AmiSharabi/mcp_text2sql

使用说明

# MCP Text2SQL PoC（本地+云）

只读SQL Server MCP服务器，带有护栏、日志记录、下载和LLM集成测试。

MCP工具

  • list_databases
  • get_schema
  • execute_readonly_sql
  • explain_reasoning
  • preview_table
  • download_result
    • download_mode=link （默认）：将CSV保存在服务器上，返回URL
    • download_mode=base64：以base64内联返回CSV内容
  • build_chart
  • build_dashboard

大多数SQL工具接受可选 database 从中选择数据库配置文件 list_databases.

主要终点

  • POST /mcp
  • GET /sse
  • POST /messages?session_id=<id>
  • POST /tools/get_schema
  • POST /tools/list_databases
  • POST /tools/execute_readonly_sql
  • POST /tools/explain_reasoning
  • POST /tools/preview_table
  • POST /tools/download_result
  • POST /tools/build_chart
  • POST /tools/build_dashboard
  • GET /downloads/<file_name>.csv

设置

  1. python -m venv venv
  2. venv\\Scripts\\python.exe -m pip install -r requirements.txt
  3. 复制 .env.example 到 .env 并填充值。
    • 单个数据库：设置 DB_*
    • 多数据库：设置 DB_CATALOG_PATH 到现有的JSON文件（请参见 db_catalog.example.json)
  4. 运行服务器： venv\\Scripts\\python.exe mcp_server.py

云访问

云模型无法调用 127.0.0.1 直接。

  • 使用HTTPS隧道暴露本地服务器（示例： ngrok http 8000)
  • 对于基于SSE的MCP连接器，请使用 https://<public-host>/sse 作为MCP服务器URL
  • 集 MCP_PUBLIC_BASE_URL 如果你想要绝对下载链接
  • 配置 x-api-key 在连接器中

项目文件

  • mcp_server.py
    • 薄兼容性入口点
    • 再出口 app 和 SSE_SESSIONS
    • 通过运行服务器 main()
  • src/mcp_app.py
    • FastAPI应用+所有HTTP/SSE路由
    • 山丘 /downloads/*
  • src/mcp_runtime.py
    • MCP JSON-RPC处理程序(initialize, tools/list, tools/call等等）
    • API密钥身份验证、跟踪/日志助手、SSE会话存储
  • src/mcp_models.py
    • Pydantic请求模型 /tools/*
  • src/tools.py
    • 工具实现：
      • list_databases
      • get_schema
      • execute_readonly_sql
      • explain_reasoning
      • preview_table
      • download_result （只读SQL->CSV）
      • build_chart
      • build_dashboard
  • src/guard.py
    • SQL安全规则：
      • 仅限单一声明
      • 仅选择
      • denylist危险代币
      • 块 SELECT INTO
      • 强制执行 TOP (SQL_MAX_ROWS)
      • 限制复杂性 SQL_MAX_TABLES
  • src/db_connection.py
    • SQLAlchemy+SQL Server连接层
    • 支持来自的传统单个数据库 .env 以及模块化多数据库 DB_CATALOG_PATH
  • db_catalog.example.json
    • 具有共享凭据和每个数据库名称的多数据库目录示例
  • src/logger.py
    • 事件记录接收器(file / sql / both)
    • SQL接收器写入SQL Server表（默认目标： mcp_logging.events)
    • 截断/清理字段（包括 user_prompt)
  • logs/sql/001_create_mcp_logging.sql
    • 用于在可观察性数据库中创建日志模式/表/索引/视图的SQL Server脚本
  • logs/sql/002_mcp_logging_analysis_queries.sql
    • 准备运行SQL查询以进行跟踪/会话/错误/性能分析
  • logs/sql/000_create_mcp_observability_db.sql
    • 创建专用的可观察性数据库(McpObservability 默认情况下）
  • logs/sql/003_mcp_logging_security_and_retention.sql
    • 创建最低权限角色/用户和保留过程
  • mcp_tools.json
    • MCP工具定义由返回 tools/list
  • logs/export_logs_csv.py
    • 出口 logs/events.jsonl 转换为CSV
    • 还导出列指南（CSV+XLSX）
    • 回填物缺失 user_prompt 通过 trace_id
  • logs/events.jsonl
    • 运行时事件日志（原始源）
  • logs/downloads/
    • CSV文件由创建 download_result 在 link 模式

日志和导出

  • JSONL运行时日志（原始）： logs/events.jsonl
  • SQL日志接收器：
    • 建议的安装顺序：
      1. 跑 logs/sql/000_create_mcp_observability_db.sql
      2. 跑 logs/sql/001_create_mcp_logging.sql
      3. 跑 logs/sql/003_mcp_logging_security_and_retention.sql
    • 脚本默认为数据库名称 McpObservability （编辑 USE [...] 如果您选择其他名称）
    • 如果你没有 CREATE DATABASE 权限，请DBA预先创建 McpObservability 然后从步骤2开始
    • 使用专用数据库+专用登录记录写入（最低权限）
    • 集 .env:
      • LOG_SINK=sql （仅限SQL）或 LOG_SINK=both （SQL+jsonl）
      • 通过设置专用SQL日志连接 LOG_DB_* （推荐）
        • LOG_DB_HOST, LOG_DB_PORT, LOG_DB_NAME
        • LOG_DB_USER, LOG_DB_PASSWORD
        • LOG_DB_DRIVER, LOG_DB_ENCRYPT, LOG_DB_TRUST_SERVER_CERTIFICATE
        • 最低建议值：
          • LOG_DB_NAME=McpObservability
          • LOG_DB_USER=<logging_writer_user>
          • LOG_DB_PASSWORD=<logging_writer_password>
      • LOG_DB_* 行为：
        • 仅在以下情况下使用 LOG_SINK 是 sql 或 both
        • 按字段回退：如果 LOG_DB_* 缺失/为空，记录器恢复匹配 DB_*
        • 回退是针对每个变量的（不是全部或全无），因此是部分的 LOG_DB_* 配置有效
        • 如果 LOG_DB_HOST 是基于实例的（例如： AMI02\\SQLEXPRESS), LOG_DB_PORT 被忽略
      • 默认表目标： LOG_DB_SCHEMA=mcp_logging, LOG_DB_TABLE=events
    • 保留：
      • 计划执行SQL代理作业：
        • EXEC mcp_logging.usp_purge_events_older_than_days @retention_days = 90, @batch_size = 5000;
    • 如果SQL插入失败，记录器将回退JSONL写入 LOG_SQL_FALLBACK_PATH
  • 导出日志时使用：
    • venv\\Scripts\\python.exe logs/export_logs_csv.py
  • 可选的自定义输出路径：
    • --input logs/events.jsonl
    • --output logs/events.csv
    • --columns-guide-output logs/events_columns_guide.csv
    • --columns-guide-xlsx-output logs/events_columns_guide.xlsx
  • 导出行为：
    • 做 不 修改原始 logs/events.jsonl
    • 仅写入新的导出文件
    • 如果目标文件被锁定，则创建一个新的文件名，如下所示 *_new1.csv

备注

  • 要跨工具事件捕获原始激活提示，请传递 user_prompt （或 x-user-prompt 标题为 /mcp).

相关 MCP