# MiddleTool

多环境中间件连接管理桌面应用，统一对外提供 MCP（Model Context Protocol）能力。

[English](README.en.md)

## 使用场景

MiddleTool 专为以下场景设计：

### 运维开发
- 统一管理多环境（dev、sit、uat、prod）的中间件连接
- 快速切换环境进行问题排查和数据查询
- 通过 MCP 协议在 Cursor 中直接操作中间件

### DevOps 工程师
- 集中管理 Kubernetes 集群连接
- 通过 MCP 协议在 Claude Desktop 中执行 K8s 操作
- 备份和迁移中间件配置

### 平台工程师
- 统一中间件访问入口，避免直接暴露连接信息
- 通过 MCP 协议为 AI 助手提供受控的中间件访问能力
- 插件式架构，快速接入新的中间件类型

## 功能

- **中间件连接**：按适配器 schema 配置连接，通过名称区分环境（如 prod-loki）
- **中间件目录**：查看已注册的全部 MCP 适配器、连通性校验与上游仓库链接
- **连接测试**：保存前可测试 Loki / MySQL / Redis / RocketMQ / Elasticsearch / MongoDB / Kubernetes 连通性
- **环境配置**：Kubernetes 多环境配置管理（dev、sit、uat、prod）
- **配置导入导出**：备份与迁移环境与连接
- **MCP 配置导出**：生成 Cursor / Claude Desktop 可用的 `mcpServers` JSON，支持写入文件
- **插件式架构**：新增中间件只需添加适配器文件并注册

## 架构

```mermaid
graph TB
    subgraph "MiddleTool Desktop"
        A[Electron 主进程]
        B[React 渲染进程]
        C[配置存储]
        D[适配器注册表]
        E[MCP Server]
    end

    subgraph "中间件层"
        F[Loki]
        G[RocketMQ]
        H[MySQL]
        I[Redis]
        J[Elasticsearch]
        K[MongoDB]
        L[Kubernetes]
    end

    subgraph "AI IDE"
        M[Cursor]
        N[Claude Desktop]
    end

    A --> D
    A --> C
    B --> A
    D --> E
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
    E --> L
    M --> E
    N --> E
```

### 数据流

1. **配置阶段**：用户在桌面端配置中间件连接，存储在本地配置文件
2. **MCP 服务**：MCP Server 读取配置，提供统一的 MCP 协议接口
3. **AI 访问**：Cursor / Claude Desktop 通过 MCP 协议调用中间件操作
4. **中间件交互**：MCP Server 通过适配器层与各中间件通信

## 已注册中间件

| 中间件 | 分类 | MCP 来源 | 状态 |
|--------|------|----------|------|
| Grafana Loki | 日志 | [loki-mcp](https://gitee.com/mirrors_grafana/loki-mcp) | ✅ 可用 |
| Apache RocketMQ | 消息队列 | 内置 `packages/rocketmq-mcp-server` | ✅ 可用 |
| MySQL | 数据库 | 内置 `packages/mysql-mcp-server`（兼容 [mcp-server-mysql](https://github.com/benborla/mcp-server-mysql)） | ✅ 可用 |
| Redis | 缓存 | 官方 redis/mcp-redis（uvx） | ✅ 可用 |
| Elasticsearch | 日志/搜索 | 内置（兼容 [elasticsearch-mcp-server](https://github.com/cr7258/elasticsearch-mcp-server)） | ✅ 可用 |
| MongoDB | 数据库 | 内置（兼容 [mcp-mongo-server](https://github.com/kiliczsh/mcp-mongo-server)） | ✅ 可用 |
| Kubernetes | 容器编排 | 内置 `packages/kubernetes-mcp-server` | ✅ 可用 |
| Apache Kafka | 消息队列 | [mcp-kafka](https://github.com/gAmUssA/mcp-kafka) | 🔜 规划中 |

## 技术栈

- **Electron + React + TypeScript**
- **适配器插件架构**（`electron/main/adapters/`）
- **共享类型**（`shared/types/`，UI 与主进程共用）
- **electron-store** 本地配置持久化

## 快速开始

```bash
cd MiddleTool
npm install
npm run dev                 # 桌面端
npm run mcp-server:start:http   # 本地 HTTP MCP + Web 管理台（自动打开浏览器）
```

Web 管理台地址：`http://127.0.0.1:8080/ui/`

### 前置条件

- Node.js 18+
- RocketMQ 开发环境首次需执行 `npm run rocketmq-mcp:java:build`（需 Maven）

## 使用流程

1. **中间件配置** — 选择适配器，用名称区分环境（如 prod-loki），配置连接参数
2. **Kubernetes 环境** — 配置多环境 K8s 集群连接（dev、sit、uat、prod）
3. **MCP 配置** — 导出 JSON 到 Cursor / Claude Desktop

## 生态集成

### Cursor 集成

在 Cursor 的设置中添加 MCP 配置：

```json
{
  "mcpServers": {
    "middle-tool": {
      "command": "node",
      "args": ["D:\\path\\to\\middle-tool\\packages\\mcp-server\\dist\\index.js"],
      "env": {
        "MIDDLE_TOOL_CONFIG_PATH": "D:\\path\\to\\config\\middle-tool-config.json"
      }
    }
  }
}
```

桌面端「MCP 配置」会自动生成上述配置，只需复制到 Cursor 设置即可。

### Claude Desktop 集成

在 Claude Desktop 的配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "middle-tool": {
      "command": "node",
      "args": ["C:\\path\\to\\middle-tool\\packages\\mcp-server\\dist\\index.js"],
      "env": {
        "MIDDLE_TOOL_CONFIG_PATH": "C:\\path\\to\\config\\middle-tool-config.json"
      }
    }
  }
}
```

### MCP Server

MiddleTool 提供**单一 MCP Server** `middle-tool`，桌面端「MCP 配置」一键导出：

| Server | 包路径 | 能力 |
|--------|--------|------|
| `middle-tool` | `packages/mcp-server` | Loki、MySQL、Redis、RocketMQ、Elasticsearch、MongoDB、Kubernetes 全部 tools |

桌面端「MCP 配置」会根据已启用的 RocketMQ / Redis / Kubernetes 连接自动补充 env。

RocketMQ 由 MiddleTool 桌面端 **内嵌托管 Java Admin 桥接**（安装包预置 JAR，用户无需单独部署）。

详见 [packages/mcp-server/README.md](packages/mcp-server/README.md)。

### Linux 解压部署（对外 IP:端口）

适用于无桌面环境的服务器：对外提供 MCP HTTP/SSE，并内置 Web 管理台维护环境与中间件连接。

```bash
npm run build:linux-mcp
# 产物: release/middle-tool-mcp-linux-x64-*.tar.gz

tar -xzf release/middle-tool-mcp-linux-x64-*.tar.gz
cd middle-tool-mcp
cp config/middle-tool-config.json.example config/middle-tool-config.json
# 也可启动后在 Web 管理台配置
chmod +x bin/start.sh
./bin/start.sh
```

默认监听 `0.0.0.0:8080`：

| 端点 | 地址 |
|------|------|
| Web 管理台 | `http://<IP>:8080/ui/` |
| Streamable HTTP | `http://<IP>:8080/mcp` |
| Legacy SSE | `http://<IP>:8080/sse` |
| 健康检查 | `http://<IP>:8080/health` |

在管理台修改环境/连接后，MCP 可用连接会立即热更新。详见 [deploy/linux/README.md](deploy/linux/README.md)。

### Docker 部署

```bash
cd deploy/docker
cp ../linux/config/middle-tool-config.json.example config/middle-tool-config.json
# 编辑 config/middle-tool-config.json

docker compose up -d --build
# 或项目根目录: npm run docker:up
```

详见 [deploy/docker/README.md](deploy/docker/README.md)。

## 项目结构

```
MiddleTool/
├── packages/mcp-server/           # 统一 MCP（全部中间件 tools）
├── packages/kubernetes-mcp-server/ # Kubernetes MCP Server
├── shared/types/                  # UI 与主进程共享类型
├── electron/main/adapters/        # 适配器注册与校验
└── src/pages/                     # 概览、目录、配置、MCP 导出、环境配置
```

## 扩展新中间件

详见 [docs/EXTENDING.md](docs/EXTENDING.md)。核心步骤：

1. 在 `electron/main/adapters/` 创建 `{name}.ts`
2. 使用 `defineConnectionAdapter()` 或 `definePlannedAdapter()`
3. 在 `registry.ts` 的 `ALL_ADAPTERS` 注册
4. 在 `packages/mcp-server` 实现对应 tools

## 构建与打包

### 开发编译

```bash
npm run build
npm run build:linux-mcp   # Linux MCP 解压包
```

### Windows 安装包（.exe）

```bash
npm install
npm run pack
# 或
npm run build:win
```

产物输出在 `release/` 目录：

| 文件 | 说明 |
|------|------|
| `MiddleTool-Setup-0.1.0.exe` | NSIS 安装程序（可自选安装目录、创建桌面快捷方式） |

**打包流程说明：**

1. 编译 `packages/mcp-server` 统一 MCP Server
2. 编译 Electron 主进程 / 预加载 / 渲染进程
3. 将 mcp-server 及生产依赖打入 `resources/mcp-server/`
4. 使用 electron-builder 生成 NSIS 安装包

**安装后 MCP 配置：**

- 应用内「MCP 配置」导出的 JSON 中，`args` 会指向安装目录下的 `resources/mcp-server/dist/index.js`
- 本机需已安装 **Node.js 18+** 并加入 PATH（Cursor 调用 MCP 时使用 `node` 命令）

**可选：自定义应用图标**

将 `icon.ico` 放入 `resources/` 目录，并在 `package.json` 的 `build.win.icon` 中指定路径。

## 版本历史

详细变更记录请查看 [CHANGELOG.md](CHANGELOG.md)。

### v0.1.0 (2026-08-18)
- 首个正式版本
- 支持 7 种中间件：Loki、RocketMQ、MySQL、Redis、Elasticsearch、MongoDB、Kubernetes
- 完整的 MCP 协议支持
- 桌面端和 Linux 服务器端部署
- Docker 部署支持

## Roadmap

- [ ] Apache Kafka MCP Server 支持
- [ ] Docker Compose 一键启动所有中间件
- [ ] MCP Server 性能优化
- [ ] 更多连接测试工具
- [ ] Web 管理界面

## 相关链接

- [loki-mcp (Gitee)](https://gitee.com/mirrors_grafana/loki-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [贡献指南](CONTRIBUTING.md)
- [变更日志](CHANGELOG.md)