01项目概述
v1 已跑通「WorkBuddy 连接器 → MCP 端点 → 认证 → 租户隔离 → 审计」全链路，但工具为硬编码 Java @Tool。v2 目标是平台化。
零代码 API-to-MCP
租户登记 REST 接口 → 自动生成 MCP 工具 → AI 客户端直接调用，无需写代码
多租户 SaaS 化运营
租户全生命周期管理 + 数据严格隔离（tenant_id）+ 按租户计量
企业级治理
密钥授权、工具白名单、限流配额、审计追溯、监控告警一体化
02竞品调研结论
调研 GitHub 5 个代表性开源项目：PlexMCP、leandro-jm/mcp-gateway、SageMCP、reaatech/mcp-gateway、isanjosgon/mcp-gateway。
| 能力 | 竞品普及度 | 本期采纳 | 说明 |
|---|---|---|---|
| 多租户组织 + 数据隔离 | 5 / 5 | 采纳 | v1 已实现，v2 补管理能力 |
| API Key 管理（哈希/吊销/轮换/作用域） | 5 / 5 | 采纳 | v1 已有基础，补 UI 和有效期 |
| REST/OpenAPI → MCP 工具动态注册 | 1 / 5 | 采纳 · 核心差异点 | 手工登记 + JSON Schema 参数定义；OpenAPI 批量导入放远期 |
| 工具白名单 / 权限策略 | 5 / 5 | 采纳 | 租户维度工具开关，tools/list 只返回已授权工具 |
| 每租户限流 + 配额 | 4 / 5 | 采纳 | 令牌桶 RPM + 日配额，单机内存实现（不引 Redis） |
| 审计日志（含防篡改哈希链） | 5 / 5 | 采纳 | v1 已落库；哈希链放远期 |
| 使用分析看板 / 计量 | 5 / 5 | 采纳 | 数据驾驶舱看板（4.6 节） |
| 管理后台 Web UI | 4 / 5 | 采纳 | 平台管理员使用 |
| 凭据 / 密钥加密存储（AES 字段级） | 2 / 5 | 采纳 | 后端接口的鉴权凭据 AES 加密落库 |
| OAuth 对接上游服务 | 3 / 5 | 远期 | 本期后端接口鉴权支持 none / basic / bearer / header 四种 |
| 防篡改审计哈希链 | 2 / 5 | 远期 | — |
| 计费 / 套餐 | 2 / 5 | 远期 | 本期先做用量计量，为计费留数据基础 |
| 多上游 MCP 聚合 / 代理 | 3 / 5 | 不做 | 定位是工具平台不是网关 |
03总体架构
AI 客户端层
WorkBuddy 连接器各租户独立 mcp.json + API Key
· · ·
其他 MCP 客户端Claude / 自研 Agent
dm-mcp-java · Spring Boot 单实例
NginxHTTPS 接入
→
认证过滤器X-API-Key / 路径租户解析
→
限流拦截器令牌桶 RPM + 日配额
→
工具白名单过滤租户可见工具集
→
动态工具引擎API 工具 → HTTP 调用租户后端
+
内置工具层Java @Tool（sys_*）
管理面 /admin/api/**JWT 登录 · 租户/密钥/工具/配额管理 · 审计查询 · 统计看板
管理后台前端 code/adminVue + Element UI + ECharts
公共层TenantContext · MyBatis-Plus 租户插件 · 审计切面 · Micrometer 指标
外部依赖
租户后端业务系统REST API
MySQL 共享库tenant_id 隔离
Dockeramd64/arm64 · 阿里云镜像仓库
请求链路
1AI 客户端Nginx → POST /mcp（X-API-Key）
2认证过滤器解析 Key → 租户 → TenantContext
3限流拦截器RPM 令牌桶 + 日配额，超限 429
4tools/list内置 ∪ API 工具，白名单过滤
5tools/call引擎拼装 HTTP → 调租户后端 API
6审计切面租户/工具/入参摘要/状态/耗时 落库
04功能清单
优先级定义：P0 本期必须 P1 本期应做 P2 远期规划
4.1 多租户管理
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | 租户 CRUD | P0 | 租户编码（tenantId）、名称、联系人、状态（启用/停用） |
| 2 | 租户停用/启用 | P0 | 停用后所有请求 403，Key 全部失效 |
| 3 | 租户配额参数 | P0 | RPM 限流阈值、日调用配额，随租户可调 |
| 4 | 租户详情聚合页 | P1 | 基本信息 + Key 列表 + 工具授权 + 近期用量 |
| 5 | 租户级配额告警阈值 | P1 | 日用量达阈值百分比时看板标红 |
| 6 | 独立库隔离模式 | P2 | 本期维持共享库 + tenant_id（TenantLineInnerInterceptor） |
4.2 后端 API 接口服务配置（API 转 MCP 工具引擎）★ 核心
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | API 工具登记 | P0 | 工具名（英文标识）、描述、HTTP 方法、URL、超时时间 |
| 2 | 参数定义 | P0 | JSON Schema 定义 query/path/body 参数 → 自动生成 MCP inputSchema |
| 3 | 后端鉴权配置 | P0 | none / Basic / Bearer Token / 自定义 Header；凭据 AES 加密落库 |
| 4 | 请求拼装与调用 | P0 | 按定义渲染 URL/Headers/Body，RestClient 调用，超时控制（默认 10s） |
| 5 | 响应处理 | P0 | JSON 原样返回；可配置响应字段裁剪（白名单路径）与错误映射 |
| 6 | 工具启用/停用 | P0 | 停用立即从 tools/list 消失（下发 tools/list_changed 通知） |
| 7 | 工具测试控制台 | P1 | 后台内填参试调，展示实际 HTTP 请求/响应 |
| 8 | 变更热生效 | P0 | 新增/修改工具无需重启，动态 ToolCallback 注册刷新 |
| 9 | OpenAPI/Swagger 批量导入 | P2 | 解析 openapi.json 批量生成工具定义 |
| 10 | SSE/流式后端接口支持 | P2 | 本期仅支持 REST 同步接口 |
技术要点：内置工具用 @Tool 静态注册；API 工具通过自定义
DynamicToolCallbackProvider 实现，启动时从 DB 加载、后台保存后触发刷新。工具命名空间：内置 sys_*，API 工具 api_*。4.3 端点接口配置（租户 MCP 端点 + 工具集）
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | 租户端点管理 | P0 | 固定端点 /mcp/{tenantId}，展示接入地址、mcp.json 样例（一键复制） |
| 2 | 工具授权白名单 | P0 | 租户维度勾选可用工具；未授权工具 tools/list 不可见、tools/call 拒绝 |
| 3 | 端点连接信息展示 | P1 | 当前在线会话数（Mcp-Session-Id 统计）、最近连接时间 |
| 4 | 多端点（一租户多套工具集） | P2 | 本期一租户一端点一工具集 |
4.4 密钥授权管理
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | Key 生成/列表/吊销 | P0 | v1 已有 API；v2 补管理 UI，Key 明文仅创建时展示一次 |
| 2 | Key 有效期 | P1 | 过期时间字段，过期自动失效 |
| 3 | Key 轮换 | P1 | 新旧 Key 宽限期并存（如 24h），平滑切换 |
| 4 | Key 备注/归属 | P0 | 备注名（如"张三-WorkBuddy"）、最后使用时间 |
| 5 | Key 级限流覆盖 | P2 | 本期限流到租户级 |
| 6 | 多级权限（平台/租户管理员） | P2 | 本期仅平台管理员（mcp_admin_user + JWT 登录） |
4.5 审计日志
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | 调用审计落库 | P0 | v1 已有：租户、Key、工具名、入参摘要、状态、耗时、错误信息 |
| 2 | 审计查询界面 | P0 | 按租户/工具/状态/时间范围筛选，分页 |
| 3 | 审计详情 | P0 | 单次调用完整请求/响应（敏感字段脱敏） |
| 4 | 管理操作审计 | P1 | 管理员的租户/密钥/工具配置变更也记审计 |
| 5 | 审计导出 CSV | P1 | 按筛选条件导出 |
| 6 | 防篡改哈希链 | P2 | 参考 reaatech 实现，远期 |
| 7 | 日志保留策略 | P1 | 可配置保留天数，定时清理归档 |
4.6 数据驾驶舱看板
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | 核心指标卡 | P0 | 今日调用总量、成功率、平均耗时、活跃租户数、限流命中次数 |
| 2 | 调用趋势图 | P0 | 按天/按小时调用量与成功率双轴折线图 |
| 3 | 租户用量排行 | P0 | Top 10 租户调用量柱状图 + 配额使用率进度条 |
| 4 | 工具热度 Top | P1 | 工具调用排行、各工具平均耗时/P99 |
| 5 | 错误分析 | P1 | 错误分布（按工具/类型）、近 7 天失败率趋势 |
| 6 | 数据明细下钻 | P1 | 图表点击下钻到对应审计日志列表 |
| 7 | 定期报表推送 | P2 | 日报/周报推送（对接现有通知渠道） |
技术：Micrometer + 日汇总任务（
mcp_usage_daily 按天聚合，看板查汇总表，避免大表实时聚合）。4.7 治理能力（增强项）
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | 租户级 RPM 限流 | P0 | 令牌桶（单机内存，Guava RateLimiter），超限 429 + Retry-After |
| 2 | 租户级日配额 | P0 | 计数器（内存 + 落库兜底），超限返回配额用尽错误 |
| 3 | 用量计量 | P0 | 每次调用计数入 mcp_usage_daily（租户×工具×天），为计费留数据 |
| 4 | 健康监控 | P1 | Actuator 增强：/actuator/health、/actuator/prometheus |
| 5 | 告警 | P1 | 错误率超阈值 / 后端 API 连续失败 / 配额将耗尽 → 看板告警中心 + 邮件通知 |
| 6 | Grafana 大盘 | P2 | 暴露 Prometheus 指标即可，Grafana 运维侧自建 |
4.8 管理后台（Web，code/admin）
| # | 功能点 | 优先级 | 说明 |
|---|---|---|---|
| 1 | 管理员登录 | P0 | 账号密码 + JWT，首个管理员启动日志输出（同 v1 模式） |
| 2 | 租户管理页 | P0 | 列表 + 详情（4.1） |
| 3 | 密钥管理页 | P0 | 在租户详情内管理（4.4） |
| 4 | API 工具配置页 | P0 | 表单化登记 + JSON Schema 参数编辑器（4.2） |
| 5 | 工具授权页 | P0 | 租户 × 工具矩阵勾选（4.3） |
| 6 | 审计日志页 | P0 | 查询 + 详情（4.5） |
| 7 | 数据看板页 | P0 | 驾驶舱首页（4.6） |
| 8 | 告警中心页 | P1 | 告警列表与处理状态 |
前端技术栈：Vue 2 + Element UI + ECharts（与点微团队技能匹配），UI 沿用蓝紫科技色调
#6366F1 → #8B5CF6。构建产物由 Nginx 托管，管理 API 走 /admin/api/**。05数据库设计
沿用 v1 规范：统一审计字段（creator、modifier、create_time、update_time、del_flag），共享库 + tenant_id 隔离。
| 表名 | 变更 | 关键字段 |
|---|---|---|
mcp_tenant | 扩展 | + status、contact、rpm_limit、daily_quota、quota_alert_percent |
mcp_api_key | 扩展 | + remark、expire_time、last_used_time |
mcp_admin_user | 新增 | username、password_hash、status（无 tenant_id，管理面表） |
mcp_builtin_tool | 新增 | tool_name、description、enabled（内置工具注册，供白名单统一管理） |
mcp_api_tool | 新增 | tenant_id、tool_name、description、http_method、url_template、param_schema(JSON)、auth_type、auth_credential(AES加密)、timeout_ms、resp_projection、enabled |
mcp_tool_grant | 新增 | tenant_id、tool_type(BUILTIN/API)、tool_ref_id、enabled（租户工具白名单） |
mcp_audit_log | 扩展 | + key_id、error_type；管理操作审计复用或加 mcp_admin_audit_log |
mcp_usage_daily | 新增 | tenant_id、tool_name、call_date、total、success、fail、avg_cost_ms、max_cost_ms（按天聚合，看板数据源） |
mcp_alert | 新增 | type、level、content、status(未处理/已处理)、tenant_id |
数据隔离注意：mcp_api_tool / mcp_tool_grant 带 tenant_id 走租户插件；管理面表（mcp_admin_user、mcp_alert）不走租户插件，管理 API 手动指定查询条件。
06技术方案要点
框架基线
沿用 v1：Spring Boot 3.5.x + Spring AI 1.1.x（Streamable HTTP，POST /mcp），Java 17+
动态工具
自定义 DynamicToolCallbackProvider，DB 加载 + 变更刷新，tools/list_changed 通知客户端
后端调用
Spring RestClient（超时/重试可配），凭据 AES-GCM 加密（密钥经环境变量注入）
限流
单机内存令牌桶（Guava RateLimiter）+ 日配额原子计数；单实例部署无需 Redis
用量汇总
定时任务（每小时）+ 关机钩子兜底，写 mcp_usage_daily
管理面安全
JWT（短有效期）+ 密码 BCrypt；管理 API 独立过滤器链 /admin/api/**
前端
Vue 2 + Element UI + ECharts，构建产物 Nginx 托管，蓝紫主题
部署
沿用 v1：Docker 多阶段构建，amd64+arm64，阿里云镜像仓库，MySQL 外接，兼容 Ubuntu / CentOS 7
可观测
Actuator + Micrometer Prometheus 指标 + 结构化日志
07开发周期与里程碑
人力假设：后端 1 人（全职）+ 前端 1 人（全职）+ 用户兼产品/测试，可并行开发；若兼职投入，周期按比例顺延。
M1 平台基座2 周
管理后台框架 + 登录、租户管理、密钥管理（含有效期/轮换）、管理操作审计 → 交付：管理台可管理租户与 Key
管理台登录 → 建租户 → 发 Key → WorkBuddy 用新 Key 连通 MCP 端点
M2 核心引擎3 周
API 工具登记 / 动态注册 / 热生效、后端鉴权四种模式、工具白名单、端点接入信息、工具测试控制台 → 交付：租户后端接口零代码变 MCP 工具
登记一个真实后端接口（如点微培训系统查询接口）→ WorkBuddy 中 AI 成功调用
M3 治理能力2 周
RPM 限流 + 日配额、用量计量汇总、监控指标、告警中心 → 交付：429/配额生效，Prometheus 可抓取
超 RPM 返回 429；超日配额返回配额错误；/actuator/prometheus 有数据
M4 驾驶舱2 周
看板指标卡 / 趋势 / 排行 / 错误分析、审计查询与导出、明细下钻 → 交付：数据驾驶舱上线
看板数据与审计明细一致；图表可下钻
M5 联调验收1 周
E2E（含多租户隔离回归）、压测限流验证、部署文档、镜像发布 → 交付：v2.0 发布
docker compose 一键起全套；E2E 全绿
合计约 10 周（2.5 个月）。M1 与 M2 前端部分可提前并行；关键风险集中在 M2（Spring AI 动态工具机制需技术预研验证，预研不通过则降级为「重启生效」并列为已知限制）。
08风险与待定项
R1
Spring AI 1.1.x 动态工具注册机制需预研（@Tool 静态 vs ToolCallback 动态混排）
应对：M2 第一周技术预研，备选：重启生效（可接受降级）
应对：M2 第一周技术预研，备选：重启生效（可接受降级）
R2
tools/list_changed 通知各 MCP 客户端支持度不一
应对：通知 + 文档说明「新工具需重连/刷新」双保险
应对：通知 + 文档说明「新工具需重连/刷新」双保险
R3
租户后端接口无统一规范，参数 schema 手工录入门槛
应对：工具测试控制台辅助调试；远期 OpenAPI 导入
应对：工具测试控制台辅助调试；远期 OpenAPI 导入
R4
单实例限流/计数，重启丢内存态
应对：日配额以 DB 落库为准确兜底；限流窗口短，丢失影响小
应对：日配额以 DB 落库为准确兜底；限流窗口短，丢失影响小
R5
待定：管理后台是否需要租户自助入口
已确认本期仅平台管理员；预留权限模型扩展
已确认本期仅平台管理员；预留权限模型扩展
R6
待定：计费/套餐
本期只做计量（mcp_usage_daily），计费模型远期
本期只做计量（mcp_usage_daily），计费模型远期
附v1 → v2 功能对照
| 模块 | v1 现状 | v2 增量 |
|---|---|---|
| 租户 | API 级建租户、示例数据自动生成 | 管理台 CRUD、状态管理、配额参数 |
| 密钥 | 哈希存储、吊销，无 UI | 完整 UI、有效期、轮换宽限、备注 |
| 工具 | 4 个硬编码打样工具 | 动态 API 工具引擎 + 白名单 + 测试控制台 |
| 审计 | 调用落库 | 查询界面、详情脱敏、导出、管理操作审计 |
| 限流 | 无 | RPM + 日配额 + 用量计量 |
| 看板 | 无 | 数据驾驶舱（指标/趋势/排行/错误/下钻） |
| 部署 | Docker + 阿里云镜像 | 不变，前端产物一并纳入镜像 |