蜂巢数据管理服务

hive管理器mcp服务器

用于养蜂数据的MCP服务器，由谷歌表格和谷歌云端硬盘支持。

概述

• 运行时：Node.js+TypeScript（ESM）
• 入口点： src/index.ts, src/server.ts
• 储存：
  • Google电子表格 hive_manager
  • 被单： logs, profiles, apiary_todos, relocations

谷歌设置

1. 创建一个Google Cloud项目。
2. 启用Google Sheets API和Google Drive API。
3. 创建一个服务帐户并下载其JSON密钥。
4. 共享您的Drive文件夹（例如 Hives/)使用服务帐户电子邮件。

本地开发

npm install

# create local env file
cp .env.example .env

# run locally
npm run dev

# checks
npm run type-check
npm run test
npm run test:e2e
npm run build

部署（Cloudflare Workers）

# authenticate once
npx wrangler login

# required secrets
npx wrangler secret put GOOGLE_SERVICE_ACCOUNT_JSON
npx wrangler secret put OAUTH_CLIENT_ID
npx wrangler secret put OAUTH_CLIENT_SECRET

# deploy
npm run deploy

笔记：

• npm run deploy 跑 npm run build && wrangler deploy.
• 电子表格选择通过MCP端点URL在请求范围内进行： POST /mcp/:spreadsheetId.

MCP端点URL

电子表格ID是URL路径的一部分：

POST https://<worker-host>/mcp/<GOOGLE_SPREADSHEET_ID>

每个客户端通过使用不同的URL来定位自己的电子表格。身份验证是通过OAuth 2.0（使用PKCE的授权代码流）处理的。

OAuth设置（用于Claude.ai自定义连接器）

服务器实现OAuth 2.0。发现元数据可在以下网址获得：

GET https://<worker-host>/.well-known/oauth-authorization-server

配置自定义MCP连接器时，将服务器URL设置为：

https://<worker-host>/mcp/<GOOGLE_SPREADSHEET_ID>

使用任何字符串 OAUTH_CLIENT_ID （例如。 hive-manager)以及一个强随机值 OAUTH_CLIENT_SECRET.

建议的项目说明（适用于使用此MCP的聊天客户端）

Use apiary_setup before the first write operation if the spreadsheet may be new or uninitialized.

GitHub 操作

• CI工作流：在上运行 pull_request.
• 部署工作流：在上运行 push 到 main 也可以手动运行(workflow_dispatch).

对于CI e2e：

• 所需的存储库机密： GOOGLE_SERVICE_ACCOUNT_JSON
• 所需的存储库变量/机密： E2E_SPREADSHEET_ID
• OAUTH_CLIENT_ID 和 OAUTH_CLIENT_SECRET 在工作流中被硬编码为固定的CI值（不需要秘密）。

MCP工具

hive_setup

• 说明：为蜂巢数据设置谷歌电子表格。需要 x-spreadsheet-id 并确保存在所需的纸张。
• 输入：无
• 输出： { success, spreadsheet_url }

hive_log_entry

• 说明：在中记录配置单元事件 logs 并在中创建或更新相应的配置文件行 profiles.
• 输入：
  • 必修的： hive, event_type (inspection|feeding|treatment|harvest)
  • 可选： timestamp, queen_seen, brood_status, food_status, action_taken, notes, next_check, tags, strength, todos, origin_hive, queen_race, queen_birth_year
• 输出： { success, message }

hive_get_profile

• 描述：从读取特定配置单元的当前配置文件 profiles 纸张。
• 输入： { hive }
• 输出：配置文件JSON行

hive_update_profile

• 说明：更新配置单元配置文件行中的特定字段 profiles 纸张。
• 输入： { hive, strength?, queen_status?, brood_status?, food_status?, notes?, todos?, origin_hive?, queen_race?, queen_birth_year? }
• 输出： { success, message }

hive_get_all_profiles

• 说明：列出所有配置单元配置文件 profiles 纸张。
• 输入：无
• 输出： { count, profiles }

hive_get_log_history

• 描述：从中检索事件日志历史记录 logs，具有可选的配置单元过滤和结果限制。
• 输入： { hive?, limit? }
• 输出： { count, entries }

hive_list_todos

• 描述：从 apiary_todos 纸张。
• 输入：无
• 输出： { count, todos }

hive_add_todo

• 说明：添加一个新的通用养蜂todo条目到 apiary_todos.
• 输入： { todo, priority?, status?, due_date?, notes? }
• 输出： { success, message }

hive_update_todo

• 描述：更新由以下标识的现有apiary todo中的字段 created_at.
• 输入： { created_at, todo?, priority?, status?, due_date?, notes? }
• 输出： { success, message, created_at }

hive_mark_todo_done

• 描述：将现有的养蜂todo标记为 done，由 created_at.
• 输入： { created_at, notes? }
• 输出： { success, message, created_at }

hive_log_relocation

• 描述：记录将一个或多个蜂箱重新定位到新位置的情况 relocations.
• 输入： { hives, location, timestamp?, notes? }
• 输出： { success, message }

hive_get_relocations

• 描述：从以下位置检索搬迁历史记录 relocations，可选择通过蜂巢过滤。
• 输入： { hive?, limit? }
• 输出： { count, entries }

hive_get_current_location

• 描述：根据以下内容获取配置单元的最新记录位置 relocations.
• 输入： { hive }
• 输出： { hive, current_location, since?, notes?, message? }

环境变量