使用说明

项目简介

BirdNet-Pi MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在桥接 BirdNet-Pi 鸟类声音识别系统和大型语言模型 (LLM) 客户端。通过该服务器，LLM 应用可以方便地访问 BirdNet-Pi 收集的鸟类检测数据、音频录音以及相关的统计分析功能，从而构建更智能的鸟类识别和分析应用。

主要功能点

鸟类检测数据检索: 根据日期范围和鸟类种类筛选 BirdNet-Pi 的鸟类检测记录。
检测统计分析: 获取指定时间段内的鸟类检测统计信息，例如检测次数、物种数量等。
音频录音访问: 获取与鸟类检测事件相关的音频录音文件。
每日活动模式分析: 分析特定日期鸟类的活动模式，例如按小时的活动频率。
检测报告生成: 生成鸟类检测报告，支持 HTML 和 JSON 格式。

安装步骤

克隆仓库:

git clone https://github.com/MCP-Mirror/DMontgomery40_mcp-local-server.git
cd DMontgomery40_mcp-local-server

创建并激活虚拟环境 (推荐):

python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

安装依赖:

pip install -r requirements.txt

配置数据目录: 创建用于存放音频和报告的数据目录（如果 'data' 目录不存在）。
```
mkdir -p data/audio data/reports
```
注意: 默认配置下，服务器假设检测数据文件 'detections.json' 位于 'data' 目录下，音频文件位于 'data/audio' 目录下，报告文件位于 'data/reports' 目录下。你需要根据实际情况将 BirdNet-Pi 的数据文件复制或链接到这些位置，或者通过环境变量配置正确的路径。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令才能连接。以下是一个 MCP 客户端配置示例，你需要根据你的实际环境进行调整。

{
  "mcpServers": {
    "birdnet_server": {  // 服务器名称，可以自定义
      "command": "python",  // 启动命令，这里使用 python
      "args": ["server.py"], // 启动命令参数，指定运行 server.py 文件
      "cwd": "/path/to/DMontgomery40_mcp-local-server", // MCP 服务器代码仓库的绝对路径，请替换为实际路径
      "env": {
        "BIRDNET_DETECTIONS_FILE": "/path/to/birdnet-pi/data/detections.json", // BirdNet-Pi 检测数据文件路径，请替换为实际路径
        "BIRDNET_AUDIO_DIR": "/path/to/birdnet-pi/audio", // BirdNet-Pi 音频文件目录路径，请替换为实际路径
        "BIRDNET_REPORT_DIR": "/path/to/DMontgomery40_mcp-local-server/data/reports" // MCP 服务器报告输出目录，可选，请替换为实际路径
      }
    }
  }
}

配置说明:

'"birdnet_server"': 为 MCP 服务器自定义的名称，客户端用此名称引用服务器。
'"command"': 启动服务器的命令，通常为 'python'。
'"args"': 启动命令的参数，这里指定运行 'server.py' 文件。
'"cwd"': (重要) 请务必替换为 DMontgomery40_mcp-local_server 仓库在你的系统中的绝对路径。 这是 MCP 客户端找到并启动服务器的关键。
'"env"': (重要) 环境变量配置，用于服务器读取配置文件。
- '"BIRDNET_DETECTIONS_FILE"': 请务必替换为你的 BirdNet-Pi 'detections.json' 文件的实际路径。 服务器将从这个文件读取鸟类检测数据。
- '"BIRDNET_AUDIO_DIR"': 请务必替换为你的 BirdNet-Pi 音频文件存储目录的实际路径。 服务器将从这个目录访问音频文件。
- '"BIRDNET_REPORT_DIR"': 可选配置，指定报告输出目录。如果 BirdNet-Pi 的数据和音频文件位于默认位置，并且报告输出目录也使用默认的 'data/reports'，则可以省略此环境变量或使用默认值。

确保 MCP 客户端能够正确读取到以上配置信息，才能与 MCP 服务器建立连接并正常工作。

基本使用方法

启动服务器: 在终端中，进入 'DMontgomery40_mcp-local-server' 仓库目录，并确保虚拟环境已激活，然后运行：
```
python server.py
```
服务器默认会在 'http://localhost:8000' 启动。
MCP 客户端请求: MCP 客户端需要按照 MCP 协议规范，通过 JSON-RPC 格式向服务器发送请求。
- 获取可用功能列表: 客户端可以向服务器根路径 '/' 发送 JSON-RPC 请求，方法名设置为 'mcp.getFunctions'，以获取服务器支持的功能列表及其参数定义。
- 调用功能: 客户端可以通过向服务器根路径 '/' 发送 JSON-RPC 请求，方法名设置为要调用的功能名称（例如 'getBirdDetections'），并在 'params' 字段中传递功能所需的参数。
具体的功能调用方法和参数，请参考 API Endpoints 和 Available Functions 部分的描述，以及服务器返回的 'mcp.getFunctions' 响应。

示例 (使用 curl 模拟 JSON-RPC 请求):

获取可用功能列表:

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "mcp.getFunctions", "id": 1}' http://localhost:8000/

调用 'getBirdDetections' 功能:

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "getBirdDetections", "params": {"startDate": "2023-01-01", "endDate": "2023-01-07"}, "id": 2}' http://localhost:8000/

请根据实际需求和功能参数定义，构建你的 MCP 客户端请求。

关键词