Bluetooth MCP Server

Bluetooth MCP Server

🔍 概要

このプロジェクトは、Claude やその他の AI アシスタントが、近くにある Bluetooth デバイスをスキャンして操作できるようにする Model Context Protocol（MCP）サーバーを実装しています。テスト駆動開発のアプローチで構築されており、複数のプラットフォームで Bluetooth 操作を行うための、堅牢でテスト済みのインターフェースを提供します。

✨ 特長

• 📡 マルチプロトコルスキャン：BLE と Classic Bluetooth の両方のデバイスを検出します
• 🔎 柔軟なフィルタリング：名前、種類、その他の属性でデバイスを絞り込めます
• 🔄 デバイスの自動認識：よくあるデバイス（Freebox、テレビなど）を識別して分類します
• 📱 拡充されたデバイス情報：メーカー情報、デバイスの種類、詳細な特性を取得できます
• 🖥️ クロスプラットフォーム対応：Windows、macOS、Linux で動作します
• ⚡ プラットフォーム固有の最適化：Windows では検出機能が強化されています
• 🤖 MCP 連携：Claude および互換性のある AI アシスタントとシームレスに連携します

📋 要件

• Python 3.7+
• Bluetooth アダプター（内蔵または外付け）
• 管理者／sudo 権限（一部の Bluetooth 操作で必要）
• インターネット接続（パッケージのインストール用）

🚀 クイックスタート

インストール

# Clone the repository
git clone https://github.com/yourusername/bluetooth-mcp-server.git
cd bluetooth-mcp-server

# Create and activate virtual environment
python -m venv venv

# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit the .env file as needed

サーバーの起動

# Start the Bluetooth API server
python run.py

# In another terminal, start the MCP server
python bluetooth_mcp_server.py

Claude での使用

1. ngrok を使用するか、サーバーにデプロイして、サーバーをインターネットに公開します：

   ngrok http 8000
   

2. MCP サーバーを使用するよう Claude を設定します：

   npx @anthropic-ai/sdk install-model-context-protocol <YOUR_SERVER_URL>
   

3. Bluetooth デバイスをスキャンするよう Claude に依頼します：

   Could you scan for nearby Bluetooth devices?
   

🧪 テスト

このプロジェクトでは、包括的なテストカバレッジを備えたテスト駆動開発（TDD）アプローチを採用しています：

# Run all tests
pytest

# Run specific test categories
pytest tests/api/       # API tests
pytest tests/models/    # Data model tests
pytest tests/services/  # Service logic tests
pytest tests/utils/     # Utility function tests

🏗️ アーキテクチャ

このプロジェクトは、関心事を明確に分離したモジュール型アーキテクチャを採用しています：

bluetooth-mcp-server/
├── app/                # Main application package
│   ├── api/            # FastAPI endpoints
│   ├── core/           # Core configuration
│   ├── data/           # Static data (Bluetooth identifiers, etc.)
│   ├── models/         # Data models
│   ├── services/       # Business logic
│   └── utils/          # Utility functions
├── mcp_sdk/            # MCP integration SDK
└── tests/              # Test suites

アーキテクチャの詳細については、architecture.md を参照してください。

🔧 トラブルシューティング

Bluetooth の問題

• 「アクセスが拒否されました」エラー：管理者／sudo 権限でサーバーを実行してください
• アダプターが検出されない：システム設定で Bluetooth が有効になっていることを確認してください
• デバイスが見つからない：近くに検出可能な Bluetooth デバイスがあることを確認してください
• Windows 固有の問題：Bluetooth サービスが有効であることを確認してください（services.msc）

MCP の問題

• Claude がツールを検出しない：MCP サーバーの URL が正しく、アクセス可能であることを確認してください
• 実行エラー：サーバーログで詳細なエラー情報を確認してください

👥 貢献

貢献を歓迎します！次の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 追加する機能のテストを記述します
4. 機能を実装します
5. すべてのテストが成功することを確認します
6. 変更をコミットします（git commit -m 'Add amazing feature'）
7. ブランチにプッシュします（git push origin feature/amazing-feature）
8. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルを参照してください。

🙏 謝辞

• API フレームワークとしての FastAPI
• クロスプラットフォームの Bluetooth 機能を提供する Bleak
• MCP 連携のサポートを提供する Anthropic Claude