Oracle和MySQL商业智能MCP服务器

基于人工智能的SQL业务逻辑分析，具有智能缓存功能，可实现即时洞察

![License: MIT](https://opensource.org/licenses/MIT) ![Database: Oracle](https://www.oracle.com/database/) ![Database: MySQL](https://www.mysql.com/) ![MCP: Protocol](https://modelcontextprotocol.io/)

______________________________________________________________________

🎯 它做什么

使用人工智能分析将复杂的SQL查询转化为清晰的业务见解。此MCP服务器自动发现表关系，推断业务逻辑，并解释您的查询实际做了什么——非常适合入职、文档和理解遗留系统。

主要特点

🧠 AI业务逻辑解释 -用简明英语理解查询目的
🔗 自动关系发现 -跟随外键，深度可达N级
⚡ PostgreSQL智能缓存 -后续查询速度提高93%（0.7秒对10秒）
📊 ER图生成 -表关系的可视化美人鱼图
🎯 实体和域分类 -从表/列名推断业务上下文
📈 性能分析 -通过执行计划分析进行深度SQL优化
🔒 多层安全 -执行前阻止危险操作
🐬 MySQL+Oracle支持 -对两个数据库引擎的原生支持
⚡ ✨ 新增：分析深度模式 -仅快速计划（0.3秒）或完全优化（2025年1月）
🎯 ✨ 新：智能代币优化 -减少80%，产量最小化（2025年1月）
📏 ✨ 新功能：自动预设调整 -智能处理大型查询（2025年1月）

______________________________________________________________________

🚀 快速开始

自动部署（推荐）

git clone https://github.com/aviciot/mcp_db_performance.git
cd mcp_db_peformance

# Edit configuration files
cp server/config/settings.template.yaml server/config/settings.yaml
# Edit settings.yaml with your database credentials

# Run automated deployment script
chmod +x deploy.sh
./deploy.sh

这 deploy.sh 脚本将：

✅ 检查Docker是否正在运行
✅ 创建所需的Docker网络
✅ 部署PostgreSQL缓存数据库
✅ 部署MCP服务器
✅ 初始化数据库架构
✅ 运行健康检查

手动部署

# 1. Start PostgreSQL cache database
cd ../pg_mcp
docker-compose up -d

# 2. Start MCP server
cd ../mcp_db_peformance
docker-compose up -d

# 3. Initialize schema (one-time)
docker exec mcp_db_performance python test-scripts/run_complete_init.py

3.连接克劳德桌面

添加到您的Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "database-performance": {
      "command": "docker",
      "args": ["exec", "-i", "mcp_db_performance", "python", "-m", "mcp_app"],
      "env": {}
    }
  }
}

重新启动Claude Desktop并开始询问有关SQL的问题！

______________________________________________________________________

💡 示例用例

业务逻辑解释

User: "Explain what this query does:

SELECT t.payment_id, t.amount, r.retry_count, c.challenge_status
FROM gateway_transactions t
LEFT JOIN gtw_trans_retry r ON t.payment_id = r.payment_id
LEFT JOIN gtw_trans_3ds_challenge c ON t.payment_id = c.payment_id
WHERE t.processing_date = '2024-01-01'"

Response:
📊 Business Purpose: Payment transaction processing with retry tracking and 3DS authentication

📦 Tables Analyzed:
• GATEWAY_TRANSACTIONS (45M rows) - Main payment processing table
• GTW_TRANS_RETRY (2.3M rows) - Retry attempt tracking
• GTW_TRANS_3DS_CHALLENGE (1.8M rows) - 3D Secure authentication

🔗 Relationships:
• GTW_TRANS_RETRY → GATEWAY_TRANSACTIONS (FK: payment_id)
• GTW_TRANS_3DS_CHALLENGE → GATEWAY_TRANSACTIONS (FK: payment_id)

🎯 Domain: Payment Processing | Entity: Transaction
⚡ Performance: 742ms (cached)

性能分析

User: "Why is this query slow?

SELECT * FROM orders WHERE customer_id = 12345"

Response:
🚨 CRITICAL Performance Issue Detected

Problem: Full table scan on ORDERS table (45M rows)
Cost: 8,234 | Estimated Time: 45+ seconds

Root Cause:
• 3 indexes exist but not being used
• Likely causes: Implicit type conversion, function on column

Recommendation:
CREATE INDEX idx_orders_customer ON orders(customer_id);

Estimated Improvement: 90-99% reduction in execution time

______________________________________________________________________

✨ 最新功能（2025年1月）

🎯 分析深度模式

在快速仅计划分析或完全优化之间进行选择：

# Fast plan explanation (0.3s, educational)
analyze_oracle_query(db="prod", sql="SELECT...", depth="plan_only")

# Full optimization analysis (1-3s, production-ready)
analyze_oracle_query(db="prod", sql="SELECT...", depth="standard")  # default

优点：

⚡ 快10倍 用于教育查询
💰 代币减少96% （500对13000代币）
🎓 非常适合学习执行计划
🚀 优化时的完整上下文

文档： 看 server/knowledge_base/depth_modes.md

______________________________________________________________________

🎯 智能令牌优化

输出最小化将令牌使用率降低了80%，而不会丢失优化上下文：

之前： 每次分析约63000个令牌 之后： 每次分析约12700个令牌

从执行计划中删除NULL/空字段
合并相关数据（索引+列）
将原始统计数据转化为可操作的见解
保留所有必要的优化数据

影响： 更低的成本，更快的分析，相同的质量

______________________________________________________________________

📏 大型查询的自动预设调整

自动处理任何大小的查询：

查询大小	操作	元数据深度
\50KB	自动切换到最小值	仅限基本值

优点：

✅ 具有100+列的UNION查询可以完美运行
✅ 始终保留完整的SQL（从不截断）
✅ 预设调整时通知用户
✅ 处理50K+个字符的查询

文档： 看 QUERY_OPTIMIZATION_IMPROVEMENTS.md

______________________________________________________________________

🛠️ 核心工具

1. `explain_business_logic` ⭐ 主要工具

它的作用： 分析SQL查询以解释业务逻辑和关系

参数：

db_name （必需）-settings.yaml中的数据库名称
sql_text （必填）-要分析的SQL查询
follow_relationships （可选，默认值：true）-遵循FK关系
max_depth （可选，默认值：2）-要遍历的关系深度

退货：

经营目的说明
带有行数和注释的表元数据
具有推断语义的列详细信息
外键关系（递归）
美人鱼ER图
实体和域分类
缓存统计

演出

第一次运行：约10秒（从数据库+缓存收集）
缓存运行：约0.7秒（快93%）
缓存TTL:7天

例子：

explain_business_logic("production_db", "SELECT * FROM customer_orders WHERE order_date > '2024-01-01'")

______________________________________________________________________

2. `analyze_full_sql_context`

它的作用： 深入的性能分析，包括执行计划和优化建议

参数：

db_name （必填）-数据库名称
sql_text （必填）-要分析的SQL查询

退货：

包含成本和基数的执行计划
表和索引统计
性能问题诊断（全扫描、笛卡尔积）
历史比较（回归检测）
带有表情符号警告的可视化计划树
优化建议

例子：

analyze_full_sql_context("production_db", "SELECT * FROM orders o JOIN customers c ON o.customer_id = c.id WHERE o.amount > 1000")

______________________________________________________________________

3. `compare_query_plans`

它的作用： 原始查询与优化查询的并排比较

参数：

db_name （必填）-数据库名称
original_sql （必填）-原始查询
improved_sql （必填）-优化查询

退货：

成本差异和改进百分比
访问方法更改（全扫描→ 索引扫描）
基数估计差异
方案结构比较

______________________________________________________________________

4. `list_available_databases`

它的作用： 列出所有已配置的数据库连接及其状态

退货：

数据库名称和类型（Oracle/MySQL）
连接状态（已连接/错误）
数据库版本和实例信息

______________________________________________________________________

📊 PostgreSQL缓存架构

运作原理

First Query:
┌─────────┐     ┌──────────────┐     ┌────────────┐
│ Claude  │────>│  MCP Server  │────>│   Oracle   │
└─────────┘     │              │     │            │
                │  10 seconds  │     └────────────┘
                │              │
                │              │     ┌────────────┐
                │              │────>│ PostgreSQL │
                └──────────────┘     │   Cache    │
                                     └────────────┘

Subsequent Queries (same tables):
┌─────────┐     ┌──────────────┐     ┌────────────┐
│ Claude  │────>│  MCP Server  │────>│ PostgreSQL │
└─────────┘     │              │     │   Cache    │
                │  0.7 seconds │     └────────────┘
                └──────────────┘
                     93% faster!

缓存数据

表元数据：行数、注释、分区信息
列详细信息：名称、类型、可空性、注释
主键：索引列
外键：表之间的关系
业务语义：推断实体类型和域
生存时间：7天（可配置）

缓存管理

所有缓存都是自动的，不需要手动干预：

✅ 第一次查询时自动填充缓存
✅ 自动TTL到期（7天）
✅ 过时时自动刷新缓存
✅ 管理员可以使用自定义文档进行覆盖

______________________________________________________________________

⚙️ 配置

数据库连接

编辑 server/config/settings.yaml:

database_presets:
  # Oracle Database
  production_oracle:
    type: oracle
    user: app_user
    password: your_password
    dsn: hostname:1521/service_name

  # MySQL Database
  production_mysql:
    type: mysql
    host: mysql.example.com
    port: 3306
    user: app_user
    password: your_password
    database: application_db

PostgreSQL缓存

编辑 .env 文件：

KNOWLEDGE_DB_HOST=omni_db
KNOWLEDGE_DB_PORT=5432
KNOWLEDGE_DB_NAME=omni
KNOWLEDGE_DB_USER=omni
KNOWLEDGE_DB_PASSWORD=omni
KNOWLEDGE_DB_SCHEMA=mcp_performance

______________________________________________________________________

🔐 安全

什么是受保护的

此MCP服务器是只读和 设计安全:

✅ 仅使用EXPLAIN PLAN（从不执行用户SQL）
✅ 仅查询元数据视图（information_schema、ALL\_\*视图）
✅ 阻止所有写入操作（INSERT、UPDATE、DELETE、DROP等）
✅ 阻止危险操作（批准、撤销、关闭等）
✅ 验证查询复杂性（最大深度、长度限制）
✅ 数据修改的可能性为零

多层防御

LLM级别：工具说明包括突出的安全警告
工具层：在任何数据库交互之前预验证SQL
收集器级别：使用25个以上被屏蔽的关键字进行深度验证

受阻操作： 插入、更新、删除、删除、创建、更改、授予、撤销、截断、关闭、终止、执行、提交、回滚、锁定/解锁、选择进入、进入输出文件

______________________________________________________________________

🔧 必需的权限

Oracle最低权限

-- Core metadata access
GRANT SELECT ON ALL_TABLES TO your_user;
GRANT SELECT ON ALL_INDEXES TO your_user;
GRANT SELECT ON ALL_IND_COLUMNS TO your_user;
GRANT SELECT ON ALL_TAB_COLUMNS TO your_user;
GRANT SELECT ON ALL_TAB_COL_STATISTICS TO your_user;
GRANT SELECT ON ALL_CONSTRAINTS TO your_user;
GRANT SELECT ON ALL_CONS_COLUMNS TO your_user;
GRANT SELECT ON ALL_PART_TABLES TO your_user;
GRANT SELECT ON ALL_PART_KEY_COLUMNS TO your_user;
GRANT SELECT ON ALL_TAB_COMMENTS TO your_user;
GRANT SELECT ON ALL_COL_COMMENTS TO your_user;

-- For EXPLAIN PLAN
GRANT INSERT, DELETE ON PLAN_TABLE TO your_user;

MySQL最低权限

-- Core metadata access
GRANT SELECT ON information_schema.TABLES TO 'your_user'@'%';
GRANT SELECT ON information_schema.STATISTICS TO 'your_user'@'%';
GRANT SELECT ON information_schema.COLUMNS TO 'your_user'@'%';
GRANT SELECT ON your_database.* TO 'your_user'@'%';

-- For index usage statistics (recommended)
GRANT SELECT ON performance_schema.table_io_waits_summary_by_index_usage TO 'your_user'@'%';

______________________________________________________________________

📚 详细文件

有关全面的技术细节，请参阅功能_详细.md:

业务逻辑分析 -深入了解SQL解析、元数据收集和语义推理
PostgreSQL缓存系统 -架构、模式设计和优化策略
性能监控 -数据库健康指标和顶级查询分析
输出过滤预设 -如何控制响应大小和令牌使用
未来改进 -路线图和计划中的改进

______________________________________________________________________

📈 性能基准

业务逻辑分析

场景	首次运行	缓存运行	改进
单表查询	2.1s	0.3s	快85%
3表连接	5.8秒	0.6秒	快90%
复杂查询（10+个表）	12.4秒	0.9秒	93%更快

缓存操作

操作	时间	吞吐量
单表查找	5ms	200次操作/秒
批量查找（10个表）	9ms	1111次操作/秒
保存表元数据	12毫秒	83次操作/秒
批量保存（10个表）	25ms	400次操作/秒

______________________________________________________________________

🧪 测试

验证安装

# Check services are running
docker ps | grep -E "(mcp_db_performance|omni_pg_db)"

# Test PostgreSQL connection
docker exec mcp_db_performance python -c "from knowledge_db import get_knowledge_db; import asyncio; db = get_knowledge_db(); print('Connected:', asyncio.run(db.connect()))"

# Test database connection
docker exec mcp_db_performance python -m mcp_app

在Claude Desktop中进行测试

User: "List available databases"

Expected: Should show all configured databases with connection status

User: "Explain the business logic of this query:
SELECT * FROM customer_orders WHERE order_date > '2024-01-01'"

Expected: Should return business analysis with table relationships and domain classification

______________________________________________________________________

📁 项目结构

mcp_db_peformance/
├── server/
│   ├── tools/                    # MCP tool implementations
│   │   ├── oracle_explain_logic.py   # Business logic analysis
│   │   ├── oracle_analysis.py         # Performance analysis
│   │   └── mysql_analysis.py          # MySQL support
│   ├── knowledge_db.py           # PostgreSQL cache connector
│   ├── config.py                 # Configuration management
│   ├── server.py                 # MCP server
│   ├── mcp_app.py               # FastMCP application
│   ├── test-scripts/
│   │   └── run_complete_init.py  # Schema initialization
│   └── migrations/
│       └── 000_complete_schema_init.sql
├── docker-compose.yml
├── .env
└── README.md

pg_mcp/                           # PostgreSQL cache database
├── docker-compose.yml
└── postgres-init/
    └── init.sql

______________________________________________________________________

📊 建筑

┌─────────────────┐
│  Claude Desktop │
│   (MCP Client)  │
└────────┬────────┘
         │
         │ MCP Protocol
         ▼
┌─────────────────┐      ┌──────────────┐
│  MCP Server     │─────>│   Oracle     │
│  (FastMCP)      │      │   Database   │
└────────┬────────┘      └──────────────┘
         │
         │ Cache Layer
         ▼
┌─────────────────┐      ┌──────────────┐
│  PostgreSQL     │      │    MySQL     │
│  Cache (omni)   │      │   Database   │
└─────────────────┘      └──────────────┘

______________________________________________________________________

🛠️ 故障排除

常见问题

“数据库连接失败”

检查凭据 server/config/settings.yaml
验证数据库是否可以从Docker容器访问
测试： docker exec mcp_db_performance ping

“缓存不工作”

验证PostgreSQL是否正在运行： docker ps | grep omni_pg_db
检查连接： docker logs mcp_db_performance | grep PostgreSQL
重新运行init脚本： docker exec mcp_db_performance python test-scripts/run_complete_init.py

“ORA-00942:表或视图不存在”

授予所需的Oracle权限（见上文）
检查用户在ALL\_\*视图上是否有选择

“性能缓慢”

第一次查询总是较慢（缓存填充）
后续查询应为亚秒级
检查PostgreSQL连接延迟

______________________________________________________________________

📚 附加文档

功能_详细.md -深入的技术文档
博士后_慕尼黑_审计-2026-01-16md -带有测试结果的PostgreSQL审计报告
server/knowledge_base/ -MCP工具文档
to_delete/ -准备删除的过时文件（包括README）

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推送到分支(git push origin feature/amazing-feature)
打开拉取请求

______________________________________________________________________

📜 许可证

MIT许可证-请参阅许可证详细信息文件

______________________________________________________________________

👤 作者

阿维·科恩 📧 电子邮件：aviciot@gmail.com 🐙 github： @飞机

______________________________________________________________________

🙏 致谢

建于快速MCP
由...驱动模型上下文协议（MCP）

______________________________________________________________________

⭐ 如果你觉得这个仓库有用，就把它标上！ ⭐

MCP db performance

快速接入

详细介绍

Oracle和MySQL商业智能MCP服务器

🎯 它做什么

主要特点

🚀 快速开始

自动部署（推荐）

手动部署

3.连接克劳德桌面

💡 示例用例

业务逻辑解释

性能分析

✨ 最新功能（2025年1月）

🎯 分析深度模式

🎯 智能令牌优化

📏 大型查询的自动预设调整

🛠️ 核心工具

1. explain_business_logic ⭐ 主要工具

2. analyze_full_sql_context

3. compare_query_plans

4. list_available_databases

📊 PostgreSQL缓存架构

运作原理

缓存数据

缓存管理

⚙️ 配置

数据库连接

PostgreSQL缓存

🔐 安全

什么是受保护的

多层防御

🔧 必需的权限

Oracle最低权限

MySQL最低权限

📚 详细文件

📈 性能基准

业务逻辑分析

缓存操作

🧪 测试

验证安装

在Claude Desktop中进行测试

📁 项目结构

📊 建筑

🛠️ 故障排除

常见问题

📚 附加文档

🤝 贡献

📜 许可证

👤 作者

🙏 致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `explain_business_logic` ⭐ 主要工具

2. `analyze_full_sql_context`

3. `compare_query_plans`

4. `list_available_databases`