哔哩哔哩 MCP demo 的设计与实现

好久没发贴了，最近在学习mcp，这是一个基于Model Context Protocol (MCP) 的哔哩哔哩视频demo，包含服务器端和客户端的完整实现，有想学习mcp的小伙伴可以学习体验一下这个项目。

💡 提示: 实现过程鱼皮面试鸭mcp的实现 https://www.cnblogs.com/yupi/p/18814281

📁 项目结构

▼
text
复制代码
spring/
├── mcp-bilibili-server-main/     # MCP服务器端 - 提供哔哩哔哩API封装
│   ├── src/
│   │   └── main/
│   │       ├── java/              # Java源代码
│   │       └── resources/         # 配置文件
│   ├── pom.xml                    # Maven配置
│   └── README.md                  # 服务器端文档
│
└── mcp-bilibili-client/          # MCP客户端 - AI智能管理界面
    ├── src/
    │   ├── main/
    │   │   ├── java/              # Java源代码
    │   │   └── resources/         # 配置文件和静态资源
    │   └── test/                  # 测试代码
    ├── pom.xml                    # Maven配置
    └── README.md                  # 客户端文档

🌟 核心特性

🖥️ MCP服务器端 (mcp-bilibili-server-main)

• 基于Spring Boot 3.2.5 + JDK 21
• Spring AI MCP Server 1.0.0 标准实现
• STDIO通信模式 - 支持标准输入输出通信
• 完整的哔哩哔哩API封装

🛠️ 提供的MCP工具

1. setSessdata - 设置哔哩哔哩登录状态
2. searchVideos - 基础视频搜索
3. searchVideosFromWeb - 高级视频搜索（支持排序、筛选）
4. createDownloadTask - 创建视频下载任务
5. getDownloadStatus - 查询下载任务状态
6. getServerStatus - 获取服务器运行状态

🤖 MCP客户端 (mcp-bilibili-client)

• 基于Spring Boot 3.2.5 + JDK 21
• Spring AI MCP Client 1.0.0 标准实现
• 集成通义千问AI - 智能意图分析
• 双模式界面 - AI聊天 + 手动控制
• 实时步骤展示 - 完整的操作流程可视化

🎯 客户端功能

1. AI智能助手 - 自然语言交互，自动识别用户意图
2. 手动控制台 - 传统的API调用界面
3. 实时状态监控 - 连接状态、工具列表、服务器状态
4. 批量操作支持 - 搜索后自动批量下载
5. 错误处理机制 - 环环相扣，快速失败

🚀 快速开始

📋 环境要求

• Java 21+
• Maven 3.6+
• 哔哩哔哩账号 (用于获取SESSDATA)
• 通义千问API密钥 (用于AI功能)

🔧 安装与配置

1. 下载项目

代码已发布到GitHub，大家可以自行下载（如果可以麻烦大家点点star）

▼
bash
复制代码
 https://github.com/q2260391948/bilibili-mcp 

2. 配置服务器端

▼
bash
复制代码
cd mcp-bilibili-server-main
cp src/main/resources/application-example.yml src/main/resources/application.yml
# 编辑配置文件，设置必要的参数

3. 配置客户端

▼
bash
复制代码
cd ../mcp-bilibili-client
cp src/main/resources/application-example.yml src/main/resources/application.yml
# 配置通义千问API密钥和MCP服务器路径

4. 构建项目

▼
bash
复制代码
# 构建服务器端
cd mcp-bilibili-server-main
mvn clean package -DskipTests

# 构建客户端
cd ../mcp-bilibili-client
mvn clean package -DskipTests

🏃‍♂️ 运行应用

一：进入server

更新配置

打包

二：使用client进行调用

本地Client替换为本地的jar包路径

启动

三：使用外部client进行调用

配置 cursor mcp配置

▼
json
复制代码
{
  "mcpServers": {
    "bilibili-downloader": {
      "command": "C:\\Users\\Administrator\\.jdks\\ms-21.0.7\\bin\\java.exe",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
         //此处需替换为本地 Serever jar包绝对路径
        "E:\\学习\\MCP\\spring\\mcp-bilibili-server-main\\target\\bilibili-mcp-server-1.0.0-SNAPSHOT.jar"
      ],
      "env": {
        "JAVA_HOME": "C:\\Users\\Administrator\\.jdks\\ms-21.0.7"
      }
    }
  }
}

效果

绿色表示已经连接到了 MCP server，红色则表示连接失败

浅浅调用一下吧~

Cherry Studio 调用

🌐 访问界面

启动客户端后，可以通过以下地址访问：

• AI智能助手: http://localhost:8090/ai-chat.html
• 手动控制台: http://localhost:8090/index.html
• API文档: http://localhost:8090/swagger-ui.html (如果启用)

📖 使用指南

🤖 AI智能助手使用

AI助手支持自然语言交互，以下是一些使用示例：

1. 设置登录信息

▼
text
复制代码
设置SESSDATA=XXX

2. 搜索视频

▼
text
复制代码
搜索JAVA学习的视频

3. 下载(单个/批量)

▼
text
复制代码
下载JAVA学习的所有视频

单个

批量

4. 检查状态

▼
text
复制代码
检查系统状态

🎛️ 手动控制台使用

手动控制台提供传统的表单界面，支持：

• 系统状态监控
• 登录信息设置
• 视频搜索（基础和高级）
• 下载任务管理

🏗️ 技术架构

📊 整体架构图

▼
text
复制代码
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   前端界面       │    │   MCP客户端      │    │   MCP服务器     │
│ (HTML/JS/CSS)  │    │ (Spring Boot)    │    │ (Spring Boot)   │
├─────────────────┤    ├──────────────────┤    ├─────────────────┤
│ • AI聊天界面    │───▶│ • 通义千问集成   │───▶│ • 哔哩哔哩API   │
│ • 手动控制台    │    │ • MCP客户端      │    │ • 下载管理      │
│ • 实时反馈      │    │ • 意图分析       │    │ • 状态监控      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │   AI分析引擎     │    │  哔哩哔哩平台   │
                       │ (通义千问API)    │    │ (外部API服务)   │
                       └──────────────────┘    └─────────────────┘

🔧 核心组件

MCP服务器端

• BilibiliMcpServerApplication - 主启动类
• MCP工具实现 - 各种哔哩哔哩操作的封装
• STDIO通信 - 标准输入输出通信协议
• 配置管理 - Spring Boot配置体系

MCP客户端

• BilibiliMcpClientApplication - 主启动类
• SimpleAIService - 基于推理的意图分析
• AIBilibiliService - 通义千问AI集成（可选）
• BilibiliClientService - MCP客户端调用封装
• Web界面 - AI聊天和手动控制界面

📡 通信协议

项目使用标准的MCP (Model Context Protocol) 进行通信：

▼
text
复制代码
客户端 ──STDIO──▶ 服务器
       ◀──────── 

• 协议版本: MCP 1.0.0
• 通信方式: STDIO (标准输入输出)
• 数据格式: JSON-RPC 2.0
• 工具调用: 同步调用模式

🛠️ 开发指南

📝 添加新的MCP工具

服务器端

1. 在服务器端实现新的工具方法
2. 添加对应的参数验证
3. 更新工具列表

客户端

1. 在BilibiliClientService中添加调用方法
2. 在AI服务中添加意图识别
3. 更新前端界面（如需要）

🧪 测试

单元测试

▼
bash
复制代码
# 服务器端测试
cd mcp-bilibili-server-main
mvn test

# 客户端测试
cd mcp-bilibili-client
mvn test

集成测试

▼
bash
复制代码
# 启动服务器后，运行客户端测试
mvn test -Dtest=IntegrationTest

📦 构建与部署

开发环境

▼
bash
复制代码
mvn spring-boot:run

生产环境

▼
bash
复制代码
mvn clean package
java -jar target/app.jar

Docker部署

▼
dockerfile
复制代码
FROM openjdk:21-jre-slim
COPY target/app.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

🔧 配置说明

服务器端配置 (mcp-bilibili-server-main)

▼
yaml
复制代码
spring:
  ai:
    mcp:
      server:
        stdio: true  # 启用STDIO通信
  application:
    name: bilibili-mcp-server

# 哔哩哔哩相关配置
bilibili:
  api:
    base-url: https://api.bilibili.com
    timeout: 30s
  download:
    path: ./downloads
    concurrent: 3

客户端配置 (mcp-bilibili-client)

▼
yaml
复制代码
spring:
  ai:
    dashscope:
      api-key: ${AI_API_KEY}  # 通义千问API密钥
      chat:
        options:
          model: qwen-plus
    mcp:
      client:
        enabled: true
        stdio:
          connections:
            bilibili-server:
              command: java
              args:
                - -jar
                - ../mcp-bilibili-server-main/target/bilibili-mcp-server-1.0.0-SNAPSHOT.jar

server:
  port: 8090

🔍 故障排除

常见问题

1. MCP连接失败

症状: 客户端显示"MCP客户端未连接" 解决方案:

• 检查服务器是否正常启动
• 确认JAR文件路径正确
• 查看日志中的详细错误信息

2. AI调用失败

症状: AI分析返回错误 解决方案:

• 检查通义千问API密钥是否正确
• 确认网络连接正常
• 查看API调用限制

3. 视频下载失败

症状: 下载任务创建失败 解决方案:

• 确认SESSDATA已正确设置
• 检查视频链接或BV号有效性
• 确认磁盘空间充足

4. 权限问题

症状: 无法访问哔哩哔哩API 解决方案:

• 检查SESSDATA是否过期
• 确认账号状态正常
• 检查IP是否被限制

📋 日志排查

启用调试日志

▼
yaml
复制代码
logging:
  level:
    com.demo.mcp: DEBUG
    org.springframework.ai: DEBUG
    root: INFO

关键日志位置

• MCP通信日志: org.springframework.ai.mcp
• 业务逻辑日志: com.demo.mcp
• HTTP请求日志: org.springframework.web

📊 性能监控

关键指标

• MCP连接状态: 客户端与服务器的连接健康度
• API响应时间: 哔哩哔哩API调用延迟
• 下载任务数量: 当前活跃的下载任务
• 内存使用率: JVM内存占用情况

监控端点

• 健康检查: /actuator/health
• 指标信息: /actuator/metrics
• MCP状态: /api/bilibili/status

🔐 安全说明

敏感信息保护

• SESSDATA: 妥善保管，定期更换
• API密钥: 使用环境变量，不要硬编码
• 日志脱敏: 避免在日志中输出敏感信息

网络安全

• HTTPS: 生产环境建议使用HTTPS
• 防火墙: 限制不必要的端口访问
• 认证授权: 考虑添加用户认证机制

🤝 贡献指南

提交代码

1. Fork项目
2. 创建特性分支
3. 提交更改
4. 创建Pull Request

代码规范

• 使用Java代码规范
• 添加必要的注释
• 编写单元测试
• 更新相关文档

💡 提示: 这是一个教育和学习项目，仅作为学习使用，遵守相关平台的使用条款。