使用说明

MySQL 自然语言处理（NLP）机器学习（MCP，此处假设为Machine Learning Classifier的缩写，但具体含义可能根据上下文有所不同）服务器

一个基于AWS Bedrock和FastAPI的全面自然语言处理服务器，专为MySQL数据库设计，全面支持MCP（模型上下文协议）。

特点/特性

自然语言转SQL使用AWS Bedrock Converse API（通过Amazon Nova Pro或Claude 3.5 Sonnet）将自然语言问题转换为SQL查询
MCP协议支持人工智能工具集成的完整模型上下文协议实现
FastAPI REST API传统的REST API端点，用于直接集成
终端接口用于直接终端使用的交互式和命令行界面
安全仅读取模式执行SQL，具备输入验证和SQL注入防护
模式感知自动检测数据库模式以优化SQL生成
共享架构代码整洁、可维护，且共享实用工具
已准备好投入生产经过全面测试和优化，已准备好投入生产部署

建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client App    │    │   MCP Client    │    │   REST Client   │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │    MySQL NLP Server       │
                    │  ┌─────────────────────┐  │
                    │  │   MCP Server        │  │
                    │  │   (mcp_server.py)   │  │
                    │  └─────────────────────┘  │
                    │  ┌─────────────────────┐  │
                    │  │   FastAPI Server    │  │
                    │  │   (app/main.py)     │  │
                    │  └─────────────────────┘  │
                    │  ┌─────────────────────┐  │
                    │  │  Shared Utilities   │  │
                    │  │ (app/shared_utils)  │  │
                    │  └─────────────────────┘  │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │   AWS Bedrock Converse    │
                    │ (Nova Pro / Claude 3.5)   │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │     MySQL RDS            │
                    └───────────────────────────┘

快速入门

先决条件

Python 3.8及以上版本
MySQL数据库（本地或AWS RDS）
拥有Bedrock访问权限的AWS账户
Git（注：Git是一个分布式版本控制系统，用于跟踪对文件的修改）

安装

克隆仓库：

git clone https://github.com/YOUR_USERNAME/mysql-nlp-mcp-server.git
cd mysql-nlp-mcp-server

安装依赖项：
```
pip install -r requirements.txt
```

配置环境变量:

cp .env.example .env

编辑 .env 附上您的身份证明文件：

# Database Configuration
DB_HOST=your-rds-endpoint.amazonaws.com
DB_PORT=3306
DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password

# AWS Configuration
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20240620-v1:0

配置AWS凭证：

aws configure
# OR set environment variables:
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

测试设置:
```
python test_mcp_server.py
```

用法

选项1：终端接口（推荐直接使用）

交互式终端客户端

python terminal_mcp_client.py

命令：

ask <question> - 提出自然语言问题
sql <query> - 执行原始SQL查询
schema - 获取数据库模式
generate <question> - 生成SQL而不执行
help - 显示所有命令

命令行界面

# Quick commands
python mcp_cli.py ask "Show me all courses"
python mcp_cli.py sql "SELECT * FROM Courses LIMIT 5"
python mcp_cli.py schema
python mcp_cli.py generate "Find students from California"

选项2：MCP服务器（用于AI集成）

python start_mcp_server.py

可用的MCP工具：

query_database - 执行自然语言查询
execute_sql - 执行原始SQL SELECT查询
get_schema - 获取数据库模式信息
generate_sql - 从自然语言生成SQL语句而不执行

与Claude桌面版集成

要使用Claude Desktop连接您的MCP服务器，请按照以下步骤操作：

第一步：安装Claude桌面版

从以下链接下载并安装：https://claude.ai/download

步骤2：定位配置文件

找到您的Claude桌面配置文件：

Windows： %APPDATA%\Claude\claude_desktop_config.json
macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

步骤3：添加MCP服务器配置

编辑 claude_desktop_config.json 并添加您的服务器：

{
  "mcpServers": {
    "mysql-nlp": {
      "command": "python",
      "args": [
        "C:/Users/YOUR_USERNAME/path/to/mcp-mysql/mcp_server.py"
      ],
      "env": {
        "DB_HOST": "your-database-host",
        "DB_PORT": "3306",
        "DB_NAME": "your-database-name",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "AWS_REGION": "us-east-1",
        "BEDROCK_MODEL_ID": "amazon.nova-pro-v1:0"
      }
    }
  }
}

重要提示：

使用 绝对路径 到你的 mcp_server.py 文件
使用正斜杠（/）/) 即使在Windows上
将占位符值替换为您的实际凭据
或者，使用 "cwd" 从（指定位置）加载的参数 .env 文件：

{
  "mcpServers": {
    "mysql-nlp": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "C:/Users/YOUR_USERNAME/path/to/mcp-mysql"
    }
  }
}

步骤4：重启Claude桌面应用

完全退出并重新启动 Claude Desktop 以使更改生效。

第五步：使用工具

在Claude Desktop中：

寻找🔨（锤子）图标以查看可用工具
请Claude使用你的数据库工具：
- “使用query_database向我展示所有教授”
- “使用 get_schema 获取数据库模式”
- “生成SQL语句以查找学生人数超过50人的所有课程”

示例对话：

You: Use the query_database tool to show me all professors

Claude: I'll query the database for all professors.
[Calls query_database tool]

Here are all the professors in your database:
1. Dr. John Doe - john.doe@university.edu (Hired: 2020-01-10)
2. Dr. Jane Williams - jane.williams@university.edu (Hired: 2019-09-05)

故障排除：

如果工具未出现，请检查Claude Desktop中的开发者控制台
确保 Python 已添加到系统的 PATH 中
验证所有凭据是否正确
确认MCP服务器独立运行： python start_mcp_server.py

选项3：FastAPI服务器（REST API）

python start_fastapi_server.py

访问： http://localhost:8000/docs

API终端点：

GET / - API信息
GET /test-db - 测试数据库连接
GET /schema - 获取数据库架构
POST /query - 处理自然语言查询
POST /sql - 执行原始SQL查询
POST /generate-sql - 从自然语言生成SQL

示例用法：

# Natural language query
curl -X POST "http://localhost:8000/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "Show me all users from California"}'

# Raw SQL query
curl -X POST "http://localhost:8000/sql" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users WHERE state = \"CA\""}'

配置

环境变量

变量	描述	默认值
`DB_HOST`	MySQL 主机地址	本地主机
`DB_PORT`	MySQL 端口	3306
`DB_NAME`	数据库名称	mcpdemo1
`DB_USER`	数据库用户名	root
`DB_PASSWORD`	数据库密码	密码
`AWS_REGION`	Bedrock 所在的 AWS 区域	us-east-1
`BEDROCK_MODEL_ID`	基础模型ID	anthropic.claude-3-5-sonnet-20240620-v1:0
`API_HOST`	FastAPI 主机	0.0.0.0
`API_PORT`	FastAPI 端口	8000
`API_RELOAD`	启用自动重载	true

数据库需求

MySQL 5.7或更高版本，或MySQL 8.0或更高版本
对目标数据库的读取访问权限
服务器到数据库的网络连接

AWS 要求

拥有Bedrock访问权限的AWS账户
IAM（身份和访问管理）权限用于 bedrock:InvokeModel
已正确配置AWS凭证

安全特性

只读查询仅允许使用SELECT语句
SQL注入防护参数化查询和输入验证
模式验证自动模式检测和验证
错误处理全面的错误处理，同时不泄露敏感信息

项目结构

mysql-nlp-mcp-server/
├── app/
│   ├── main.py          # FastAPI server implementation
│   ├── config.py        # Configuration management
│   └── shared_utils.py  # Shared utilities (database + Bedrock)
├── mcp_server.py       # MCP server implementation
├── start_mcp_server.py # MCP server startup script
├── start_fastapi_server.py # FastAPI server startup script
├── terminal_mcp_client.py # Interactive terminal MCP client
├── mcp_cli.py          # Command-line MCP interface
├── test_mcp_server.py  # MCP server testing script
├── test_rds_connection.py # Database connection testing
├── requirements.txt    # Python dependencies
├── .env.example       # Environment variables template
└── README.md          # This file

发展

添加新功能

对于MCP工具在（此处）添加新的工具定义 mcp_server.py
对于API终端点添加新路线到 app/main.py
对于数据库操作扩展函数中的功能 app/shared_utils.py
对于配置更新 app/config.py 用于新设置

测试

测试数据库连接：

curl http://localhost:8000/test-db

测试自然语言查询：

curl -X POST "http://localhost:8000/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "Show me the first 5 records from any table"}'

测试

测试您的设置

# Test MCP server functionality
python test_mcp_server.py

# Test database connection
python test_rds_connection.py

# Test simple SQL query
python test_simple.py

示例查询

自然语言：

# Interactive mode
python terminal_mcp_client.py
MCP> ask Show me all courses with more than 50 students

# Command line
python mcp_cli.py ask "Find all students from California"

SQL 查询：

# Interactive mode
MCP> sql SELECT * FROM Courses LIMIT 10

# Command line  
python mcp_cli.py sql "SELECT COUNT(*) FROM Students"

故障排除

常见问题

数据库连接错误：
- 检查数据库凭据 .env
- 确保可以从服务器访问数据库
- 验证 MySQL 服务是否正在运行
AWS Bedrock 错误:
- 验证AWS凭证是否已配置
- 检查Bedrock的IAM权限
- 确保模型ID正确无误
- 注确保您使用的是正确的Claude 3.5 Sonnet模型ID
导入错误:
- 安装所有依赖项： pip install -r requirements.txt
- 检查Python版本兼容性
- 确保所有文件都位于正确的目录结构中
MCP服务器问题:
- 验证MCP服务器能否无错误启动： python mcp_server.py
- 检查共享实用程序是否已正确导入
- 确保环境变量已配置

日志

两台服务器都提供了详细的日志记录。请检查控制台输出以获取错误消息和调试信息。

做出贡献

我们欢迎投稿！以下是投稿指南：

为仓库创建分支
创建一个特性分支: git checkout -b feature/amazing-feature
进行你的更改 并测试它们
提交您的更改: git commit -m 'Add amazing feature'
推送到分支: git push origin feature/amazing-feature
提交拉取请求

开发环境设置

# Clone your fork
git clone https://github.com/YOUR_USERNAME/mysql-nlp-mcp-server.git
cd mysql-nlp-mcp-server

# Install dependencies
pip install -r requirements.txt

# Run tests
python test_mcp_server.py

许可证

这个项目遵循MIT许可证授权——详见许可证文件中有详细信息。

支持

需要帮助吗？

📖 查看上面的故障排除部分
请查看API文档： /docs
🐛 在仓库中创建一个问题
💬 开始讨论问题

发现了一个错误吗？

请创建一个问题，并包含以下内容：
- 复现步骤
- 预期行为与实际行为
- 环境详情（操作系统、Python版本等）

给这个仓库点赞/收藏

如果这个项目对您有帮助，请给它点个星吧！