JinDaGe - BirdNet-Pi MCP Details

article

README

🚀 鸟类网络Pi MCP服务器

这是一个基于Python的模型上下文协议（MCP）服务器，专为鸟类网络Pi集成而设计。它能够助力用户高效检索鸟类检测数据、开展检测统计分析、访问音频录音、了解日活动模式以及生成相关报告。

🚀 快速开始

本服务器基于Python构建，借助FastAPI和Uvicorn运行。以下是启动服务器的详细步骤：

安装依赖

克隆仓库：

git clone https://github.com/YourUsername/mcp-server.git
cd mcp-server

创建虚拟环境并激活它：

python -m venv venv
source venv/bin/activate  # 在Windows上使用：venv\Scripts\activate

安装依赖项：

pip install -r requirements.txt

mkdir -p data/audio data/reports

配置服务器

服务器可以通过环境变量进行配置：

BIRDNET_DETECTIONS_FILE：检测JSON文件的路径（默认：'data/detections.json'）
BIRDNET_AUDIO_DIR：音频文件目录的路径（默认：'data/audio'）
BIRDNET_REPORT_DIR：报告目录的路径（默认：'data/reports'）

启动服务器

python server.py

服务器将在http://localhost:8000上运行。

✨ 主要特性

数据检索：根据日期和物种过滤检索鸟类检测数据。
统计分析：提供检测统计信息和分析。
音频访问：支持音频录音访问。
活动模式：可查看日活动模式。
报告生成：能够生成相关报告。

💻 使用示例

基础用法

以下是调用getBirdDetections函数的示例：

import requests

url = 'http://localhost:8000/invoke'
data = {
    "name": "getBirdDetections",
    "parameters": {
        "startDate": "2024-01-01",
        "endDate": "2024-01-31",
        "species": "Sparrow"
    }
}

response = requests.post(url, json=data)
print(response.json())

高级用法

以下是调用generateDetectionReport函数生成HTML报告的示例：

import requests

url = 'http://localhost:8000/invoke'
data = {
    "name": "generateDetectionReport",
    "parameters": {
        "startDate": "2024-01-01",
        "endDate": "2024-01-31",
        "format": "html"
    }
}

response = requests.post(url, json=data)
with open('report.html', 'w') as f:
    f.write(response.text)

📚 详细文档

API端点

/functions - 列出可用函数（GET）
/invoke - 调用一个函数（POST）

可用函数

getBirdDetections
- 获取根据日期范围和物种过滤的鸟类检测数据
- 参数：startDate，endDate，species（可选）
getDetectionStats
- 获取时间段内的检测统计信息
- 参数：period（'day'，'week'，'month'，'all'），minConfidence（可选）
getAudioRecording
- 获取检测的音频录音
- 参数：filename，format（'base64'或'buffer'）
getDailyActivity
- 获取特定日期的鸟类活动模式
- 参数：date，species（可选）
generateDetectionReport
- 生成检测报告
- 参数：startDate，endDate，format（'html'或'json'）

🔧 技术细节

本项目使用Python 3.8+作为开发语言，借助FastAPI框架搭建API服务，使用Uvicorn作为服务器运行。项目的核心逻辑封装在birdnet目录下的各个模块中，通过环境变量进行配置，方便灵活部署。

📦 项目结构

mcp-server/
├── birdnet/
│   ├── __init__.py
│   ├── config.py
│   ├── functions.py
│   └── utils.py
├── data/
│   ├── audio/
│   └── reports/
├── server.py
├── requirements.txt
└── README.md

BirdNet-Pi