# mcp-mix

**Repository Path**: syq821781113/mcp-mix

## Basic Information

- **Project Name**: mcp-mix
- **Description**: 转发mcp请求到mcp或者http服务
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 网关平台

本项目是一个 MCP 整合平台，囊括管理、用户计费、MCP 服务的完整链路。

技术栈：Java 21 · Spring Boot 3.3 · MyBatis-Plus · Redis · MCP SDK 2.x

## 模块结构

| 模块 | 协议 | 端口 | Context Path | 职责 |
|------|------|------|--------------|------|
| `mcp-common` | — | — | — | 公共库 |
| `mcp-config` | — | — | — | Redis / MyBatis-Plus / 异常 / CORS |
| `mcp-manage` | **HTTP** | 3893 | `/manage` | 配置系统：登记上游、同步工具、管理端 |
| `mcp-gateway` | **MCP 入口** | 3890 | `/` | **鉴权 + 按端点反向代理**（优先 Redis 路由，回落 `s_mcp`） |
| `mcp-server` | **MCP** | 3895 | `/` | **业务 MCP 封装**：代码注册 Tool，Streamable HTTP |
| `mcp-http` | **MCP** | 3894 | `/` | **HTTP→MCP**：`s_mcp(impl_type=http)` / `s_mcp_tool` 配置转 Tool |
| `mcp-user` | **HTTP** | 3892 | `/api` | C 端用户 / 计费 |
| `mcp-job` | **HTTP** | 3891 | `/` | **XXL-JOB 执行器**：定时把 `s_mcp` 端点同步到 Redis |

## 架构关系

```
配置面:
  管理 UI ──HTTP──▶ mcp-manage（写 s_mcp / s_mcp_tool）
                      │ 可从业务 MCP 自动拉取 tools 写入 s_mcp_tool

调度面:
  XXL-JOB Admin ──▶ mcp-job（读 s_mcp → 写 Redis mcp:gateway:routes）

运行面:
  调用方 ──MCP──▶ mcp-gateway（鉴权；优先 Redis 路由，回落 DB）
                      │ /mcp/{id} 反向代理到 endpoint_url
                      ├──────────────▶ mcp-server（自定义业务 Tool）
                      └──────────────▶ mcp-http（HTTP→MCP Tool）
```

要点：

- **mcp-gateway**：只做鉴权与转发；入口为 `/mcp/{mcpId}`；目标地址优先 `mcp:gateway:routes`，未命中再读 `s_mcp.endpoint_url`。
- **mcp-job**：XXL-JOB 执行器；任务 `mcpEndpointSyncJob` 全量同步启用中的 MCP 端点到 Redis。
- **mcp-server / mcp-http**：具体业务场景封装，对外提供 Streamable HTTP MCP，被登记进 `s_mcp` 后由网关转发。
- **工具集合**：统一 `s_mcp_tool`；`impl_type=http` 时填 method/url/header/param。管理端同步仅对原生 MCP 拉取 tools。

| 服务 | 端口 |
|------|------|
| mcp-gateway | 3890 |
| mcp-manage | 3891 |
| mcp-server | 3892 |
| mcp-user | 3893 |
| mcp-job | 3894 |
| mcp-http | 3899 |

### mcp-server 端点（代码注册）

路径格式：`/mcp/{code}`。登记 `s_mcp.endpoint_url` 时填完整地址。

| 端点 | serverInfo | Tools | endpoint_url 示例 |
|------|------------|-------|-------------------|
| `/mcp/demo` | `mcp-server-demo` | `ping`、`echo`、`add` | `http://host:3892/mcp/demo` |
| `/mcp/util` | `mcp-server-util` | `now`、`uuid`、`md5`、`json_pretty` | `http://host:3892/mcp/util` |

新增业务端点：实现 `BusinessToolProvider`（`code` / `serverName`），在方法上加 `@McpTool` / `@McpToolParam` 即可（Spring AI 注解扫描）。

### mcp-http 端点（HTTP→MCP）

路径格式：`/mcp/{name}`。端点**完全由库配置**：启用且 `impl_type=http` 的 `s_mcp` → `/mcp/{name}`，其下 `s_mcp_tool` 即为 Tools。改配置后 `POST /internal/reload`（或重启）生效。

| 端点 | serverInfo | 库中 name | endpoint_url 示例 |
|------|------------|-----------|-------------------|
| `/mcp/suggest` | `mcp-http-suggest` | `suggest` | `http://host:3899/mcp/suggest` |
| `/mcp/match` | `mcp-http-match` | `match` | `http://host:3899/mcp/match` |

新增端点：管理端创建 `impl_type=http` 的 MCP + HTTP 接口即可。

### mcp-job / XXL-JOB 配置说明

1. 自行部署 [XXL-JOB Admin](https://github.com/xuxueli/xxl-job)（默认占位：`http://127.0.0.1:8080/xxl-job-admin`）。
2. Admin 中新增执行器，AppName 填 `mcp-job`（与 `xxl.job.executor.appname` 一致）。
3. 新增任务：运行模式 Bean，JobHandler = `mcpEndpointSyncJob`，按需配置 Cron（如每分钟）。
4. 修改 `mcp-job` 的 `xxl.job.admin.addresses` / `accessToken` 与 Admin 对齐后启动本模块。

## 默认登录账号

| 端 | 账号 | 密码 |
|------|------|------|
| Manage（管理端） | `admin` | `admin` |
| User（用户端） | `13211118278` | `123456` |