MCP 注册服务指南（bdsh-mcp-hub）

1. 项目介绍

bdshMCPHub 是本地生活业务场景下的 MCP (Model Context Protocol) 服务集合平台，基于 FastMCP 框架构建，支持 HTTP Stream 和 SSE 传输方式。项目采用模块化架构，可统一管理多个独立的 MCP 服务器实例，通过 Docker 容器化部署和 Nginx 路由，为 AI 应用提供标准化的工具调用服务能力，简化本地生活业务场景下的 MCP 服务部署和维护。

2. 架构简介

.
├── build.config.ts            # 构建配置
├── config.json                # mcp服务配置项
├── docker
│   ├── nginx.conf             # nginx配置
│   └── start.sh               # docker入口脚本
├── package.json
├── servers
│   ├── _common                # 通用端口mcp服务
│   └── temperatureConversion  # 独享端口mcp服务
└── src
    └── index.ts               # 构建入口

2.1 服务启动流程

项目采用配置驱动的模块化架构。核心入口 src/index.ts 读取 config.json 配置文件，动态启动多个独立的 MCP 服务器实例，每个服务运行在独立端口（如 8080、8081）。服务层位于 servers/ 目录，每个服务通过 registerTools 函数注册工具，使用 Zod 进行参数校验。

graph LR
    Config[config.json<br/>服务配置] --> Entry[src/index.ts<br/>入口程序]
    Entry -->|启动服务| MCP1[Common MCP Server<br/>:8080]
    Entry -->|启动服务| MCP2[Temperature Conversion<br/>:8081]
    S1[servers/_common<br/>注册工具] -->|registerTools| MCP1
    S2[servers/temperatureConversion<br/>注册工具] -->|registerTools| MCP2
    
    style Entry fill:#e8f5e9
    style Config fill:#f3e5f5
    style MCP1 fill:#ffe1e1
    style MCP2 fill:#ffe1e1

Loading

2.2 客户端访问流程

部署层面，Nginx 作为反向代理统一对外提供服务，通过 X-Target-Port header 动态路由请求到对应的后端服务端口。支持 HTTP Stream 和 SSE 两种传输方式，适配长连接场景。整体采用 Docker 容器化部署，便于在云环境中快速扩展和维护。

graph LR
    Client[AI 应用客户端] -->|HTTP/SSE<br/>X-Target-Port: 8080| Nginx[Nginx 反向代理<br/>:80]
    Client -->|HTTP/SSE<br/>X-Target-Port: 8081| Nginx
    Nginx -->|路由转发| MCP1[Common MCP Server<br/>:8080]
    Nginx -->|路由转发| MCP2[Temperature Conversion<br/>:8081]
    
    style Client fill:#e1f5ff
    style Nginx fill:#fff4e1
    style MCP1 fill:#ffe1e1
    style MCP2 fill:#ffe1e1

Loading

3. MCP 接入

3.1 本地开发（指在 bdsh-mcp-hub 代码库内开发 MCP 服务）

3.1.1 拉取代码库

http://xingyun.jd.com/codingRoot/BDSH_BEST_AI/bdshMCPHub/

git clone git@coding.jd.com:BDSH_BEST_AI/bdshMCPHub.git

3.1.2 使用 pnpm 装包

# 推荐使用 node v22
pnpm i
pnpm doPrepare # 安装准备工作

3.1.3 构建 MCP 服务

单 MCP 服务需占用一个本地端口

3.1.3.1 通用端口 MCP 服务

直接在 servers/_common/index.ts 里面添加自己的 tool

3.1.3.2 独占端口 MCP 服务

1. 复制一份 servers/temperatureConversion 取名为自己的 mcp 业务名（myMCPService）

2. 添加相关工具（魔法镜子）

3. 在 config.json 中注册相关工具（端口唯一，从8080开始）

4. 构建、提交代码并构建对应分支

pnpm build
# 自动化读取配置

git add .
git commit -m xxxxxxxx
git push origin xxxxx

直接复制master，改下分支即可

http://xingyun.jd.com/jdosCD/ls/CI/bdsh-mcp-hub

3.1.5 把制品部署预发二

3.1.6 MCP 发布完毕

3.1.6.1 通用端口 MCP 服务

{
  "mcpServers": {
    "bdsh-common-mcp": {
      "timeout": 1000,
      "url": "http://11.125.20.213/sse",
      "type": "sse",
      "transportType": "sse",
      "headers": {
        "X-Target-Port": "8080"
      }
    }
  }
}

3.1.6.2 独占端口 MCP 服务

{
  "mcpServers": {
    "my-mcp-service": {
      "timeout": 1000,
      "url": "http://11.125.20.213/sse",
      "type": "sse",
      "transportType": "sse",
      "headers": {
        "X-Target-Port": "8082"
      }
    }
  }
}

3.1.7 使用 MCP 服务

3.1.8 Autobots 注册使用 MCP 插件

3.1.8.1 试运行 MCP 服务

3.1.9 合并master并重新走一遍部署流程

3.2 NPX形式（开发中...）

3.3 UVX形式（开发中...）

4. 项目开发

4.1 基础镜像构建

1. 使用 container/Dockerfile 构建系统镜像
2. 使用 docker/Dockerfile 构建容器镜像（运行镜像选择上一步构建的系统镜像）

4.2 nginx 日志查询（开发中...）