Birdnet Pi

🚀 鳥類網絡Pi MCP服務器

這是一個基於Python的模型上下文協議（MCP）服務器，專為鳥類網絡Pi集成而設計。它能夠助力用戶高效檢索鳥類檢測數據、開展檢測統計分析、訪問音頻錄音、瞭解日活動模式以及生成相關報告。

🚀 快速開始

本服務器基於Python構建，藉助FastAPI和Uvicorn運行。以下是啟動服務器的詳細步驟：

安裝依賴

1. 克隆倉庫：

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

2. 創建虛擬環境並激活它：

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

3. 安裝依賴項：

pip install -r requirements.txt

4. 設置數據目錄：

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）

可用函數

1. getBirdDetections

   • 獲取根據日期範圍和物種過濾的鳥類檢測數據
   • 參數：startDate，endDate，species（可選）

2. getDetectionStats

   • 獲取時間段內的檢測統計信息
   • 參數：period（'day'，'week'，'month'，'all'），minConfidence（可選）

3. getAudioRecording

   • 獲取檢測的音頻錄音
   • 參數：filename，format（'base64'或'buffer'）

4. getDailyActivity

   • 獲取特定日期的鳥類活動模式
   • 參數：date，species（可選）

5. 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