别人花 3 个月重写，我花了 3 天配网关：老系统零改造对接 AI 的野路子

┌─────────────────────────────────────────────────────────────────────┐
│                         AI 平台（控制面）                              │
│                                                                     │
│    ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐   │
│    │ API 服务    │  │ MCP Server  │  │ MCP Tool   │  │ 产品/订阅   │   │
│    │ 管理       │  │ 管理        │  │ 管理       │  │ 管理       │   │
│    └──────┬─────┘  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘   │
│           │               │               │               │          │
│           └───────────────┴───────────────┘               │          │
│                           │                               │          │
│             Nacos AI Admin API (/v3/admin/ai/*)            │          │
│                           │                               │          │
│           ┌───────────────┴───────────────┐               │          │
│           │     Nacos AI Registry 写入     │◄──────────────┘          │
│           │  · mcp-server (元数据)         │   产品 upsert / 订阅审批  │
│           │  · mcp-tools (工具定义)        │                          │
│           │  · mcp-server-versions        │                          │
│           │  · mcp-endpoints (自动生成)    │                          │
│           └───────────────┬───────────────┘                          │
└───────────────────────────┼──────────────────────────────────────────┘
                            │
                            ▼
              ┌─────────────────────────┐
              │   Higress AI 网关        │
              │  · 自动发现 Nacos MCP    │
              │  · 协议转换 HTTP ↔ MCP   │
              │  · 暴露 SSE 端点:        │
              │    /mcp/{name}/sse       │
              └────────────┬────────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │   存量 REST API 服务     │
              │   (Nacos Naming 实例)    │
              │   /api/order/query      │
              │   /api/inventory/list   │
              └─────────────────────────┘

version: "3.8"
services:
  # Redis 7: MCP 会话保持
  redis:
    image: redis:7-alpine
    container_name: mcp-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    networks:
      - mcp-net

  # Nacos 3.2: 配置中心 + AI Registry + Naming
  nacos:
    image: nacos/nacos-server:v3.2.0
    container_name: mcp-nacos
    ports:
      - "8848:8848"  # API
      - "9848:9848"  # gRPC
      - "8081:8080"  # 控制台
    environment:
      - MODE=standalone
      - NACOS_AUTH_ENABLE=true
    volumes:
      - nacos-logs:/home/nacos/logs
    restart: unless-stopped
    networks:
      - mcp-net

  # Higress 2.2: AI 网关
  higress:
    image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:2.2.0
    container_name: mcp-higress
    ports:
      - "8001:8001"  # 控制台
      - "8088:8080"  # HTTP 网关 ⚠️ 注意容器内是 8080，映射到 8088
    environment:
      - REDIS_ADDR=redis:6379
    volumes:
      - ./higress-data:/data  # ⚠️ 必须持久化，否则重启配置丢失
    depends_on:
      nacos:
        condition: service_started
      redis:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - mcp-net

volumes:
  redis-data:
    driver: local
  nacos-logs:
    driver: local

networks:
  mcp-net:
    driver: bridge

# 先获取 Nacos 的访问 Token
NACOS_TOKEN=$(curl -s -X POST "http://localhost:8848/nacos/v1/auth/login" \
  -d "username=nacos&password=nacos" | jq -r '.accessToken')

# 把老系统注册为 Nacos 服务实例
curl -X POST "http://localhost:8848/nacos/v1/ns/instance" \
  -H "Authorization: Bearer ${NACOS_TOKEN}" \
  -d "serviceName=my-old-system" \
  -d "groupName=DEFAULT_GROUP" \
  -d "ip=192.168.1.100" \
  -d "port=8081" \
  -d "ephemeral=false"

{
  "name": "my-old-system",
  "description": "老系统业务查询服务",
  "protocol": "mcp",
  "version": "1.0.0",
  "exportPath": "/sse",
  "mcpSpecificationVersion": "1.0",
  "remoteServerConfig": {
    "serviceProtocol": "HTTP",
    "serviceRef": "my-old-system:1.0.0",
    "exportPath": "/sse"
  }
}

{
  "name": "query_inventory",
  "description": "根据产品编码查询当前库存数量",
  "args": [
    { "name": "productCode", "type": "string", "description": "产品编码", "required": true },
    { "name": "page", "type": "number", "description": "页码，从1开始" }
  ]
}

{
  "url": "/api/health/check",
  "method": "GET"
}

{
  "url": "/api/inventory/get",
  "method": "GET",
  "argsToUrlParam": true
}

{
  "url": "/api/order/create",
  "method": "POST",
  "argsToJsonBody": true,
  "headers": [
    { "key": "Content-Type", "value": "application/json" }
  ]
}

{
  "url": "/users/{{ .args.userId }}/status",
  "method": "PUT",
  "body": "{\"status\":\"{{ .args.status }}\",\"remark\":\"{{ .args.remark }}\"}",
  "headers": [
    { "key": "Content-Type", "value": "application/json" }
  ]
}

┌──────────────────────────────────────────────────────────────────┐
│                      自建平台（控制面）                             │
│                                                                  │
│  ┌────────────────────┐  ┌────────────────────┐                   │
│  │   Vue 前端          │  │   Java 后端          │                   │
│  │  · ApiServiceList   │  │  · McpServerService  │                   │
│  │  · McpServerList    │  │  · ApiServiceService │                   │
│  │  · McpServerDetail  │  │  · NacosAiAdminClient│                   │
│  │  · ToolEditor       │  │  · McpProductSyncApi │                   │
│  └────────┬───────────┘  └──────────┬───────────┘                   │
│           │                         │                              │
│           │    REST API              │  调用 Nacos AI Admin API     │
│           │   /api/mcp/*             │  /v3/admin/ai/mcp            │
│           │                         │                              │
│           └─────────────┬───────────┘                              │
│                         │                                          │
│              ┌──────────┴──────────┐                               │
│              │    MySQL 数据库      │                               │
│              │  · api_service       │                               │
│              │  · mcp_server        │                               │
│              │  · mcp_tool          │                               │
│              │  · product           │                               │
│              └─────────────────────┘                               │
└──────────────────────────────────────────────────────────────────┘

字段            说明
─────────────────────────────────
name            老系统展示名称，如“进销存系统”
nacosServiceName  Nacos Naming 服务名，如“inventory-api”
host            老系统 IP 地址
port            老系统端口
healthCheckPath 健康检查路径，如 /api/health
status          状态：已注册 / 未注册

字段            说明
─────────────────────────────────
name            MCP Server 名称，决定 /mcp/{name}/sse
fromType        来源类型：HTTP_TO_MCP / NATIVE_MCP
apiServiceId    关联哪个老系统
protocol        sse / streamable
version         版本号，固定 1.0.0
status          0=草稿  1=已发布  2=已下线
exposeUrl       对外暴露的 SSE URL
productId       关联的产品市场 ID

字段            说明
─────────────────────────────────
serverId        关联哪个 MCP Server
name            Agent 看到的工具名称
description     工具描述
argsJson        入参定义 JSON
httpMethod      GET/POST/PUT/DELETE
path            接口相对路径
argMapping      参数映射方式：url_param/json_body/form_body/body
headersJson     请求头配置
requestBody     自定义请求体模版

publish()
  ├── Step 1: 校验 MCP 名称合法性
  │     ↳ 只允许英文、数字、-、_、/、.，最长 128 字符
  │
  ├── Step 2: 校验关联的老系统已注册到 Nacos
  │     ↳ 如果还没注册，自动调用 ApiServiceService.register() 注册
  │
  ├── Step 3: 查询该 Server 下所有 Tool
  │     ↳ SELECT * FROM mcp_tool WHERE server_id = ?
  │
  ├── Step 4: 组装三份 Nacos Spec JSON
  │     ├── buildServerSpecification() → mcp-server.json
  │     │     { name, description, protocol, version,
  │     │       remoteServerConfig: { serviceRef, serviceProtocol } }
  │     │
  │     ├── buildToolSpecification() → mcp-tools.json
  │     │     遍历每个 Tool，组装扁平 HTTP 配置：
  │     │     { url, method, headers, argsToUrlParam/argsToJsonBody/body, ... }
  │     │
  │     └── buildEndpointSpecification() → mcp-endpoints.json
  │           { exportPath: "/sse", ... }
  │
  ├── Step 5: 调用 NacosAiAdminClient 写入 Nacos AI Registry
  │     ↳ createMcpServer(serverSpec, toolSpec, endpointSpec)
  │     ↳ 底层调用 Nacos 3.2 的 /v3/admin/ai/mcp 接口
  │
  ├── Step 6: 生成对外暴露的 SSE URL
  │     ↳ exposeUrl = "http://{gateway}:8088/mcp/{name}/sse"
  │
  ├── Step 7: 同步到产品市场
  │     ↳ McpProductSyncApi.upsert() → 创建/更新 product 记录
  │     ↳ 用户可以在产品市场看到这个 MCP Server，申请订阅
  │
  └── Step 8: 更新数据库状态
        ↳ mcp_server.status = 1（已发布）

private JSONObject buildFlatHttpConfig(McpTool tool) {
    JSONObject config = new JSONObject();
    config.put("url", tool.getPath());
    config.put("method", tool.getHttpMethod());

    // 参数映射方式
    switch (tool.getArgMapping()) {
        case "url_param":   config.put("argsToUrlParam", true);  break;
        case "json_body":   config.put("argsToJsonBody", true);  break;
        case "form_body":   config.put("argsToFormBody", true);  break;
        case "body":        config.put("body", tool.getRequestBody()); break;
    }

    // 请求头
    if (StrUtil.isNotBlank(tool.getHeadersJson())) {
        config.put("headers", JSON.parseArray(tool.getHeadersJson()));
    }
    return config;
}

public void publish(McpServer server) {
    // 组装三份 Spec
    String serverSpec = buildServerSpecification(server);
    String toolSpec = buildToolSpecification(tools);
    String endpointSpec = buildEndpointSpecification(server);

    // 一键写入 Nacos
    nacosAiAdminClient.createMcpServer(serverSpec, toolSpec, endpointSpec);

    // 生成 exposeUrl
    String exposeUrl = String.format("http://%s:%d/mcp/%s/sse",
        gatewayHost, gatewayPort, server.getName());

    // 同步产品市场
    productSyncApi.upsert(Product.builder()
        .type("mcp_server")
        .name(server.getName())
        .exposeUrl(exposeUrl)
        .build());

    // 更新状态
    server.setStatus(1);
    mcpServerMapper.updateById(server);
}

offline()
  ├── 1. 调用 NacosAiAdminClient.deleteMcpServer() 删除 Nacos 中的 MCP 声明
  ├── 2. 产品置为下架（status=inactive）
  └── 3. 更新 mcp_server.status = 2（已下线）

# 预览接口
GET /api/mcp/servers/{id}/preview-nacos-spec

# 返回三份 JSON：
{
  "serverSpec": { ... },
  "toolSpec": { ... },
  "endpointSpec": { ... }
}

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

{
  "headers": [
    { "key": "Content-Type", "value": "application/json" },
    { "key": "Authorization", "value": "Bearer {{ ${nacos.my-token/DATA}.token }}" }
  ]
}

curl -N http://localhost:8088/mcp/my-old-system/sse

npx @modelcontextprotocol/inspector
# 在弹出的界面中：
# Transport 选择 SSE
# URL 填 http://localhost:8088/mcp/my-old-system/sse

{
  "mcpServers": {
    "my-old-system": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-proxy", "http://localhost:8088/mcp/my-old-system/sse"]
    }
  }
}