架构概述

Foggy MCP 服务实现了 Model Context Protocol (MCP) 协议，为 AI 助手提供数据查询能力。

整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        AI 客户端                                 │
│  (Claude Desktop / Cursor / 自定义 Agent)                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ MCP 协议 (JSON-RPC 2.0)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Foggy MCP 服务层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ /mcp/admin   │  │ /mcp/analyst │  │ /mcp/business│          │
│  │   全部工具    │  │  专业工具     │  │  自然语言     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                              │                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    MCP 工具分发器                          │  │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐            │  │
│  │  │ 元数据工具  │ │ 查询工具   │ │ NL 查询工具 │  ...       │  │
│  │  └────────────┘ └────────────┘ └────────────┘            │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Foggy Dataset Model                            │
│              (TM/QM 模型引擎、语义查询层)                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        数据库                                    │
│         (MySQL / PostgreSQL / SQL Server / SQLite)              │
└─────────────────────────────────────────────────────────────────┘

角色与端点

MCP 服务按用户角色提供不同的端点，每个端点返回不同的工具集：

端点列表

端点	角色	工具范围	适用场景
/mcp/admin/rpc	管理员	全部工具	开发调试、完全访问
/mcp/analyst/rpc	分析师	专业工具（不含 NL）	数据分析、精确查询
/mcp/business/rpc	业务人员	仅自然语言查询	普通用户、简单查询

角色说明

管理员 (Admin)

• 端点: /mcp/admin/rpc
• 权限: 所有工具的完整访问权限
• 适用: 开发人员、系统管理员
• 工具: 元数据、查询、自然语言、图表、导出等全部工具

数据分析师 (Analyst)

• 端点: /mcp/analyst/rpc
• 权限: 专业数据处理工具，不含自然语言查询
• 适用: 数据分析师、BI 开发人员
• 工具: 元数据查询、结构化查询、图表生成、数据导出
• 特点: 需要了解语义层模型和查询语法，提供精确控制

业务人员 (Business)

• 端点: /mcp/business/rpc
• 权限: 仅自然语言查询工具
• 适用: 普通业务用户、非技术人员
• 工具: dataset_nl.query
• 特点: 用自然语言描述需求，无需了解技术细节

协议支持

JSON-RPC 2.0 端点

所有 /rpc 端点使用标准 MCP JSON-RPC 2.0 协议：

# 示例：获取工具列表
curl -X POST http://localhost:7108/mcp/analyst/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list",
    "params": {}
  }'

支持的 MCP 方法:

• initialize - 初始化连接
• tools/list - 获取可用工具列表
• tools/call - 调用指定工具
• ping - 心跳检测

工具分类

MCP 工具按功能分为以下类别：

类别	说明	包含工具
元数据管理	查询语义层元数据	get_metadata, description_model_internal
数据查询	结构化数据查询	query_model
自然语言	AI 驱动的智能查询	dataset_nl.query
数据可视化	图表生成	generate_chart
数据导出	数据导出功能	export_with_chart

角色-工具权限矩阵

工具	Admin	Analyst	Business
dataset.get_metadata	✅	✅	❌
dataset.description_model_internal	✅	✅	❌
dataset.query_model	✅	✅	❌
dataset.generate_chart	✅	✅	❌
dataset.export_with_chart	✅	✅	❌
dataset_nl.query	✅	❌	✅

HTTP Headers

MCP 服务支持以下 HTTP Headers：

Header	说明	必填
Authorization	认证信息，传递给后端服务	否
X-Trace-Id	AI 会话追踪 ID，贯穿多次工具调用	否
X-Request-Id	单次 HTTP 请求 ID	否

追踪 ID 说明:

• X-Trace-Id: 标识一次完整的 AI 会话，同一会话的多次工具调用共享此 ID
• X-Request-Id: 标识单次 HTTP 请求，每次请求生成新的 ID
• 如果客户端未提供，服务端会自动生成 UUID

部署架构

单机部署

┌─────────────────────────────────────────┐
│              应用服务器                  │
│  ┌─────────────────────────────────┐   │
│  │     Foggy MCP + Dataset Model   │   │
│  │          (端口 7108)             │   │
│  └─────────────────────────────────┘   │
│                  │                      │
│  ┌─────────────────────────────────┐   │
│  │           数据库                 │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

分布式部署

┌──────────────┐     ┌──────────────┐
│  MCP 服务 1   │     │  MCP 服务 2   │
│  (端口 7108)  │     │  (端口 7108)  │
└──────────────┘     └──────────────┘
        │                   │
        └───────┬───────────┘
                │
        ┌───────▼───────┐
        │   负载均衡器   │
        └───────────────┘
                │
        ┌───────▼───────┐
        │  Dataset 服务  │
        │  (端口 8080)   │
        └───────────────┘
                │
        ┌───────▼───────┐
        │    数据库      │
        └───────────────┘

技术栈

• 框架: Spring Boot 3.x + Spring WebFlux
• AI 集成: Spring AI (OpenAI 兼容接口)
• 协议: JSON-RPC 2.0 (MCP)
• 响应式: Project Reactor
• 流式输出: Server-Sent Events (SSE)

下一步

• 快速开始 - 启动 MCP 服务
• 工具列表 - 查看可用工具
• Claude Desktop 集成 - 配置 AI 客户端