Blue Archive MCP 服务器

一个提供全面访问《碧蓝档案》游戏数据的模型上下文协议（MCP）服务器，包括学生信息、装备、关卡、物品等。

目录

• 概览
• 功能
• 安装
• 配置
• 可用工具
• 使用示例
• 开发
• 故障排除
• 贡献
• 许可证

概览

Blue Archive MCP 服务器与 SchaleDB API 集成，为 AI 助手提供实时访问《碧蓝档案》游戏数据的功能。该服务器实现了模型上下文协议，能够与支持 MCP 的客户端（如 Claude Desktop）无缝集成。

主要功能

• 学生数据库：访问所有《碧蓝档案》学生的详细信息
• 装备和物品：浏览武器、装备和消耗品
• 关卡信息：获取战役关卡和突袭战的详细信息
• 多媒体内容：检索学生头像和语音片段
• 高级搜索：跨所有数据类型进行过滤和搜索
• 多语言支持：支持中文、日语和英语

功能

• ✅ 8个全面工具 用于访问游戏数据
• 🌐 多语言支持 (CN/JP/EN)
• 🔍 高级过滤 和搜索功能
• 🖼️ 丰富的媒体集成 (头像, 语音片段)
• ⚡ 性能优化 带有缓存
• 🛡️ 错误处理 和重试机制
• 📱 响应式数据格式 (文本/Markdown)

安装

前提条件

• Node.js 18+
• npm 或 yarn 包管理器
• 支持 MCP 的客户端（例如 Claude Desktop）

方法 1：NPM 安装（推荐）

直接从 NPM 安装：

npm install -g blue-archive-mcp

或者在你的项目中本地安装：

npm install blue-archive-mcp

方法 2：从源代码安装

1. 克隆仓库

   git clone <repository-url>
   cd blue_archive_mcp
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

4. 测试服务器

   npm start
   

配置

Claude Desktop 集成

将以下配置添加到你的 Claude Desktop 配置文件中：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

对于 NPM 安装：

{

  "mcpServers": {

    "blue-archive": {

      "command": "npx",

      "args": ["blue-archive-mcp"],

      "env": {

        "NODE_ENV": "production"

      }

    }

  }

}

对于源代码安装：

{

  "mcpServers": {

    "blue-archive": {

      "command": "node",

      "args": ["path/to/blue_archive_mcp/dist/index.js"],

      "env": {

        "NODE_ENV": "production"

      }

    }

  }

}

环境变量

可用工具

1. get_students

检索带有过滤选项的学生信息。

参数:

• language (字符串, 可选): 语言偏好 (cn/jp/en) - 默认: "cn"
• search (字符串, 可选): 按学生姓名搜索
• limit (数字, 可选): 最大结果数 - 默认: 20
• detailed (布尔值, 可选): 包含详细统计数据 - 默认: false
• school (字符串, 可选): 按学校筛选
• starGrade (数字, 可选): 按星级等级筛选 (1-3)
• role (字符串, 可选): 按战术角色筛选

2. get_student_info

获取特定学生的详细信息。

参数:

• studentId (数字, 必填): 学生的唯一 ID
• language (字符串, 可选): 语言偏好 - 默认: "cn"

3. get_student_by_name

按名称查找学生（支持多种语言）。

参数:

• name (字符串, 必填): 任何支持语言中的学生姓名
• language (字符串, 可选): 响应语言 - 默认: "cn"
• detailed (布尔值, 可选): 包含详细信息 - 默认: false

4. get_raids

检索突袭战信息和 Boss 数据。

参数:

• language (字符串, 可选): 语言偏好 - 默认: "cn"
• search (字符串, 可选): 按突袭战名称搜索- detailed (布尔值，可选)：包含详细统计信息 - 默认值：false

5. get_equipment

浏览装备和武器数据。

参数：

• language (字符串，可选)：语言偏好 - 默认值："cn"
• category (字符串，可选)：装备类别过滤
• tier (数字，可选)：装备等级 (1-7)
• limit (数字，可选)：最大结果数 - 默认值：20
• detailed (布尔值，可选)：包含详细统计信息 - 默认值：false

6. get_stages

访问战役和关卡信息。

参数：

• language (字符串，可选)：语言偏好 - 默认值："cn"
• search (字符串，可选)：按关卡名称搜索
• area (字符串，可选)：按区域过滤
• chapter (字符串，可选)：按章节过滤
• difficulty (字符串，可选)：按难度过滤
• limit (数字，可选)：最大结果数 - 默认值：20
• detailed (布尔值，可选)：包含详细信息 - 默认值：false

7. get_items

检索消耗品和材料。

参数：

• language (字符串，可选)：语言偏好 - 默认值："cn"
• search (字符串，可选)：按物品名称搜索
• category (字符串，可选)：物品类别过滤
• rarity (数字，可选)：物品稀有度 (1-5)
• tags (字符串，可选)：按标签过滤
• limit (数字，可选)：最大结果数 - 默认值：20
• detailed (布尔值，可选)：包含详细信息 - 默认值：false

8. get_student_avatar

获取学生头像的各种格式。

参数：

• studentId (数字，可选)：学生的唯一ID
• name (字符串，可选)：学生姓名（替代ID）
• language (字符串，可选)：语言偏好 - 默认值："cn"
• avatarType (字符串，可选)：头像类型 (portrait/collection/icon/lobby) - 默认值："portrait"
• format (字符串，可选)：输出格式 (markdown/md) - 默认值："markdown"

使用示例

基本学生搜索

Find all students from Gehenna Academy

详细学生信息

Get detailed information about Shiroko including stats and skills

装备浏览

Show me all tier 6 weapons with detailed stats

关卡信息

Find all hard difficulty stages in chapter 3

头像显示

Show me Hina's collection avatar in markdown format

开发

项目结构

blue_archive_mcp/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

从源代码构建

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start development server
npm start

代码架构

服务器使用以下技术构建：

• TypeScript 用于类型安全和现代JavaScript特性
• @modelcontextprotocol/sdk 用于MCP协议实现
• Zod 用于运行时类型验证和模式生成
• SchaleDB API 作为主要数据源

关键组件

• BlueArchiveMCPServer：处理MCP协议的主要服务器类
• SchaleDBClient：用于数据获取的API客户端
• ErrorHandler：集中错误处理和日志记录
• ParameterHandler：输入验证和规范化
• Logger：结构化日志系统

故障排除

常见问题

连接问题

• 症状：服务器无法启动或连接
• 解决方案：检查Node.js版本（需要18+）并验证配置路径

数据加载失败

• 症状：API请求返回空结果
• 解决方案：验证互联网连接和SchaleDB API可用性

工具未显示

• 症状：工具未在Claude Desktop中显示
• 解决方案：在配置更改后重启Claude Desktop

调试模式

通过设置环境变量启用调试日志：

LOG_LEVEL=debug npm start

性能优化

• 默认情况下，数据缓存5分钟
• 当不需要完整数据时，使用detailed=false以获得更快的响应
• 使用limit参数限制结果集

贡献

我们欢迎贡献！请遵循以下指南：

1. Fork 仓库
2. 创建 功能分支 (git checkout -b feature/amazing-feature)
3. 提交 您的更改 (git commit -m 'Add amazing feature')
4. 推送 到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

开发指南

• 遵循TypeScript最佳实践- 添加适当的错误处理
• 为新函数添加JSDoc注释
• 在提交前彻底测试更改

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。

数据来源

此服务器使用来自SchaleDB的数据，这是一个开源的Blue Archive数据库。所有游戏资源和数据均归其各自所有者所有。

注意：这是一个由粉丝为Blue Archive社区创建的非官方工具。它与游戏的官方开发者没有任何关联，也未得到他们的认可。