蓝牙 MCP 服务器

用于蓝牙设备检测的模型上下文协议服务器

🔍 概述

此项目实现了一个模型上下文协议（MCP）服务器，使 Claude 和其他 AI 助手能够扫描并与其附近的蓝牙设备进行交互。通过测试驱动开发方法构建，它为跨多个平台的蓝牙操作提供了一个强大且经过测试的接口。

✨ 特性

📡 多协议扫描：同时检测 BLE 和经典蓝牙设备
🔎 灵活过滤：按名称、类型或其他属性过滤设备
🔄 自动设备识别：识别并分类常见设备（如 Freebox、电视等）
📱 增强设备信息：获取制造商信息、设备类型和详细特性
🖥️ 跨平台支持：适用于 Windows、macOS 和 Linux
⚡ 特定平台优化：在 Windows 上增强检测能力
🤖 MCP 集成：与 Claude 和兼容的 AI 助手无缝集成

📋 要求

Python 3.7+
蓝牙适配器（内置或外置）
管理员/sudo 权限（某些蓝牙操作需要）
互联网连接（用于安装包）

🚀 快速开始

安装

# 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 一起使用

使用 ngrok 或将其部署到服务器上将您的服务器暴露到互联网：
```
ngrok http 8000
```

配置 Claude 以使用您的 MCP 服务器：

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

让 Claude 扫描附近的蓝牙设备：

你能扫描一下附近的蓝牙设备吗？

🧪 测试

该项目遵循测试驱动开发（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。

🔧 故障排除

蓝牙问题

“访问被拒绝”错误：以管理员/sudo 权限运行服务器
未检测到适配器：确保系统设置中启用了蓝牙
未找到设备：确保附近有可发现的蓝牙设备
Windows 特定问题：检查蓝牙服务是否处于活动状态 (services.msc)

MCP 问题

Claude 未检测到工具: 请验证您的 MCP 服务器 URL 是否正确且可访问
执行错误: 请检查服务器日志以获取详细的错误信息

👥 贡献

欢迎贡献！请遵循以下步骤：

Fork 仓库
创建一个功能分支 (git checkout -b feature/amazing-feature)
为您的功能编写测试
实现您的功能
确保所有测试通过
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

FastAPI 提供 API 框架
Bleak 提供跨平台蓝牙功能
Anthropic Claude 提供 MCP 集成支持