AI导哈

数据库对话接口

Pocket DBA MCP Server 是一个通过自然语言对话实现数据库查询和分析的工具，为业务用户提供实时数据洞察，无需SQL知识。

  • by vyente-ruffin
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 david-ruffin/MCP-MSSQL-SERVER

使用说明

Pocket DBA MCP服务器-“DBA在你的口袋里”

项目愿景

通过创建取代传统静态BI工作流程的对话界面，改变企业主与数据的交互方式。企业主无需向DBA请求报告并等待Power Platform可视化，而是可以与他们的数据库进行实时对话并获得即时见解。

当前状态： 企业主→ 问题→ DBA → SQL查询→ Power Platform→ 静态报告→ 有限跟进

目标州： 企业主→ 对话式AI→ 动态查询→ 即时洞察→ 无限制随访

当前实施状态

✅ 第一阶段完成：带FastMCP的核心MCP服务器

  • 使用stdio传输的FastMCP服务器实现
  • 具有安全验证的只读SQL Server访问
  • 基本工具： execute_sql 具有查询验证功能
  • 资源： list_tables 和 get_table_data
  • 综合测试套件（9项测试通过）
  • 与Claude Desktop经过验证的集成

✅ 第二阶段完成：增强的数据库发现

  • describe_table 模式检查工具
  • get_relationships 外键发现工具
  • TDD方法的全面测试覆盖率

✅ 第3阶段完成：Gradio聊天界面（第4阶段）

  • 丰富的HTML/图表渲染功能
  • 导出文件下载支持
  • 多格式响应处理
  • 增强的可视化功能

✅ 第4阶段完成：现代UI设计

  • 基于design.json的ChatGPT/Claude风格接口
  • 具有ARIA可访问性的语义HTML5
  • 响应式设计（手机/平板电脑/台式机）
  • 玻璃造型效果与现代造型
  • 60个全面的UI测试（全部通过）

✅ 第5阶段完成：后端集成

  • 同时为UI和API端点提供服务的FastAPI服务器
  • 面向现代web界面的静态文件服务
  • 完成API与前端的集成
  • 15项集成测试（全部通过）
  • 已准备好进行Azure容器部署

✅ 第6阶段完成：真实数据库集成

  • 将FastAPI连接到实际的MCP服务器端点
  • 通过web UI实时执行SQL查询
  • 动态数据库结构发现（无硬编码假设）
  • 带环境变量的API成本管理
  • 12个web UI MCP集成测试（全部通过）

✅ 第7阶段完成：综合测试

  • Playwright MCP服务器浏览器测试与可视化UI
  • 所有功能均已验证：SQL查询、表描述、错误处理
  • 响应式设计测试（移动设备/平板电脑/台式机）
  • 通过HTTP请求验证API端点
  • 10个Playwright浏览器自动化测试（全部通过）

❌ 已识别关键错误：Web应用程序使用假MCP客户端

  • 当前的web应用程序直接导入MCP功能，而不是使用FastMCP客户端
  • 违反记录的架构：应使用FastMCP客户端→ MCP服务器
  • 必须重新构建才能使用正确的FastMCP客户端连接
  • 目前已损坏：未遵循记录的FastMCP方法

特性

当前能力

  • 只读数据库访问：以零写入权限完全查看SQL Server数据库
  • 安全第一设计：高级SQL注入预防和查询验证
  • FastMCP实施：使用装饰器简化语法，实现快速开发
  • 架构发现：列出所有数据库表及其结构
  • 查询执行：安全执行已验证的SELECT语句
  • 错误处理：妥善处理格式错误的查询和连接问题

建筑

当前实施（基于Web）：

Business Owner → Modern Web UI → FastAPI Backend → MCP Server → SQL Server

传统实现（Claude Desktop）：

Business Owner → Claude Desktop → FastMCP Client → pocket-dba-mcp-server → SQL Server

安装和设置

先决条件

  • Python 3.12+
  • 用于SQL Server的Microsoft ODBC驱动程序18
  • SQL Server数据库访问

快速入门（Web界面）

git clone https://github.com/david-ruffin/pocket-dba-mcp-server.git
cd pocket-dba-mcp-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run the modern web interface
python main.py --port=8002
# Visit http://localhost:8002 for the UI

# For network access from other machines on same VNET:
# Replace localhost with your machine's IP address
# Example: http://192.168.1.100:8002 or http://10.0.0.50:8002

替代方案：传统Claude桌面集成

# For Claude Desktop MCP integration
python src/mssql/server.py

配置

创建一个 .env 文件：

# Database Configuration
MSSQL_SERVER=your_server
MSSQL_DATABASE=your_database  
MSSQL_USER=your_username
MSSQL_PASSWORD=your_password
MSSQL_DRIVER={ODBC Driver 18 for SQL Server}

# Claude API Configuration (Phase 6+)
CLAUDE_API_KEY=your_claude_api_key
CLAUDE_MODEL=claude-3-haiku-20240307
ENABLE_CLAUDE_API=false

Claude桌面集成

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pocket-dba": {
      "command": "/path/to/pocket-dba-mcp-server/venv/bin/python",
      "args": ["/path/to/pocket-dba-mcp-server/src/mssql/server.py"],
      "env": {
        "MSSQL_SERVER": "your_server",
        "MSSQL_DATABASE": "your_database",
        "MSSQL_USER": "your_username", 
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DRIVER": "{ODBC Driver 18 for SQL Server}"
      }
    }
  }
}

项目结构

pocket-dba-mcp-server/
├── main.py               # FastAPI web server (primary entry point)
├── src/mssql/
│   ├── server.py         # FastMCP server implementation
│   └── server_old.py     # Legacy standard MCP version
├── ui/                   # Modern web interface
│   ├── index.html        # Main UI file
│   ├── styles/           # CSS design system
│   │   ├── design-system.css
│   │   ├── components.css
│   │   └── responsive.css
│   ├── js/               # Vanilla JavaScript
│   │   ├── app.js
│   │   ├── api.js
│   │   └── components.js
│   └── tests/            # UI test suite (60 tests)
│       ├── test_components.py
│       ├── test_layout.py
│       ├── test_theme.py
│       └── test_accessibility.py
├── tests/                # Backend test suites
│   ├── test_server.py    # MCP server tests
│   ├── test_fastapi_integration.py  # API integration tests
│   └── test_*.py         # Additional test files
├── chat_app.py           # Legacy Gradio interface
├── design.json           # UI design system specifications
├── CLAUDE.md             # Development instructions
├── requirements.txt      # Python dependencies
├── roadmap.md           # Project roadmap
└── README.md            # This file

当前工具和资源

MCP工具（后端）

  • execute_sql：执行带有验证的只读SELECT查询
  • describe_table：获取表架构（列、类型、约束）
  • get_relationships：发现外键关系

资源

  • mssql://tables：列出所有数据库表
  • mssql://table/{table_name}：获取表数据（前100行）

Web API终结点

  • GET /：提供现代web UI
  • GET /api/health：健康检查
  • POST /api/connect：数据库连接
  • POST /api/chat：用于数据库查询的聊天界面
  • GET /api/conversations：对话历史
  • 静态文件服务：CSS、JavaScript和资源

发展路线图

第一阶段：核心服务器✅ 完成

  • [x] 设置Python 3.12虚拟环境
  • [x] 使用stdio传输实现FastMCP服务器
  • [x] 创建带有安全验证的execute_sql工具
  • [x] 添加表列表和数据资源
  • [x] 全面的测试套件
  • [x] Claude Desktop集成已验证

第2阶段：增强型数据库发现

  • []实施 describe_table 模式检查工具
  • []添加 get_relationships 外键发现工具
  • []创建表元数据资源（列、类型、约束）
  • []添加索引信息以优化查询
  • []实施连接池以提高效率

第3阶段：高级查询功能

  • []添加查询复杂性分析和超时限制
  • []实施性能结果集大小限制
  • []为合规性创建审计跟踪日志记录
  • []添加查询优化建议
  • []支持WITH条款和CTE

第4阶段：客户端界面开发✅ 完成

  • [x] 构建Gradio聊天界面
  • [x] 使用消息路由实现MCP客户端
  • [x] 为对话上下文创建会话管理器
  • [x] 为数据可视化添加结果渲染器
  • [x] 测试端到端对话流
  • [x] 新：具有ChatGPT风格界面的现代web UI
  • [x] 新：FastAPI后端集成
  • [x] 新：响应式设计，便于使用

第5阶段：商业智能功能

  • []多表分析功能
  • []时间序列分析和趋势识别
  • []客户行为跟踪的队列分析
  • []数据分割和模式发现
  • []基于历史数据的基本预测

第6阶段：生产准备

  • []性能优化和监控
  • []增强的错误处理和恢复
  • []数据导出功能
  • []与现有BI工具集成
  • []多数据库支持

业务用例

主要场景

  1. 探索性分析：“显示过去6个月的销售趋势”
  2. 相关性发现：“找到客户行为中有趣的模式”
  3. 特别报告：“比较各地区的绩效”
  4. 数据验证：“是否有任何我应该知道的数据质量问题？”
  5. 战略洞察力：“哪些因素对客户保留率影响最大？”

先进能力（未来）

  • 多表分析：Claude自动连接相关表
  • 时间序列分析：识别趋势、季节性和异常情况
  • 分割：识别不同的客户或产品组
  • 预测：基于历史数据的预测性见解

安全与安保

数据保护

  • 只读访问：无INSERT、UPDATE、DELETE或DDL操作
  • 查询验证：服务器在执行之前验证所有查询
  • SQL注入防护：先进的模式检测和阻断
  • 连接安全性：安全的凭据管理
  • 错误处理：操作优雅，无数据泄露

访问控制

  • 认证：安全管理数据库凭据
  • 授权：尊重现有数据库权限
  • 审计跟踪：记录所有合规和监控查询

测试

运行综合测试套件：

source venv/bin/activate
python -m pytest tests/ -v

当前测试覆盖率：

  • 数据库连接验证
  • 查询安全验证（9种不同的攻击模式）
  • 使用有效/无效查询执行SQL
  • 资源列表和数据检索
  • 处理格式错误的请求时出错

性能注意事项

当前限制

  • 查询超时：默认30秒
  • 结果集：表数据的前100行
  • 只读操作
  • 每个请求一个连接

计划优化

  • 连接池提高效率
  • 查询复杂性分析
  • 资源使用监控
  • 缓存频繁访问的元数据

用户体验目标

面向企业主

  • 直接性：在几秒钟内得到答案，而不是几天
  • 无障碍：不需要SQL知识
  • 对话式：自然后续问题
  • 全面的：访问所有业务数据
  • 深谋远虑：AI建议进行相关分析

技术团队

  • 安全：对生产数据没有风险
  • 合规：数据访问的完整审计跟踪
  • 演出：不影响操作的优化查询
  • 可维护性：简单、干净的代码库

当前状态：生产准备就绪

完成内容：

  • ✅ 采用ChatGPT风格设计的现代web界面
  • ✅ 同时为UI和API提供服务的FastAPI后端
  • ✅ 使用数据库工具完成MCP服务器
  • ✅ 综合测试套件（75+测试通过）
  • ✅ 所有设备的响应式设计
  • ✅ 无障碍合规性（WCAG）
  • ✅ 已准备好进行Azure容器部署

如何使用：

  1. 在中配置数据库 .env 文件
  2. 跑 python main.py
  3. 访问http://localhost:8000
  4. 开始和你的数据库聊天吧！

预期成果

一个生产就绪的web应用程序，展示了会话式人工智能如何使数据访问民主化，使企业主能够独立探索他们的数据，同时保持安全性和准确性。该系统感觉就像有一名高级数据分析师全天候处理任何业务问题。

未来法学硕士：发展背景

当前实施方法：

  • 建筑：为web UI和API端点提供服务的单个FastAPI服务器
  • 前端：遵循design.json规范的普通HTML/CSS/JavaScript（无框架）
  • 后端：具有静态文件服务的FastAPI，与现有的MCP服务器集成
  • 测试：全面的TDD方法，在UI和后端进行了75次以上的测试
  • 部署目标：Azure容器（单容器架构）

开发关键文件：

  • main.py：主FastAPI服务器（入口点）
  • ui/index.html：主web界面
  • ui/js/app.js：前端应用程序逻辑
  • src/mssql/server.py：MCP服务器实现
  • tests/test_fastapi_integration.py：后端集成测试
  • ui/tests/：前端测试套件（60个测试）
  • design.json：UI设计系统规范
  • CLAUDE.md：开发说明和最佳做法

发展理念：

  • TDD方法论（先写测试）
  • 无过度设计（简单、专注的解决方案）
  • 具有可访问性的现代网络标准
  • Azure就绪容器部署
  • LLM交接的综合文件

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 为您的更改编写测试
  4. 确保所有测试通过(python -m pytest tests/ -v)
  5. 提交您的更改(git commit -m 'Add some amazing feature')
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

依赖项

fastmcp>=2.8.1
pyodbc>=4.0.35
python-dotenv>=1.0.1
gradio>=5.0.0
anthropic>=0.40.0
fastapi>=0.104.0
uvicorn>=0.24.0

发展的下一步

第6阶段：真正的数据库集成✅ 完成

  • ✅ 使用可配置模型实施Claude API成本管理
  • ✅ 将FastAPI端点连接到真实的MCP服务器调用
  • ✅ 用实际数据库查询替换模拟API响应
  • ✅ 验证真实数据库场景是否端到端工作
  • ✅ 全部23项集成测试通过
  • ✅ MCP服务器成功分析数据库结构

第7阶段：商业智能层（当前）

  • 实现自然语言到SQL的转换
  • 增加业务背景理解（客户、产品、销售）
  • 为后续问题创建对话记忆
  • 添加积极的见解和建议
  • 使用Sarah角色对真实业务场景进行测试

成本管理策略：

  • 默认：用于测试的Mock Claude API（零成本）
  • 开发：用于模型选择和API启用/禁用的环境变量
  • 测试：最低成本的Claude Haiku模型（每M代币0.25美元/1.25美元）
  • 生产：可配置的型号选择（Sonnet/Opus质量）

第8阶段：Azure部署（未来）

  • 用于Azure部署的Docker容器化
  • 环境特定配置
  • 生产安全强化

未来的增强功能：

  • 高级可视化功能
  • 导出功能
  • 多数据库支持
  • 高级分析功能

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

“通过对话式人工智能实现数据访问的民主化”

项目状态：生产就绪Web界面✅

相关 MCP