Band MCP Server

🚀 Band MCP Server

Band MCP Server 是一个功能完备的模型上下文协议（MCP）服务器，它与 Band API 集成。该服务器支持 AI 助手和其他 MCP 兼容工具与 Band 社交平台数据进行无缝交互。

🚀 快速开始

前提条件

• Band API 访问令牌（可从 Band 开发者门户 获取）
• 支持 MCP 的 VS Code 或任何 MCP 兼容客户端
• Docker（用于容器化部署）

VS Code 集成

将以下配置添加到你的 VS Code settings.json 中：

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "band_access_token",
        "description": "BAND Access Token",
        "password": true
      }
    ],
    "servers": {
      "band-mcp-server": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "-e", "BAND_ACCESS_TOKEN", "kanghouchao/band-mcp-server:latest"],
        "env": {
          "BAND_ACCESS_TOKEN": "${input:band_access_token}"
        }
      }
    }
  }
}

本地开发

# 克隆仓库
git clone <repository-url>
cd band-mcp-server

# 安装依赖
make install
# 或者
npm install

# 设置环境变量
echo "BAND_ACCESS_TOKEN=your_token_here" > .env

# 以开发模式运行
make dev
# 或者
npm run dev

# 构建项目
make build
# 或者
npm run build

# 运行测试
make test
# 或者
npm test

Docker 部署

# 构建 Docker 镜像
make docker-build
# 或者
docker build -t band-mcp-server:latest .

# 运行 Docker 容器
make docker-run
# 或者
docker run --rm -i -e BAND_ACCESS_TOKEN=your_token_here band-mcp-server:latest

✨ 主要特性

• ✅ 访问令牌认证：使用 Band API 访问令牌进行安全认证。
• ✅ 完整的 Band API 覆盖：全面实现所有主要的 Band API 端点。
• ✅ 读写操作：对帖子、评论和群组数据进行全面的 CRUD 操作。
• ✅ MCP 集成：提供原生 MCP 工具和资源，实现与 AI 的无缝集成。
• ✅ Docker 部署：支持生产环境的容器化部署。
• ✅ TypeScript 实现：类型安全的实现，具备完整的错误处理。
• ✅ 自动化 CI/CD：持续集成和自动化 Docker 构建。

📦 安装指南

项目状态：可用于生产环境

版本：1.0.3
Docker 镜像：kanghouchao/band-mcp-server:latest

此 MCP 服务器已完全实现，并提供对 Band API 功能的完整访问，包括用户资料、群组管理、帖子、评论、相册和照片，具备完整的读写能力。

💻 使用示例

基础用法

// 获取用户所属的所有群组
await mcp.callTool("get_bands", {});

// 获取特定群组的近期帖子
await mcp.callTool("get_posts", {
  band_key: "AADoj33YIR6g5reUiHGZx0wj",
  limit: 20
});

// 创建新帖子
await mcp.callTool("write_post", {
  band_key: "AADoj33YIR6g5reUiHGZx0wj",
  content: "Hello from MCP! 🚀",
  do_push: false
});

// 为帖子添加评论
await mcp.callTool("write_comment", {
  band_key: "AADoj33YIR6g5reUiHGZx0wj",
  post_key: "AAB8tbywKWMoGQFLqd_EhiBD",
  body: "Great post! 👍"
});

📚 详细文档

可用的 MCP 工具

用户与群组管理

• get_user_information - 获取 Band 群组的用户资料信息。
• get_bands - 获取已认证用户所属的所有 Band 群组列表。
• permissions - 检查用户对特定 Band 的权限（发帖、评论、删除权限）。

帖子与内容

• get_posts - 支持分页获取特定 Band 的帖子。
• get_post - 获取特定帖子的详细信息。
• write_post - 在 Band 群组中创建新帖子。
• remove_post - 从 Band 中删除帖子（需要相应权限）。

评论与互动

• get_comments - 支持排序获取特定帖子的评论。
• write_comment - 为帖子添加评论。
• remove_comment - 从帖子中删除评论（需要相应权限）。

媒体与相册

• get_albums - 获取 Band 群组中的相册。
• get_photos - 从特定相册中获取照片。

🔧 技术细节

错误处理与 API 限制

服务器实现了全面的错误处理，并遵守 Band API 速率限制：

• 认证错误：对于无效或过期的令牌，提供清晰的错误消息。
• 权限错误：当操作需要更高权限时，提供详细反馈。
• 速率限制：自动处理 API 速率限制，并进行适当延迟。
• 验证：使用 Zod 模式对所有参数进行输入验证。
• 日志记录：提供全面的日志记录，用于调试和监控。

开发与测试

项目结构

src/
├── index.ts          # 主 MCP 服务器入口点
├── tools.ts          # 工具定义和路由
├── client.ts         # Band API 客户端
├── config.ts         # 配置管理
└── [feature]/        # 单个工具实现
    ├── index.ts      # 工具定义
    └── tool.ts       # 工具实现

可用脚本

• npm run dev - 开发模式，支持热重载。
• npm run build - 将 TypeScript 编译为 JavaScript。
• npm run test - 运行测试套件。
• npm run lint - 运行 ESLint。
• make help - 显示所有可用的 Makefile 命令。

故障排除

常见问题

“认证失败”

• 验证你的 Band API 访问令牌是否有效且未过期。
• 确保令牌具有你尝试执行的操作所需的权限。
• 检查令牌是否正确设置在环境变量 BAND_ACCESS_TOKEN 中。

“权限被拒绝” 错误

• 某些操作需要在 Band 中具有特定角色（领导者、副领导者等）。
• 使用 permissions 工具检查你对特定 Band 的访问权限。
• 联系 Band 管理员请求相应权限。

Docker 容器问题

• 确保 Docker 正在运行，并且你有足够的权限。
• 检查环境变量是否正确传递给容器。
• 验证 Docker 镜像是否为最新版本：docker pull kanghouchao/band-mcp-server:latest。

MCP 客户端连接问题

• 验证你的 MCP 客户端是否支持所需的协议版本。
• 检查服务器命令和参数是否正确配置。
• 查看 VS Code 或客户端日志以获取详细错误消息。

调试模式

要启用详细日志记录，请设置环境变量：

export DEBUG=band-mcp-server:*

贡献

我们欢迎贡献！请遵循以下准则：

1. 分叉仓库 并创建功能分支。
2. 为新功能编写测试。
3. 遵循 TypeScript 最佳实践 并保持类型安全。
4. 更新文档 以反映任何 API 更改。
5. 在提交前运行测试和代码检查：

   npm run test
   npm run lint
   

6. 提交拉取请求 并清晰描述更改内容。

开发工作流程

# 设置开发环境
git clone <your-fork>
cd band-mcp-server
npm install

# 创建功能分支
git checkout -b feature/your-feature-name

# 进行更改并测试
npm run dev
npm run test

# 提交并推送
git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name

路线图

计划改进

• [ ] 优化响应数据，提高 AI 处理性能。
• [ ] 提供用于复杂操作的组合 API 工具。
• [ ] 增强错误恢复和重试机制。
• [ ] 覆盖更多的 Band API 端点。
• [ ] 性能监控和指标。
• [ ] 错误消息的多语言支持。

性能优化

当前重点是优化 API 响应数据，通过以下方式提高 AI 处理速度：

• 过滤不必要的数据字段。
• 实现选择性字段查询。
• 减小有效负载大小以提高性能。

安全考虑

• 令牌安全：切勿将访问令牌提交到版本控制。
• 环境变量：始终使用环境变量存储敏感数据。
• 权限：在请求 API 权限时遵循最小权限原则。
• 速率限制：遵守 Band API 速率限制，避免服务中断。
• 输入验证：使用 Zod 模式验证所有输入。

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件了解详细信息。

维护者：kanghouchao
Docker Hub：kanghouchao/band-mcp-server
问题反馈：请通过 GitHub Issues 报告错误和提出功能请求。