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=
• 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/.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)

1. 运行服务器： venv\\Scripts\\python.exe mcp_server.py

云访问

云模型无法调用 127.0.0.1 直接。

• 使用HTTPS隧道暴露本地服务器（示例： ngrok http 8000)
• 对于基于SSE的MCP连接器，请使用 `https://

/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 1. 跑 logs/sql/001_create_mcp_logging.sql 1. 跑 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= - LOG_DB_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).