# 慧策 · MCP 协议中台

> **一句话**：一套 MCP 协议基础设施——让产线自助注册数据源和 Tool，下游 Agent 通过标准 MCP 协议发现和调用。平台是"协议管道"，不承载任何业务逻辑。

---

## 目录

- [定位与边界](#定位与边界)
- [核心概念：MCP 是什么](#核心概念mcp-是什么)
- [架构总览](#架构总览)
- [核心设计](#核心设计)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [产线接入](#产线接入)
- [文档索引](#文档索引)
- [项目路线图](#项目路线图)

---

## 定位与边界

### 为什么做 MCP 协议中台？

公司有多个产线（跨境 ERP、国内电商、仓储 WMS、财务结算……），每个产线都有数据查询需求。如果每接一个产线就 fork 一份 MCP Server 改 Tool 实现，会陷入"每接一个产线就改代码"的困境。

**核心思路**：做一个只负责 MCP 协议实现和工具调度框架的基础设施。平台定义协议契约，产线按契约自助接入。

### 平台做什么、不做什么

```
                    ┌─────────── 本平台范围 ───────────┐
                    │                                  │
  AI Agent ──MCP──→ │  MCP Protocol   Tool Registry    │ ←── API 契约 ←── 产线
                    │  Auth / Rate    Cache / Degrade  │
                    │  Adapter Framework               │
                    │  Admin Console  Observability    │
                    │                                  │
                    └────────────┬─────────────────────┘
                                 │ Data Source Adapter SPI
                                 ▼
              ┌──────────────────────────────────────┐
              │         产线数据源（产线自管）         │
              │  MySQL / Doris / StarRocks / HTTP API │
              │  Redis / ES / ...                    │
              └──────────────────────────────────────┘
```

| ✅ In Scope | ❌ Out of Scope |
|-------------|-----------------|
| MCP 协议完整实现（基于 Spring AI MCP Server 1.1.2） | 任何实例 Tool 的 SQL/API 逻辑（产线做） |
| Tool 注册中心（CRUD + 版本管理 + 热加载） | ETL 管道 / 宽表建设 / 数据清洗 |
| 数据源适配框架（MySQL/PG/Doris/HTTP/Redis） | 上游 API 对接（ERP、BI、第三方） |
| 中间件管道（鉴权/限流/缓存/降级/日志/监控） | 业务公式 / 算法 / 规则 |
| 管理控制台（数据源管理 + Tool 管理 + 监控大盘） | OAuth2.0 / RBAC / 多租户（Phase 2） |
| 产线 SDK（Java + Python） | 产线接入辅导 / Tool 开发 |

> **关键设计原则**：平台不懂业务。Tool 只是 MySQL 里的一条配置记录（名称 + JSON Schema + 数据源引用 + 查询模板）。产线决定 Tool 叫什么、SQL 怎么写、缓存 TTL 设多少。

---

## 核心概念：MCP 是什么

**MCP（Model Context Protocol）** 是 AI Agent 与外部工具/数据交互的**标准协议**，由 Anthropic 开放。类比 USB-C：在 MCP 之前，每个 AI 应用对接数据源都要写定制胶水代码；有了 MCP，Agent 通过统一的 `tools/list` → `tools/call` 协议发现和调用工具。

```mermaid
flowchart LR
    A["🤖 AI Agent<br/>Claude Desktop / LangChain / OpenAI"] -->|"tools/list<br/>tools/call<br/>JSON-RPC 2.0"| B["🔌 MCP 协议中台<br/>Spring AI MCP Server"]
    B -->|"Adapter SPI"| C["🗄️ MySQL"]
    B -->|"Adapter SPI"| D["🗄️ Doris"]
    B -->|"Adapter SPI"| E["🌐 HTTP API"]
    B -->|"Adapter SPI"| F["📦 Redis"]
```

> **关键设计原则**：Agent 管"意图"（理解用户要什么），平台管"协议"（MCP 实现 + Tool 路由 + 中间件），产线管"数据"（注册数据源 + 写 SQL/配置）。

---

## 架构总览

### 分层架构

```mermaid
flowchart TB
    subgraph Agent["AI Agent 层（外部）"]
        Claude["Claude Desktop"]
        LangChain["LangChain Client"]
        OpenAI["OpenAI Agent SDK"]
    end

    subgraph Platform["MCP 协议中台（本平台）"]
        direction TB

        subgraph Protocol["MCP Protocol Layer"]
            Handshake["initialize 握手<br/>协议版本协商 · 能力交换"]
            JSONRPC["JSON-RPC 2.0 Router<br/>tools/list · tools/call · tools/schema<br/>resources/list · resources/read"]
            Transport["Transport: HTTP SSE / Streamable HTTP"]
        end

        subgraph Middleware["Middleware Pipeline（Filter Chain）"]
            direction LR
            Auth["鉴权<br/>API Key + BCrypt"] --> RateLimit["限流<br/>Token Bucket"]
            RateLimit --> Cache["缓存<br/>Caffeine L1 + Redis L2"]
            Cache --> Degrade["降级<br/>4 级状态机"]
            Degrade --> Log["日志·监控<br/>TraceId · Prometheus"]
        end

        subgraph Core["Tool Engine"]
            Dispatcher["ToolDispatcher<br/>Tool 解析 · 路由"]
            Registry["Tool Registry<br/>元数据管理 · 版本管理 · 热加载"]
            Executor["Tool Executor<br/>参数校验 · 模板渲染<br/>结果映射 · 输出校验"]
        end

        subgraph Adapter["Data Source Adapter Framework"]
            SPI["Adapter SPI<br/>接口契约 · 连接池 · 健康检查 · 查询护栏"]
            Builtin["内置适配器<br/>MySQL · PostgreSQL · Doris · HTTP · Redis"]
        end

        subgraph Admin["Admin Console"]
            ToolMgmt["Tool 管理"]
            DSMgmt["数据源管理"]
            Dashboard["监控大盘"]
            Alarm["告警配置"]
        end
    end

    subgraph Datasources["产线数据源（产线自管）"]
        MySQL_DS["MySQL 产线 A"]
        Doris_DS["Doris 产线 B"]
        HTTP_API["HTTP API 产线 C"]
        Redis_DS["Redis 产线 D"]
    end

    Agent -->|"MCP Protocol"| Handshake
    Handshake --> JSONRPC
    JSONRPC --> Auth
    Middleware --> Dispatcher
    Dispatcher --> Registry
    Dispatcher --> Executor
    Executor --> SPI
    Admin --> Registry
    Admin --> DSMgmt
    SPI --> Builtin
    Builtin --> Datasources
```

### 分层职责

| 层级 | 核心职责 | 边界约束 |
|------|---------|---------|
| **MCP Protocol 层** | `initialize` 握手、JSON-RPC 2.0 Router、SSE/Streamable HTTP Transport（基于 Spring AI MCP Server 1.1.2，不重复造轮子） | 协议层不关心 Tool 从哪来、数据源是什么 |
| **Middleware Pipeline** | 鉴权 → 限流 → 缓存 → 降级 → 日志监控，Filter Chain 模式，请求必经路径 | 全配置驱动，产线在 Tool 配置中勾选策略 |
| **Tool Engine** | ToolDispatcher 解析路由、Tool Registry 元数据管理、Tool Executor 参数校验+模板渲染+结果映射 | 通过 ToolDispatcher 解耦 Protocol 和 Registry |
| **Adapter Framework** | Adapter SPI 接口契约 + 5 种内置适配器 + 查询护栏（max_rows/timeout/DDL 黑名单） | 平台只做适配，不关心数据内容 |
| **Admin Console** | 数据源管理、Tool 注册管理、监控大盘、告警配置（Vue 3 + Arco Design） | 面向产线管理员自助操作 |

---

## 核心设计

### Tool = 元数据，不是代码

从平台视角看，Tool 只是一条 MySQL 记录。产线通过 API 或控制台注册 Tool：

```json
{
  "id": "my_query_tool",
  "name": "my_query_tool",
  "description": "查询最近 N 条订单（给 LLM 看的描述）",
  "parameters": {
    "type": "object",
    "properties": {
      "limit": { "type": "integer", "default": 20, "maximum": 100 }
    }
  },
  "datasource_id": "ds_my_line",
  "query": {
    "type": "SQL",
    "template": "SELECT a, b, c FROM orders ORDER BY created_at DESC LIMIT {{.limit}}"
  },
  "cache": { "level": "BOTH", "l1_ttl_sec": 60, "l2_ttl_sec": 300 }
}
```

平台做的事：校验参数合法性 → 渲染模板 → 通过 Adapter 执行 → 映射结果 → 返回。产线决定一切业务逻辑。

### 数据模型（6 张核心表）

```mermaid
erDiagram
    Datasource ||--o{ Tool : "绑定"
    Tool ||--o{ ToolVersion : "版本"
    Tool ||--o{ CachePolicy : "缓存策略"
    Tool ||--o{ DegradePolicy : "降级策略"
    Tool ||--o{ InvocationLog : "调用记录"

    Datasource {
        string id PK "ds_example"
        string type "DORIS / MYSQL / PG / HTTP / REDIS"
        json connection "主机·端口·库名·凭据引用"
        json pool_config "连接池配置"
        string status "ONLINE / OFFLINE / ERROR"
    }

    Tool {
        string id PK "my_tool_001"
        string name "对 Agent 可见的工具名"
        string description "详细的工具描述给 LLM 看"
        json parameters "JSON Schema — 输入参数定义"
        string datasource_id FK "绑定数据源"
        string query_template "SQL 或 HTTP URL 模板"
        json result_mapping "字段映射"
        json transform "字段级转换规则"
        string status "DRAFT / ONLINE / OFFLINE"
    }

    InvocationLog {
        bigint id PK
        string tool_id FK
        string trace_id "全链路追踪 ID"
        int latency_ms "执行耗时"
        boolean cache_hit "是否命中缓存"
        int degrade_level "降级级别"
        timestamp created_at "TTL 7 天"
    }
```

### 中间件能力（平台"赠送"给产线的）

| 能力 | 说明 |
|------|------|
| **鉴权** | API Key + BCrypt，基于 `mcp-server-security` 0.0.5 + Spring Security |
| **限流** | Token Bucket，3 级：全局 / 产线 / Tool |
| **缓存** | Caffeine L1（本地 <1ms）+ Redis L2（分布式共享），TTL 产线可配 |
| **降级** | 4 级自动降级：过期缓存 → 仅本地缓存 → 静态默认值 → 503 拒绝 |
| **可观测性** | 自动埋点：调用量/成功率/P95/缓存命中率/降级次数，Prometheus + Grafana |
| **调用日志** | `InvocationLog` 表，产线可查询"Agent 调了我的 Tool 传了什么参数、返回了什么" |

### 三种接入方式

| 方式 | 适用场景 | 产线工作量 |
|------|---------|:---:|
| **SQL 模板** | 单表查询、简单 JOIN、聚合 | 写 1 条 SQL + 填表单 |
| **HTTP 模板** | 调用产线已有 REST API | 填 URL 模板 |
| **SDK 插件** | 多步聚合、复杂计算 | 写 50-200 行 Java/Python |

---

## 技术栈

| 层级 | 选型 | 版本 | 理由 |
|------|------|:---:|------|
| **MCP 协议实现** | Spring AI MCP Server | 1.1.2 | 公司内部 Demo 已验证，内置 JSON-RPC Router + Transport + `initialize` 握手。**不重复造协议轮子** |
| **鉴权** | `mcp-server-security` + Spring Security | 0.0.5 | 社区库，Demo 已验证。API Key + BCrypt |
| **基础框架** | Java 21 + Spring Boot | 3.4.7 | 公司 Java 技术栈，与内部 Demo 对齐版本 |
| **管理控制台前端** | Vue 3 + Vite + Arco Design | — | 轻量、公司前端组技术栈 |
| **元数据存储** | MySQL 8.0 | — | Tool 配置、数据源配置、调用日志 |
| **缓存** | Caffeine (L1) + Redis 6.2 (L2) | — | L1 本地 <1ms，L2 分布式共享 |
| **监控** | Micrometer + Prometheus + Grafana | — | Spring Boot 原生集成 |
| **配置中心** | Nacos 2.x | — | 公司已有，凭据 + 配置存储 |
| **部署** | Docker Compose（开发）+ K8s（生产） | — | 与公司基础设施对齐 |

> **基础框架选择**：Spring AI MCP Server 1.1.2 已完整实现 MCP 2024-11-05 协议。本平台不重复实现协议层，而是在 Spring AI 之上做三件事：(1) 动态 Tool 注册（替换 `@McpTool` 静态注解），(2) 数据源适配与模板执行，(3) 通用中间件管道。

---

## 项目结构

```
intent_plan/
├── docs/
│   └── superpowers/
│       └── specs/
│           ├── 2026-07-16-mcp-platform-plan.md              # MCP 协议中台建设计划（主文档）
│           └── 2026-07-16-cross-border-mcp-boundary-design.md # 产线协作契约
├── mcp-server/                   # MCP Server 核心（Spring Boot）
│   └── src/main/java/com/wangdian/mcp/
│       ├── protocol/             # MCP 协议层（Spring AI 集成）
│       ├── registry/             # Tool 注册中心（动态注册 + 版本管理）
│       ├── executor/             # Tool 执行器（校验 + 模板 + 映射）
│       ├── adapter/              # 数据源适配框架（SPI + 内置适配器）
│       ├── middleware/           # 中间件管道（鉴权/限流/缓存/降级）
│       ├── admin/                # 管理控制台 API（/admin/*）
│       └── sdk/                  # 产线 SDK（Java）
├── mcp-server-admin/             # 管理控制台前端（Vue 3 + Arco Design）
├── mcp-sdk-python/               # 产线 SDK（Python）
├── docker-compose.yml            # 本地开发环境
└── README.md
```

---

## 快速开始

> ⚠️ 项目开发中，以下为预期启动流程。

### 前置条件

- JDK 21 + Maven 3.9+
- Docker 20.10+ & Docker Compose 2.20+
- 公司内网访问（Nacos / MySQL / Redis）

### 本地开发

```bash
# 1. 克隆项目
git clone <repo-url> && cd intent_plan

# 2. 启动开发环境中间件
docker compose up -d mysql redis nacos-standalone

# 3. 初始化数据库
# 执行 docs/superpowers/specs/ 下的 DDL 脚本

# 4. 启动 MCP Server
cd mcp-server
mvn spring-boot:run

# 5. 验证 MCP 协议
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":0}'
```

### 服务端口

| 服务 | 端口 | 说明 |
|------|:---:|------|
| MCP Server | 8080 | MCP JSON-RPC 端点 (`:8080/mcp`) |
| Admin Console | 8080 | 管理控制台 (`:8080/admin/*`) |
| MySQL | 3306 | 元数据存储 |
| Redis | 6379 | L2 缓存 |
| Nacos | 8848 | 配置中心 / 服务发现 |

---

## 产线接入

产线接入只需 3 步，无需平台开发介入：

### Step 1：注册数据源

```bash
curl -X POST http://mcp-platform:8080/api/v1/datasources \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -d '{
    "id": "ds_my_line",
    "type": "MYSQL",
    "connection": {
      "host": "10.x.x.x", "port": 3306, "database": "my_db",
      "credential_ref": "nacos:my-line/db-pwd"
    },
    "pool_config": { "min": 2, "max": 10, "timeout_sec": 30 }
  }'
```

### Step 2：注册 Tool

```bash
curl -X POST http://mcp-platform:8080/api/v1/tools \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -d '{
    "id": "my_query",
    "name": "my_query",
    "description": "查询我的订单数据",
    "parameters": { "type": "object", "properties": { "limit": { "type": "integer" } } },
    "datasource_id": "ds_my_line",
    "query": { "type": "SQL", "template": "SELECT * FROM orders LIMIT {{.limit}}" }
  }'
```

### Step 3：Agent 调用

Tool 注册后 30s 内全实例生效。下游 Agent 通过标准 MCP 协议调用：

```
Agent → POST /mcp
  {"jsonrpc":"2.0", "method":"tools/list", "id":1}
Agent ← {"jsonrpc":"2.0", "result":{"tools":[..., {"name":"my_query", ...}]}, "id":1}

Agent → POST /mcp
  {"jsonrpc":"2.0", "method":"tools/call", "params":{"name":"my_query","arguments":{"limit":20}}, "id":2}
Agent ← {"jsonrpc":"2.0", "result":{"content":[{"type":"text","text":"[{\"col\":\"val\"}]"}]}, "id":2}
```

---

## 文档索引

| 文档 | 用途 | 读者 |
|------|------|------|
| [MCP 协议中台建设计划](docs/superpowers/specs/2026-07-16-mcp-platform-plan.md) | 平台架构、WBS 分解、里程碑、风险 | 全员 |
| [MCP 服务责任边界设计](docs/superpowers/specs/2026-07-16-cross-border-mcp-boundary-design.md) | 产线协作契约、接入协议 | 平台团队 + 产线团队 |

---

## 项目路线图

```mermaid
gantt
    title MCP 协议中台路线图
    dateFormat  YYYY-MM-DD
    axisFormat  W%W

    section M1 · 协议核心（W1）
    Spring AI 集成 + 动态 Tool 注册 POC  :m1, 2026-07-20, 5d

    section M2 · 工具引擎（W2）
    Tool Registry + Executor + Adapter    :m2, after m1, 5d

    section M3 · 生产就绪（W3）
    Middleware Pipeline + 降级演练        :m3, after m2, 5d

    section M4 · 管理控制台（W4-W5）
    Admin Console + SDK                   :m4, after m3, 10d

    section M5 · 上线（W6）
    集成测试 + 压测 + 灰度                :m5, after m4, 5d
```

| 阶段 | 目标 | 时间 |
|------|------|:---:|
| **Phase 1 · MVP** | MCP 协议中台核心能力：动态 Tool 注册 + 5 种数据源适配器 + 中间件管道 + 管理控制台 + SDK | 6 周 |
| **Phase 2 · 增强** | 插件热加载 + OAuth2.0/RBAC/多租户 + 自定义 ClassLoader 隔离 + 更多适配器（ES/Mongo/GraphQL） | 3-6 月 |
| **Phase 3 · 商业化** | MCP Marketplace + 计费计量 + 多集群调度 + 数据脱敏镜像 | 6 月+ |

---

> **项目状态**：`设计阶段 · 待评审` | **团队**：2.5 人（TL + BE + FE 共享）| **周期**：6 周
>
> 有问题？先看 [MCP 协议中台建设计划](docs/superpowers/specs/2026-07-16-mcp-platform-plan.md)。