Band MCP Server

🚀 Band MCP Server

完全に機能するModel Context Protocol (MCP)サーバーで、Band APIと統合されています。このサーバーにより、AIアシスタントやその他のMCP互換ツールを通じて、Bandソーシャルプラットフォームのデータとシームレスにやり取りすることができます。

✨ 主な機能

✅ アクセストークン認証：Band APIのアクセストークンを使用した安全な認証
✅ 完全なBand APIカバレッジ：主要なBand APIエンドポイントの完全実装
✅ 読み取り/書き込み操作：投稿、コメント、バンドデータの包括的なCRUD操作
✅ MCP統合：AIとのシームレスな統合のためのネイティブMCPツールとリソース
✅ Dockerデプロイメント：本番環境で使用可能なコンテナ化されたデプロイメント
✅ TypeScript実装：完全なエラーハンドリングを備えた型安全な実装
✅ 自動化されたCI/CD：継続的インテグレーションと自動化されたDockerビルド

🚀 クイックスタート

前提条件

• Band APIアクセストークン（Band Developer Portalから取得可能）
• 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

💻 使用例

基本的な使用法

// ユーザーが所属するすべてのバンドを取得する
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 - バンドグループのユーザープロファイル情報を取得する
• get_bands - 認証されたユーザーが所属するすべてのバンドグループのリストを取得する
• permissions - 特定のバンドに対するユーザーの権限を確認する（投稿、コメント、削除権限）

投稿とコンテンツ

• get_posts - ページネーションをサポートして、特定のバンドから投稿を取得する
• get_post - 特定の投稿の詳細情報を取得する
• write_post - バンドグループに新しい投稿を作成する
• remove_post - バンドから投稿を削除する（適切な権限が必要）

コメントとインタラクション

• get_comments - ソートオプション付きで、特定の投稿のコメントを取得する
• write_comment - 投稿にコメントを追加する
• remove_comment - 投稿からコメントを削除する（適切な権限が必要）

メディアとアルバム

• get_albums - バンドグループの写真アルバムを取得する
• get_photos - 特定のアルバムから写真を取得する

開発とテスト

プロジェクト構造

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コマンドを表示する

トラブルシューティング

一般的な問題

"Authentication failed"

• Band APIアクセストークンが有効で期限切れでないことを確認する
• トークンが実行しようとしている操作に必要な権限を持っていることを確認する
• トークンが環境変数BAND_ACCESS_TOKENに正しく設定されていることを確認する

"Permission denied"エラー

• 一部の操作には、バンド内の特定の役割（リーダー、副リーダーなど）が必要です
• permissionsツールを使用して、特定のバンドに対するアクセス権を確認する
• 適切な権限を要求するために、バンド管理者に連絡する

Dockerコンテナの問題

• Dockerが実行中で、十分な権限があることを確認する
• 環境変数がコンテナに正しく渡されていることを確認する
• Dockerイメージが最新であることを確認する：docker pull kanghouchao/band-mcp-server:latest

MCPクライアントの接続問題

• MCPクライアントが必要なプロトコルバージョンをサポートしていることを確認する
• サーバーコマンドと引数が正しく構成されていることを確認する
• VS Codeまたはクライアントのログを確認して、詳細なエラーメッセージを確認する

デバッグモード

詳細なログを有効にするには、環境変数を設定します。

export DEBUG=band-mcp-server:*

🔧 技術詳細

エラーハンドリングと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コマンドを表示する

🤝 コントリビュート

コントリビューションを歓迎します！ 次のガイドラインに従ってください。

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

📄 ライセンス

MIT License - 詳細はLICENSEファイルを参照してください。

メンテナ：kanghouchao
Docker Hub：kanghouchao/band-mcp-server
問題報告：バグや機能要求はGitHub Issuesを通じて報告してください