💡 Model Context Protocol (MCP) Server for Hive Monitoring & AI Agent Integration

[don-petry]

Context & Objective

We will provide a native Model Context Protocol (MCP) Server (broodminder-mcp) for broodminder-data.

This will allow AI assistants and autonomous coding/agent environments—including Claude Desktop, Antigravity CLI, Cursor, Windsurf, and Claude Code—to securely and intelligently query beehive telemetry, inspect apiary health, detect colony anomalies, and examine beekeeper notes using structured tools and resources.

Target Agent Capabilities

Beekeepers and researchers can ask conversational AI questions such as:

• "How did hive weights in the North Apiary change over the last 7 days? Is there a nectar flow or dearth?"
• "Check brood temperatures across all hives in Apiary Add BroodMinder data-export tooling onto template scaffold #2 to identify any possible queenless colonies or brood rearing dips."
• "Summarize my recent inspection notes from last weekend alongside temperature telemetry for Hive 4."
• "Are any sensors showing critically low battery levels or missed syncs?"

Proposed Tools & Resources

1. MCP Tools

Tool	Parameters	Description
get_apiary_summary	apiary_id, format	High-level overview of apiaries, hive counts, and active devices minimizing LLM context tokens (~150 tokens).
get_hive_status	hive_id, format	Latest sensor readings (internal temperature, ambient temperature, relative humidity, current weight, swarm score).
get_telemetry_trends	hive_id, metric, days, resample_interval, format	Aggregated time-series trend analysis (min, max, mean, delta) over specified lookback window.
get_hive_notes	hive_id, limit, format	Recent beekeeper inspection notes, weather observations, and intervention records.
get_device_health	apiary_id, min_battery	Battery percentages, charge statuses, and telemetry freshness across deployed devices.
export_hive_data	hive_id, start_date, end_date, format, destination_dir	Triggers structured data export to local disk in JSON, NDJSON, or CSV.

2. MCP Resources

• broodminder://apiaries/list (JSON inventory of all registered apiaries and hives)
• broodminder://hives/{hive_id}/status (Real-time snapshot of hive metrics)
• broodminder://devices/health (Device battery and sync status overview)

3. MCP Prompts

• inspection_prep: Prepares a pre-inspection briefing for an apiary highlighting hives with unusual weight loss, abnormal brood temperatures, or past notes.
• overwintering_audit: Analyzes cluster temperature maintenance and food consumption rate heading into or during winter.
• nectar_flow_tracker: Identifies daily weight gains and hive scale inflection points to guide supering decisions.

Installation & Configuration

# Install with optional MCP dependencies
pip install "broodminder-data[mcp]"

# Or run instantly via uvx
uvx --from "broodminder-data[mcp]" broodminder-mcp

Agent configuration in claude_desktop_config.json or mcp.json:

{
  "mcpServers": {
    "broodminder": {
      "command": "broodminder-mcp",
      "env": {
        "BROODMINDER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Sandbox Mode

Provide an offline mock/sandbox mode (broodminder-mcp --sandbox) using synthetic or anonymized telemetry fixtures so developers and agents can test without live API credentials.

Acceptance Criteria

• FastMCP implementation in bm/mcp_server.py with CLI entrypoint broodminder-mcp.
• Comprehensive test suite covering all tools and resources with mocked and sandbox data.
• Token-efficient output formatting (Markdown, compact JSON, table).
• Complete documentation in repository README.