FranklinWH MCP Server 设计文档

1. 概述

FranklinWH MCP Server (fwh-tools) 是基于 Model Context Protocol 实现的内部工具服务器，为 AI Agent（Kiro CLI）提供对 FranklinWH 内部工具平台数据和服务的结构化访问能力。

项目	说明
服务名	`fwh-tools`
版本	`2.1.0`
语言	Go
SDK	`github.com/mark3labs/mcp-go`
传输协议	stdio (JSON-RPC 2.0 over stdin/stdout)
构建产物	单二进制 `fwh-mcp-server`
调用方	Kiro CLI（通过 ACP 协议启动子进程）

2. 架构设计

2.1 整体架构

┌─────────────────────────────────────────────────────┐
│                   Kiro CLI (AI Agent)                 │
│              通过 ACP 协议管理 MCP Server              │
└────────────────────────┬────────────────────────────┘
                         │ stdio (JSON-RPC 2.0)
                         ▼
┌─────────────────────────────────────────────────────┐
│              fwh-mcp-server (本进程)                  │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │              MCP Protocol Layer                 │  │
│  │         (mcp-go SDK: 请求路由、序列化)          │  │
│  └─────────────────────┬──────────────────────────┘  │
│                        │                             │
│  ┌─────────┬───────────┼───────────┬─────────────┐  │
│  │service/ │  data/    │  storage/ │    util/     │  │
│  │业务逻辑 │ 数据直查   │ 对象存储  │   辅助工具   │  │
│  └────┬────┴─────┬─────┴─────┬─────┴──────┬──────┘  │
│       │          │           │            │          │
└───────┼──────────┼───────────┼────────────┼──────────┘
        │          │           │            │
        ▼          ▼           ▼            │ (纯函数)
┌──────────┐ ┌──────────────────────┐ ┌──────────┐
│ services/│ │  repositories/       │ │  MinIO   │
│层(复用后 │ │  ├─ mongo (MongoDB)  │ │          │
│端业务代 │ │  ├─ redis (Redis)    │ │          │
│码)       │ │  ├─ pgsql (PgSQL)   │ │          │
│          │ │  ├─ api/fwh_pro     │ │          │
│          │ │  ├─ api/plane_v1+v2 │ │          │
│          │ │  └─ api/sim (SH/AC) │ │          │
└──────────┘ └──────────────────────┘ └──────────┘

2.2 与现有后端的关系

MCP Server 是现有后端 Service 层的另一个入口，不是独立系统：

对比项	HTTP Server (`main.go`)	MCP Server (`cmd/mcp/main.go`)
入口	Fiber HTTP 路由	stdio JSON-RPC
调用方	前端浏览器	Kiro CLI (AI Agent)
认证	Casdoor JWT	无需（本地 stdio 进程）
复用层	controllers → services → repositories	直接调用 services/repositories
输出格式	JSON HTTP Response	MCP Tool Result (text/JSON)

2.3 代码目录结构

service/cmd/mcp/
├── main.go                      # 入口：初始化基础设施 + 创建 MCP Server + 注册工具
├── tools/
│   ├── register.go              # RegisterAll：唯一对外注册入口
│   ├── helper/
│   │   └── helper.go            # 统一响应工具函数
│   ├── service/                 # 业务逻辑层工具
│   │   ├── register.go          # RegisterServiceTools
│   │   ├── site.go              # 站点相关工具
│   │   ├── sim.go               # SIM 卡相关工具
│   │   ├── monitor.go           # 监控统计工具
│   │   └── feedback.go          # 反馈协作工具
│   ├── data/                    # 数据直查层工具
│   │   ├── register.go          # RegisterDataTools
│   │   ├── mongo.go             # MongoDB 通用直查
│   │   ├── redis.go             # Redis 缓存读取
│   │   ├── pgsql.go             # PostgreSQL 直查
│   │   ├── emspara.go           # EMS 参数查询
│   │   ├── fwh_api.go           # FWH Pro API 读操作
│   │   ├── plane_api.go         # Plane API 读操作（工具注册）
│   │   ├── plane_api_handlers.go # Plane API 读操作（handler 实现）
│   │   └── sim_api.go           # SmartHub/Acceleronix SIM 卡 API
│   ├── storage/                 # 对象存储层工具
│   │   ├── register.go          # RegisterStorageTools
│   │   ├── file.go              # 用户上传文件读取
│   │   └── minio.go             # MinIO 对象浏览/读取
│   └── util/                    # 辅助工具层
│       ├── register.go          # RegisterUtilTools
│       └── format.go            # SN 解析等纯函数

3. 工具分层架构

采用四层分类设计，按访问层级递进：

┌───────────────────────────────────────────────────┐
│  Layer 1: service_*  — 业务逻辑层（优先使用）        │
│  调用后端 Service 层函数，包含业务校验和数据聚合      │
├───────────────────────────────────────────────────┤
│  Layer 2: data_*     — 数据直查层（灵活查询）        │
│  直接调用 repositories 层，跳过业务逻辑，仅限只读     │
│  覆盖: DB(Mongo/Redis/PgSQL) + 外部API(FWH/Plane/SIM) │
├───────────────────────────────────────────────────┤
│  Layer 3: storage_*  — 对象存储层（文件操作）        │
│  file_* 支持读写，minio_* 仅只读浏览和读取           │
├───────────────────────────────────────────────────┤
│  Layer 4: util_*     — 辅助工具层（纯函数）          │
│  格式解析等不涉及数据持久化的工具                     │
└───────────────────────────────────────────────────┘

命名规范： {layer}_{domain}_{action}

示例：service_site_query_info、data_fwh_query_site_alarm_list、data_plane_list_work_items、storage_minio_list_objects、util_parse_sn

4. 工具清单

4.1 Service 层（业务逻辑）

工具名	说明	参数
`service_site_query_info`	查询站点设备详情	`sn` (必填)
`service_site_search`	搜索站点列表	`page`, `size`, `keyword`
`service_site_power_flow`	查询功率流数据	`sn` (必填), `date` (必填, yyyy-MM-dd)
`service_sim_query`	查询 SIM 卡详情	`giccid` (必填)
`service_sim_search`	搜索 SIM 卡列表	`page`, `size`, `search`, `status`, `platform`
`service_monitor_alarm_stats`	查询告警统计	`date`
`service_monitor_shutdown_stats`	查询停机统计	`date`
`service_feedback_create`	创建 Plane Intake Issue	`title` (必填), `type` (必填), `priority`, `description`, `category`
`service_feedback_history`	查询反馈历史	(无参数)

4.2 Data 层（数据直查）

4.2.1 通用数据库直查

工具名	说明	参数
`data_mongo_find`	MongoDB 集合查询	`collection` (必填), `filter`, `limit`, `skip`, `sort`
`data_mongo_count`	MongoDB 文档计数	`collection` (必填), `filter`
`data_redis_get`	读取 Redis key	`key` (必填), `type`
`data_redis_exists`	检查 key 存在性及 TTL	`key` (必填)
`data_pgsql_query_snapshot_file_record`	查询快照文件解析记录	`file_name` (必填)
`data_pgsql_query_snapshot_data`	查询告警快照数据	`sn` (必填), `date` (必填)
`data_emspara_vid_info`	查询 EMS VID 参数信息	`id` (必填)
`data_emspara_pid_info`	查询 EMS PID 参数信息	`id` (必填)

4.2.2 FWH Pro API 直查

工具名	说明	参数
`data_fwh_query_site_base_info_list`	查询站点基本信息列表	`sn`, `page`, `size`
`data_fwh_query_site_list`	查询站点列表	`sn`, `page`, `size`
`data_fwh_query_site_mode_info`	查询站点工作模式	`sn` (必填)
`data_fwh_query_site_power_flow`	查询站点功率流	`sn` (必填), `date` (必填)
`data_fwh_query_site_alarm_list`	查询站点告警列表	`sn` (必填)
`data_fwh_query_event_alarm_list`	查询事件/告警日志	`sn` (必填), `start_time` (必填), `end_time` (必填), `type`
`data_fwh_query_alarm_snapshot`	查询告警快照	`sn` (必填), `date` (必填)
`data_fwh_query_alarm_statistics`	查询实时告警统计	`country`, `page`
`data_fwh_query_alarm_statistics_from_code`	按告警码查询站点	`alarm_code` (必填), `country`, `page`
`data_fwh_query_mqtt_log_list`	查询 MQTT 日志	`sn` (必填), `cmd_type` (必填), `start_time` (必填), `end_time` (必填)
`data_fwh_query_shutdown_list`	查询停机站点列表	`date` (必填), `country`
`data_fwh_query_ems_log_record`	查询 EMS 日志记录	`sn` (必填)
`data_fwh_query_fault_record_list`	查询故障录波列表	`sn` (必填), `start_time` (必填), `end_time` (必填)
`data_fwh_query_fault_record_callable_list`	查询可召唤故障录波	`sn` (必填), `dev_type`
`data_fwh_query_fault_record_call_record_list`	查询录波召唤记录	(无参数)
`data_fwh_query_fault_record_sub_list`	查询录波子记录	`fault_id` (必填)
`data_fwh_query_system_update_log`	查询系统升级记录	`sn` (必填)
`data_fwh_query_system_update_log_detail`	查询升级记录详情	`order_id` (必填)
`data_fwh_query_ahub_update_log`	查询 aHub 升级记录	`sn` (必填)
`data_fwh_query_tou_template_list`	查询 TOU 模板列表	`search`, `page`, `size`
`data_fwh_query_tou_template_detail`	查询 TOU 模板详情	`id` (必填)

4.2.3 Plane API 直查

工具名	说明	参数
`data_plane_list_projects`	列出项目	(无参数)
`data_plane_get_project`	获取项目详情	`project_id` (必填)
`data_plane_get_project_summary`	获取项目摘要	`project_id` (必填), `fields`
`data_plane_list_work_items`	列出工作项	`state`, `priority`, `assignee`, `label`
`data_plane_get_work_item`	获取工作项详情	`work_item_id` (必填)
`data_plane_get_work_item_by_identifier`	通过标识符获取工作项	`identifier` (必填), `sequence_id` (必填)
`data_plane_search_work_items`	搜索工作项	`query` (必填), `limit`
`data_plane_list_cycles`	列出迭代	(无参数)
`data_plane_get_cycle`	获取迭代详情	`cycle_id` (必填)
`data_plane_list_cycle_issues`	列出迭代工作项	`cycle_id` (必填)
`data_plane_list_modules`	列出模块	(无参数)
`data_plane_get_module`	获取模块详情	`module_id` (必填)
`data_plane_list_module_issues`	列出模块工作项	`module_id` (必填)
`data_plane_list_states`	列出状态	(无参数)
`data_plane_list_labels`	列出标签	(无参数)
`data_plane_list_workspace_members`	列出工作空间成员	(无参数)
`data_plane_list_project_members`	列出项目成员	(无参数)
`data_plane_list_work_item_comments`	列出评论	`work_item_id` (必填)
`data_plane_list_work_item_activities`	列出活动历史	`work_item_id` (必填)
`data_plane_list_work_item_links`	列出链接	`work_item_id` (必填)
`data_plane_list_work_item_attachments`	列出附件	`work_item_id` (必填)
`data_plane_list_work_item_relations`	列出关系	`work_item_id` (必填)
`data_plane_get_intake_issue_list`	查询 Intake 列表	(无参数)
`data_plane_get_intake_issue_detail`	获取 Intake 详情	`intake_id` (必填)
`data_plane_list_pages`	列出页面 (V2)	(无参数)
`data_plane_get_page`	获取页面详情 (V2)	`page_id` (必填)
`data_plane_get_page_description`	获取页面描述 (V2)	`page_id` (必填)

4.2.4 SIM 卡 API 直查

工具名	说明	参数
`data_sim_smarthub_batch_info`	SmartHub 批量查询 SIM 卡	`page`, `size`
`data_sim_smarthub_card_info`	SmartHub 单卡详情	`giccid` (必填)
`data_sim_acceleronix_card_list`	Acceleronix SIM 卡列表	`page`, `size`
`data_sim_acceleronix_card_info`	Acceleronix 单卡详情	`iccid` (必填)
`data_sim_acceleronix_batch_data_info`	Acceleronix 批量数据用量	`iccid_list` (必填), `month` (必填)
`data_sim_acceleronix_data_pool_list`	Acceleronix 流量池列表	`page`, `size`
`data_sim_acceleronix_data_pool_sim_info`	Acceleronix 流量池 SIM 详情	`data_pool_id` (必填), `page`, `size`

4.3 Storage 层（对象存储）

工具名	说明	参数	读写
`storage_file_read`	读取用户上传文件	`path` (必填)	读
`storage_file_write`	写入文件到存储	`path` (必填), `content` (必填)	写
`storage_file_list`	列出用户上传文件	(无参数)	读
`storage_minio_list_objects`	列出 MinIO 对象	`bucket` (必填), `prefix`, `limit`	读
`storage_minio_read_object`	读取 MinIO 文本文件	`bucket` (必填), `key` (必填)	读

4.4 Util 层（辅助工具）

工具名	说明	参数
`util_parse_sn`	解析设备 SN 序列号含义	`sn` (必填)

5. 安全设计

5.1 访问控制

机制	说明
传输层	stdio 本地进程通信，无网络暴露
认证	无需（由 ACP 管理器控制进程生命周期）
Collection 白名单	MongoDB 查询限制在指定集合内
Bucket 白名单	MinIO 访问限制在指定 bucket 内
只读限制	data_* 层所有操作均为只读（排除写、更新操作）
外部 API	datafwh*、dataplane、datasim 仅暴露查询接口，不暴露写操作
文件大小限制	MinIO 读取限制 1MB，用户上传限制 2MB
查询结果限制	MongoDB 单次最多返回 100 条
Redis 安全	不支持通配符 key，防止 KEYS * 类操作
SIM 卡批量限制	Acceleronix 批量查询最多 50 个 ICCID

5.2 白名单配置

MongoDB Collections:

var mongoAllowedCollections = []string{
    "SiteInfoManageData",
    "SiteInfoManageRecord",
    "SimCardManage",
    "SimCardMonthlyData",
    "BatchDownloadConfig",
    "SiteAnalysisConfig",
    "StatisticsShutdown",
    "StatisticsAlarm",
    "SiteMonitorConfig",
    "UserInfo",
    "AutoUpdateConfigOption",
    "AutoUpdateConfig",
    "AiChatSessions",
}

MinIO Buckets:

var minioAllowedBuckets = []string{
    "fwh-toolbox-batch-download",
    "fwh-toolbox-ai-file",
}

5.3 写操作控制

层级	写操作	说明
service	`service_feedback_create`	创建 Plane Intake Issue
data	无	全部只读
storage	`storage_file_write`	写入文件到 MCP FileStore（MinIO），最大 2MB
storage	`storage_minio_*`	仅只读（列出、读取），不支持写入
util	无	纯函数

6. 文件存储设计

6.1 FileStore 架构

MinIO Bucket: fwh-toolbox-ai-file
├── upload/                        ← 用户上传的文件
│   └── {userId}/{sessionId}/{uuid}_{fileName}
│
└── download/                      ← AI 生成的下载文件
    └── {userId}/{sessionId}/{uuid}_{fileName}

6.2 文件生命周期

阶段	操作	说明
上传	`POST /ai/files/upload`	前端上传 → 后端存入 MinIO（prefix=acp）
读取	Agent `readTextFile` 或 `storage_file_read`	AI 请求读取 → FileStore 从 MinIO 获取
过期	自动清理	文件设置 7 天过期

6.3 共享模块

通用 FileStore 位于 service/utils/filestore/filestore.go，ACP 和 MCP 通过不同 prefix 实例化：

// ACP 使用
acpFS := filestore.NewFileStore("acp")

// MCP 使用
mcpFS := filestore.NewFileStore("download")

7. 响应格式

7.1 统一响应工具 (`helper/helper.go`)

函数	用途	返回类型
`JSONResult(data)`	序列化为格式化 JSON	`CallToolResult` (text)
`TextResult(text)`	直接返回文本	`CallToolResult` (text)
`ParamError(name)`	参数缺失错误	`CallToolResult` (error)
`ParamInvalidError(name, detail)`	参数格式错误	`CallToolResult` (error)
`ServiceError(action, err)`	业务调用失败	`CallToolResult` (error)
`EmptyResult(msg)`	空结果提示	`CallToolResult` (text)

7.2 错误响应格式

参数 {name} 必填
参数 {name} 格式错误: {detail}
{action}失败: {error}

8. 初始化流程

func main() {
    // 1. 加载配置（与 HTTP Server 共享）
    cfg := config.LoadConfig()

    // 2. 初始化基础设施
    logger.Init(cfg.App.AppEnv)
    database.Init(&cfg.App)          // MongoDB
    cache.Init(cfg.App.RedisAddr)    // Redis
    repositories.PlaneWebHttpInit()  // Plane API

    // 3. 初始化 MCP FileStore (prefix="download")
    mcpFS := filestore.NewFileStore("download")
    storage.InitFileStore(mcpFS)

    // 4. 创建 MCP Server
    s := server.NewMCPServer("fwh-tools", "2.0.0",
        server.WithToolCapabilities(false),
        server.WithRecovery(),
        server.WithInstructions(serverInstructions),
    )

    // 5. 注册所有 Tools（单一入口）
    tools.RegisterAll(s)

    // 6. 启动 stdio 通信
    server.ServeStdio(s)
}

9. 部署配置

9.1 构建

cd service
go build -o fwh-mcp-server ./cmd/mcp

9.2 Kiro MCP 配置

文件：service/.kiro/settings/mcp.json

{
  "mcpServers": {
    "fwh-tools": {
      "command": "./fwh-mcp-server",
      "args": [],
      "env": {
        "MONGO_DSN": "${MONGO_DSN}",
        "REDIS_ADDR": "${REDIS_ADDR}",
        "MINIO_ENDPOINT": "${MINIO_ENDPOINT}",
        "MINIO_ACCESS_KEY": "${MINIO_ACCESS_KEY}",
        "MINIO_SECRET_KEY": "${MINIO_SECRET_KEY}",
        "PLANE_WEB_HOST": "${PLANE_WEB_HOST}",
        "PLANE_WEB_EMAIL": "${PLANE_WEB_EMAIL}",
        "PLANE_WEB_PASSWORD": "${PLANE_WEB_PASSWORD}",
        "PLANE_WEB_WORKSPACE_SLUG": "${PLANE_WEB_WORKSPACE_SLUG}",
        "PLANE_WEB_PROJECT_ID": "${PLANE_WEB_PROJECT_ID}"
      }
    }
  }
}

9.3 部署目录

/var/www/fwh-toolbox/server/
├── fwh-toolbox-server         # HTTP Server
├── fwh-mcp-server             # MCP Server
├── .kiro/
│   ├── settings/mcp.json      # MCP 配置
│   ├── agents/                # Agent 配置
│   └── steering/              # Steering 文件
└── .env                       # 环境变量

10. Instructions 系统提示

MCP Server 通过 server.WithInstructions() 向 AI Agent 提供使用指南：

FranklinWH 工具箱 MCP Server — 内部工具平台的 AI 接口层。

使用原则：
1. 优先使用 service_* 工具，它们包含完整的业务逻辑
2. 仅当 service 层无法满足时才使用 data_* 直查
3. data_* 层覆盖 repositories 全部只读操作（DB + 外部 API）
4. 所有 data_* 和 storage_* 工具仅支持只读操作
5. 查询 MongoDB 时注意 collection 白名单限制

11. 扩展指南

11.1 添加新的 Service 层工具

在 tools/service/ 下创建新文件（如 newdomain.go）
实现 registerXxxTools(s *server.MCPServer) 函数
在 tools/service/register.go 的 RegisterServiceTools 中调用

工具命名遵循 service_{domain}_{action} 格式

// tools/service/newdomain.go
package service

func registerNewDomainTools(s *server.MCPServer) {
s.AddTool(
    mcp.NewTool("service_newdomain_query",
        mcp.WithDescription("..."),
        mcp.WithString("id", mcp.Required(), mcp.Description("...")),
    ),
    handleNewDomainQuery,
)
}

func handleNewDomainQuery(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
id, err := req.RequireString("id")
if err != nil {
    return helper.ParamError("id"), nil
}
data, err := services.GetSomething(id)
if err != nil {
    return helper.ServiceError("查询", err), nil
}
return helper.JSONResult(data), nil
}

11.2 添加新的 MongoDB Collection 访问

在 tools/data/mongo.go 的 mongoAllowedCollections 白名单中添加新集合名：

var mongoAllowedCollections = []string{
    // ... 现有集合
    "new_collection_name",  // ← 添加这一行
}

11.3 添加新的 MinIO Bucket 访问

在 tools/storage/minio.go 的 minioAllowedBuckets 白名单中添加：

var minioAllowedBuckets = []string{
    // ... 现有 bucket
    "new-bucket-name",  // ← 添加这一行
}

12. 测试

12.1 本地测试

# 构建
cd service && go build -o fwh-mcp-server ./cmd/mcp

# 测试 tools/list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./fwh-mcp-server

# 测试单个工具调用
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"util_parse_sn","arguments":{"sn":"10060006A03X25310091"}}}' | ./fwh-mcp-server

12.2 通过 Kiro CLI 测试

# 在 service/ 目录下（含 .kiro/ 配置）
kiro-cli chat

# 对话中使用工具
> 帮我查一下 SN 为 10060006A03X25310091 的站点信息
> 统计一下 site_info 集合中有多少条记录
> 解析一下这个 SN: 10050004B02X24450023

13. 依赖关系

依赖	版本	用途
`github.com/mark3labs/mcp-go`	latest	MCP 协议 SDK
`go.mongodb.org/mongo-driver`	-	MongoDB 驱动
`github.com/minio/minio-go/v7`	-	MinIO 客户端
`github.com/google/uuid`	-	UUID 生成
`go.uber.org/zap`	-	日志

共享后端模块：

fwh-toolbox-server/services — 业务逻辑层
fwh-toolbox-server/database — 数据库连接
fwh-toolbox-server/cache — Redis 缓存
fwh-toolbox-server/repositories — 数据访问层（Mongo/Redis/PgSQL/API）
fwh-toolbox-server/domain — 领域对象定义
fwh-toolbox-server/utils/filestore — 文件存储
fwh-toolbox-server/utils/minio — MinIO 客户端
fwh-toolbox-server/config — 配置加载
fwh-toolbox-server/dto — 数据传输对象

14. 变更历史

版本	日期	变更内容
1.0.0	2026-08-03	初版：6 个 service 层工具（site/sim/alarm/shutdown/plane）
2.0.0	2026-08-06	重构为四层架构，新增 data/storage/util 层，命名规范化
2.1.0	2026-08-10	data 层全面覆盖 repositories 只读操作：新增 fwh_api(21)、plane_api(25)、sim_api(7)、pgsql(2)、emspara(2) 共 57 个工具；修正 MongoDB 白名单为实际集合名

DESIGN.md 24 KB لینک دائمی تاريخچه خام