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 報告錯誤和提出功能請求。