# RustMcpTools

**Repository Path**: LeiZhK/RustMcpTools

## Basic Information

- **Project Name**: RustMcpTools
- **Description**: 基于 Rust 实现的多中间件 MCP（Model Context Protocol）服务平台，为 Trae 等 AI 助手提供数据库、消息队列、DevOps 工具等能力的统一接入层。相比 `npx`（Node.js）和 `uvx`（Python）的按需安装方式，本项目采用 Rust 原生编译为单一二进制文件，优势显著。
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Rust, GUI, exe, MCP

## README

# RustMcpTools

[![Crates.io](https://img.shields.io/badge/version-1.0.1-blue)](https://crates.io/crates/rust-mcp-tools)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-2021-edition-orange)](https://www.rust-lang.org)

[![MCP 协议](https://img.shields.io/badge/MCP-协议规范-purple)](https://spec.modelcontextprotocol.io)
[![MCP GitHub](https://img.shields.io/badge/MCP-GitHub仓库-purple)](https://github.com/modelcontextprotocol)
[![Rust 官网](https://img.shields.io/badge/Rust-官网-orange)](https://www.rust-lang.org)
[![Gitee 仓库](https://img.shields.io/badge/Gitee-仓库-red)](https://gitee.com/LeiZhK/RustMcpTools)

基于 Rust 实现的多中间件 MCP（Model Context Protocol）服务平台，为 Trae、Claude Code 等 AI 助手提供数据库、网页抓取等能力的统一接入层。

> **💡 相比 `npx`（Node.js）和 `uvx`（Python）的按需安装方式，本项目采用 Rust 原生编译为单一二进制文件，优势显著：**

| 对比维度 | npx / uvx 方式 | 本项目（Rust 二进制） |
|---------|----------------|---------------------|
| 🚀 **启动速度** | 需下载包 + 启动运行时（Node/Python），冷启动秒级 | **毫秒级冷启动**，直接执行机器码 |
| 📦 **运行依赖** | 需预装 Node.js 或 Python + uv | **零依赖**，无需任何运行时 |
| 🔌 **离线可用** | 首次运行需联网下载依赖包 | **完全离线**，编译即携带所有依赖 |
| 💾 **磁盘占用** | 50~150MB（运行时 + node_modules/venv） | **~15MB**，一个文件即服务 |
| 🛡️ **供应链安全** | 递归拉取数十~数百个第三方包，攻击面大 | 依赖树极小，编译时安全检查 |
| 🎯 **部署便捷性** | 需确保目标机器有所需运行时版本 | **复制即用**，一个 exe 文件搞定 |
| ⚡ **运行时性能** | JIT 编译（Node）/ 解释执行（Python），有 GC 开销 | **原生机器码**，无 JIT 预热、无 GC 停顿 |

## 功能特性

- **MCP 协议支持**：完整实现 Model Context Protocol（JSON-RPC 2.0），兼容 HTTP + SSE 和 stdio 双传输模式
- **MySQL 数据库 MCP 服务**：SQL 查询、表管理、表结构查看，支持 DDL/DML 权限管控
- **网页抓取 MCP 服务**：URL 内容抓取与状态检查
- **双运行模式**：HTTP 服务器模式和 stdio 模式，灵活对接各类 AI 工具
- **GUI 管理客户端**（可选）：基于 egui/eframe 的可视化管理界面，一站式管理所有服务
- **DDL/DML 权限管控**：可独立控制是否允许执行建表/改表等 DDL 语句和 INSERT/UPDATE/DELETE 等 DML 语句

## 服务生态

### 📦 MCP 服务

| 服务 | 状态 | 说明 | 功能 |
|------|------|------|------|
| 🐬 **MySQL MCP Server** | ✅ **已实现** | 关系型数据库访问 | SQL 查询、表管理、表结构查看、DDL/DML 权限管控 |
| 🌐 **Scraper MCP Server** | ✅ **已实现** | 网页内容抓取 | URL 内容获取、网页状态检查 |
| 🔴 **Redis MCP Server** | 🔜 规划中 | 缓存数据库访问 | String/Hash/List/Set/ZSet 操作、发布订阅 |
| 🐘 **PostgreSQL MCP Server** | 🔜 规划中 | 关系型数据库访问 | 高级查询、模式管理 |
| 🍃 **MongoDB MCP Server** | 🔜 规划中 | 文档数据库访问 | 文档查询、聚合管道 |
| 🔍 **Elasticsearch MCP Server** | 🔜 规划中 | 搜索引擎访问 | 全文搜索、聚合分析 |
| 📨 **Kafka MCP Server** | 🔜 规划中 | 消息队列访问 | 消息生产/消费、Topic 管理 |

## 项目架构

```
RustMcpTools/
├── src/
│   ├── main.rs               # mysql-mcp 入口（HTTP & stdio 模式）
│   ├── lib.rs                 # 库根模块
│   ├── config.rs              # SQLite 配置存储模块（含 DDL/DML 权限管控）
│   ├── db.rs                  # MySQL 数据库模块
│   ├── scraper.rs             # 网页抓取 MCP 实现
│   ├── bin/
│   │   ├── gui.rs             # GUI 二进制（可选，需 gui feature）
│   │   └── scraper.rs         # scraper-mcp 独立二进制入口
│   ├── mcp/
│   │   ├── mod.rs             # MCP 模块根
│   │   ├── handler.rs         # MCP 工具定义（旧模块，新工具逻辑在 transport.rs）
│   │   ├── transport.rs       # HTTP 传输层（axum 路由、SSE、JSON-RPC 处理）
│   │   └── stdio.rs           # stdio 传输模式（stdin/stdout JSON-RPC 通信）
│   └── services/
│       ├── mod.rs             # 服务模块根
│       └── process.rs         # 进程生命周期管理
├── scripts/                   # PowerShell 辅助脚本
│   ├── Build-Gui.ps1          # 构建 GUI 版本
│   ├── build-gui-admin.ps1    # 管理员模式构建 GUI
│   ├── Diagnose-TraeConnection.ps1  # 诊断 Trae 连接问题
│   └── Test-McpService.ps1    # 测试 MCP 服务
├── CLAUDE.md                  # Claude Code 项目指引（中文）
├── CLAUDE.zh.md               # Claude Code 项目指引（英文）
└── config.db                  # SQLite 配置文件（首次运行 GUI 时自动生成）
```

## 环境要求

- [Rust](https://www.rust-lang.org/zh-cn/tools/install)（edition 2021）
- MySQL 服务器（推荐 8.0+）— 使用 MySQL MCP Server 时需要

## 快速开始

### 编译构建

```bash
# 编译所有二进制（默认不包含 GUI）
cargo build --release

# 编译包含 GUI 的版本
cargo build --release --features gui --bin ZenkovenMcpTools
```

### 运行 MySQL MCP Server

```bash
# HTTP 模式（默认端口 3000）
cargo run --release

# 指定端口
cargo run --release -- --port 3307

# stdio 模式（适用于 MCP 兼容客户端，如 Claude Desktop/Code）
cargo run --release -- --stdio
```

### 运行 Scraper MCP Server

```bash
# HTTP 模式（默认端口 3001）
cargo run --release --bin scraper-mcp

# stdio 模式
cargo run --release --bin scraper-mcp -- --stdio
```

### 验证服务

```bash
# 测试 MySQL MCP Server
curl http://localhost:3000/health

# 测试 Scraper MCP Server
curl http://localhost:3001/health

# 调用 initialize
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
```

## 集成 AI 助手

### Stdio 方式（推荐，Claude Desktop/Code）

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "command": "path/to/mysql-mcp.exe",
      "args": ["--stdio"]
    },
    "scraper-mcp": {
      "command": "path/to/scraper-mcp.exe",
      "args": ["--stdio"]
    }
  }
}
```

### HTTP 方式（Trae 等）

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "url": "http://localhost:3000/mcp"
    },
    "scraper-mcp": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

## MCP API

### MySQL MCP Server 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/health` | 健康检查 |
| `GET` | `/sse` | SSE 流式推送 |
| `POST` | `/mcp` | MCP JSON-RPC 请求 |
| `OPTIONS` | `/mcp`, `/sse` | CORS 预检请求 |

### 当前可用工具

#### MySQL 工具

| 工具 | 说明 | 参数 |
|------|------|------|
| `sql_execute` | 执行 SQL 查询/语句 | `sql`（字符串，必填） |
| `sql_list_tables` | 列出当前数据库所有表 | 无 |
| `sql_describe_table` | 查看表结构 | `table`（字符串，必填） |

#### Scraper 工具

| 工具 | 说明 | 参数 |
|------|------|------|
| `fetch_url` | 获取 URL 内容 | `url`（字符串，必填） |
| `fetch_status` | 检查网页状态码 | `url`（字符串，必填） |

## GUI 模式（可选）

构建带图形界面的版本，可视化地管理所有服务：

```bash
cargo build --release --features gui --bin ZenkovenMcpTools
./target/release/ZenkovenMcpTools.exe
```

GUI 提供以下功能：

- 🏠 **服务管理中心**：卡片式布局展示所有 MCP 服务的运行状态
- 🐬 **MySQL 服务详情**：连接配置、DDL/DML 权限开关、SQL 在线执行、表结构查看
- 🌐 **Scraper 服务详情**：抓取服务状态监控
- ⚙️ **MCP 配置面板**：一键生成 Stdio/HTTP 两种模式的配置 JSON
- 📝 **实时日志**：服务运行日志监控

### 截图预览

| 首页仪表盘 |
| :---: |
| ![首页仪表盘](images/index.png) |

| MySQL 服务配置 | Scraper MCP 配置 |
| :---: | :---: |
| ![MySQL 服务配置](images/mysql-mcp-config.png) | ![Scraper MCP 配置](images/scraper-mcp-config.png) |

| 数据库配置 | 数据表查看 |
| :---: | :---: |
| ![数据库配置](images/config.png) | ![数据表查看](images/list-table.png) |

| Scraper 抓取演示 |
| :---: |
| ![Scraper 抓取演示](images/scraper-execute.png) |

## 开发路线

### ✅ 当前完成

- MySQL MCP Server 核心功能（SQL 查询、表管理、表结构查看）
- Scraper MCP Server（URL 内容抓取、状态检查）
- MCP 协议基础框架（JSON-RPC 2.0, HTTP+SSE+stdio）
- GUI 管理界面框架与 MySQL/Scraper 详情页
- DDL/DML 权限管控开关
- 多服务架构设计（ServiceType 枚举体系）
- CLAUDE.md 项目指引文档

### 🔜 规划中

- [ ] Redis MCP Server — 缓存操作
- [ ] PostgreSQL MCP Server — 关系型数据库
- [ ] MongoDB MCP Server — 文档数据库
- [ ] Elasticsearch MCP Server — 搜索引擎
- [ ] Kafka MCP Server — 消息队列
- [ ] Docker MCP Server — 容器管理
- [ ] Git MCP Server — 版本控制

## 更新记录

### v1.0.1 (2026-05-15)

- ✨ **新增**: Scraper MCP Server 独立二进制（`scraper-mcp`），支持 HTTP 和 stdio 双模式
- ✨ **新增**: stdio 传输模式支持，可直接对接 Claude Desktop/Code 等客户端
- ✨ **新增**: DDL/DML 权限管控开关，可独立控制是否允许执行写操作
- ✨ **新增**: CLAUDE.md / CLAUDE.zh.md 项目指引文档
- 🐛 **修复**: `sql_execute` 执行 `SELECT 1` 等数字列返回 `NULL` 的问题（改用多类型回退：String → i64 → f64）
- 🐛 **修复**: GUI 启动服务时无防重复启动保护，导致端口冲突显示错误的问题
- 🐛 **修复**: GUI 中 Starting/Error 状态显示不完整，按钮条件判断不当的问题
- 🔧 **优化**: `start_service()` 日志输出时机，服务真正就绪后才输出成功日志
- 🔧 **优化**: GUI MCP 配置页签改为"Stdio方式"和"Http方式"

### v0.1.0 (初始版本)

- MySQL MCP Server 核心功能（SQL 查询、表列表、表结构查看）
- MCP 协议基础框架（JSON-RPC 2.0, HTTP + SSE 双传输模式）
- GUI 管理界面框架与 MySQL 详情页
- 多服务架构设计（ServiceType 枚举体系）

## 项目状态

本项目处于积极开发阶段。MySQL MCP Server 和 Scraper MCP Server 核心功能稳定可用，GUI 客户端提供了完整的服务管理框架。欢迎贡献代码和反馈意见。

## 开源协议

本项目基于 MIT 协议开源 - 详见 [LICENSE](LICENSE) 文件。