ding

anruowang/ding

0 Stars 5 次浏览更新于 2026-08-23

浏览器自动化

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

MCP 服务管理平台模块需求文档

对标 ModelScope MCP 社区市场交互形态

1. 项目概述

构建一套 MCP（Model Context Protocol）服务管理平台，实现 MCP 服务的录入、探测、展示、管理，支持 Stdio / Streamable HTTP / SSE 三种协议类型。

平台定位：MCP 服务发布与分发市场。

外部客户端（QClaw、VSCode Cline、ModelScope Agent）可获取平台生成的 MCP 配置并连接远端 MCP 服务进行工具调用。

核心机制：

用户录入远端 MCP 服务连接信息 → 后端通过 MCP 协议临时会话自动探测 tools/list → 获取工具元信息入库 → 前端页面可视化展示工具清单。

工具定义完全由远端 MCP 服务提供，平台仅做连接网关，无法新增 / 编辑工具逻辑。

2. 页面功能清单

2.1 MCP 服务列表页

参考 ModelScope MCP 市场卡片布局

布局结构
- 左侧：分类侧边栏（位置服务、搜索工具、开发者工具、浏览器自动化等，支持自定义分类）
- 右上：搜索框、筛选栏
- 主体区域：MCP 服务卡片网格
筛选条件
- 关键词搜索：MCP 名称、描述、标签检索
- 托管类型筛选：Hosted(远程HTTP) / Local(本地Stdio)
- 支持分页
卡片展示字段
- 图标、中文名称、英文唯一名称
- 简短服务描述
- 标签、托管类型标签
- 开发者 / 所有者信息
- 统计指标：访问量、收藏数量
交互行为
- 点击卡片 → 跳转【MCP 服务详情页】
- 顶部「创建 MCP Server」按钮 → 跳转创建表单

2.2 MCP 服务详情页

基础信息头部

图标、中英文名称、所有者、开源协议、服务简介、收藏按钮
可用工具展示区（核心模块）

展示后端探测得到的工具列表：
- 工具名称
- 工具描述（AI 理解用途）
- 入参结构 inputSchema：参数名称、参数类型、是否必填、参数说明

服务配置面板

根据 MCP 协议类型展示对应 JSON 配置，支持一键复制，供给外部客户端使用。

Streamable HTTP 示例：

json

{
  "mcpServers": {
    "amap-weather-mcp": {
      "type": "streamable_http",
      "url": "https://mcp.amap.com/mcp?key=<YOUR_AMAP_KEY>"
    }
  }
}

辅助功能
- 刷新工具列表：重新触发后端探测接口
- 工具测试入口：支持传入参数调试调用工具
- 查看 README 文档（Markdown 渲染）

2.3 创建 MCP Server 表单页面

分为两大区域：基础信息、协议配置 & README

2.3.1 基础信息表单

表格

字段	约束
英文名称	必填，全局唯一，创建后不可修改
中文名称	必填
来源地址	选填，MCP 开源地址
所有者	必填，当前登录用户
是否公开	公开 / 私有；私有仅本人可见
托管类型	Hosted (远程服务) / 仅本地可用
类型	下拉选择：Stdio / Streamable HTTP / SSE
服务描述	简短功能介绍
自定义标签	多选标签，用于分类筛选
图标	图片上传

2.3.2 协议配置区域（根据「类型」动态切换面板）

Streamable HTTP（主推，远程公网 MCP）
- 左侧：服务配置 JSON 输入框
- 右侧：请求参数配置（Query 参数 / Header 鉴权）
- 【添加】按钮：触发后端探测工具
Stdio（本地进程模式）
- command、args、环境变量配置 JSON
SSE
- SSE 模式连接地址配置

2.3.3 README

Markdown 编辑器，支持「预览」，用于介绍 MCP 功能、参数、使用示例。

3. 后端核心能力

3.1 核心接口：MCP 工具探测接口

最重要接口

入参：MCP 连接 url、headers、协议类型
执行逻辑：
- 创建短时 MCP 客户端 Transport
- MCP initialize 握手
- 调用 tools/list RPC 获取全部工具元数据
- 关闭连接，返回工具列表
业务动作：探测成功后将工具数组存入数据库；探测失败记录错误状态

约束：探测会话为一次性短时会话，获取工具后立刻销毁，不长期维持连接。

3.2 数据模型（mcp_server）

{
  id: string;
  en_name: string; // 唯一英文标识
  cn_name: string;
  icon: string;
  description: string;
  source_url?: string;
  owner_id: string;
  is_public: boolean;
  host_type: "hosted" | "local";
  transport_type: "stdio" | "streamable_http" | "sse";
  config_json: string;
  readme: string;
  tags: string[];
  // 探测缓存
  tools: Array<{
    name: string;
    description: string;
    inputSchema: object;
  }>;
  last_discover_at: Date | null;
  status: "normal" | "discover_failed";
  view_count: number;
  star_count: number;
}

3.3 基础 CRUD 接口

创建 MCP 服务
编辑基础信息、配置、README
MCP 列表分页查询（支持筛选、搜索）
获取单条 MCP 详情
收藏 / 取消收藏

4. 核心业务流程（创建链路）

用户进入【创建 MCP Server】页面，填写基础信息
选择 Streamable HTTP，录入服务配置 JSON
点击【添加】，前端调用后端探测接口
后端建立 MCP 会话，执行握手 + tools/list
探测成功，工具列表入库
保存整条 MCP 记录，跳转至详情页
详情页自动渲染远端 MCP 上报的全部工具

5. 关键约束与开发注意事项

MCP 协议交互全部放在后端执行

禁止前端浏览器直接建立 SSE 流，存在 CORS、长连接生命周期难以管控问题。
会话区分
- 探测会话：仅拉取工具元信息，用完立即关闭
- Agent 工具调用：单独新建独立会话，跟随对话生命周期
工具更新机制

MCP 协议不存在服务端主动推送变更；远端 MCP 新增 / 修改工具后，用户需要手动点击【刷新工具列表】重新探测。
配置兼容性

输出的 mcpServers JSON 格式兼容主流客户端：

ModelScope、Cline（VSCode）、QClaw、MCP Inspector。
异常处理

探测接口设置超时限制；网络失败、鉴权错误、协议不兼容时页面展示异常提示。

6. 角色定位区分

本平台：MCP 市场（发布、存储、展示、分发 MCP 接入配置）
QClaw / VSCode Cline / ModelScope Agent：MCP 消费客户端，填入平台提供的配置连接远端 MCP 服务调用工具

7. 扩展规划（可选）

MCP 合集功能
工具在线调试面板
MCP 版本管理
访问权限控制、分享链接

查看源码项目主页