ranch

Ranch.Bot MCP 服务

通过本地 MCP 服务，在你自己的计算机上读取和写入牛羊记录。它通过 stdio 传输使用你的 Ranch.Bot 账户，每次只公开一个农场。托管连接目前尚未开放。ChatGPT 接入仍处于私人试点阶段。Ranch.Bot 的 Claude 连接器正在审核中；你仍可将其作为自定义连接器私下连接。

要求：Node.js 22 或更高版本、Ranch.Bot 账户，以及农场访问权限。

安装并登录

这些命令会安装此源代码包的 0.2.0 版本。若要使用推荐的公开版本，请使用 MCP setup 上固定的命令；该页面是设置的权威来源。发布状态和推广规则见 MAINTAINING.md。升级前请停止旧版 CLI 和 MCP 进程；切勿删除其活动锁定文件。

npm install -g @ranchbot/[email protected]
ranchbot-mcp --version
ranchbot-mcp login

打开显示的网址，登录，并在浏览器中明确批准显示的代码和请求的访问权限。无需 API 密钥。如果登录过期，请再次运行 ranchbot-mcp login；使用 ranchbot-mcp logout 退出登录。有关访问被拒和会话问题，请参阅故障排除，并切勿在助手消息中透露密码和令牌文件。

配置本地 stdio 客户端

将 MCP 客户端指向已安装的命令，不带任何参数：

{
  "mcpServers": {
    "ranchbot": { "command": "ranchbot-mcp", "args": [] }
  }
}

如果客户端找不到该命令，请使用其可执行文件的绝对路径。更改配置后，请重启客户端。ranchbot-mcp --help 和 ranchbot-mcp --version 无需身份验证即可运行。任何能够运行本地 stdio 服务的 MCP 客户端都可使用；这不代表对任何特定客户端的认证。

首次成功读取

请客户端按顺序调用以下工具：

1. 使用 {} 调用 list_my_farms。选择目标农场 ID。如果可能的农场不止一个，且生产者未指定农场，请先询问，不要猜测。
2. 使用 {"farm_id":"<farm_id>"} 调用 list_animals，将占位符替换为该 ID。

空列表也表示读取成功。每次限定范围的调用都要明确传入 farm_id；使用 set_default_farm 设置默认农场为可选操作。如果访问被拒，请检查账户和农场成员身份；若缺少身份验证，请先在终端登录，然后重试。工具调用不会启动浏览器审批。更换账户会清除进程的默认农场。

list_animals 接受 query、match_mode（默认为 exact，也可以是 partial）和 identifier_type；精确匹配会查找已保存的标识符和当前资料名称，部分匹配则会在资料名称及 NAME／MANAGEMENT_TAG 标识符中按字面子串搜索。list_records 接受 animal_id、group_id、include_group_context，以及明确指定是否包含边界的 applied_from／applied_before RFC3339 时间范围；前三项和时间范围会启用有界历史模式。限定范围的凭据需要具备与目标过滤条件相匹配的额外读取权限范围。

一个实用的只读任务示例：“汇总所选农场的当前存栏情况。”读取完整的相关群体，遵循每项操作的分页参数（skip／take）和返回的 total；如果未能完整检索，请报告检索不完整，不要把第一页内容当作完整结果。

编写农场数据

普通写入会直接在你的服务器权限下保存，不会显示应用确认屏幕，也不会进入其变更历史记录。执行任何修改前，都应说明操作、农场、解析后的目标、确切值和后果，并获得明确批准。之后读取结果进行核实。如果结果不确定，应先通过读取进行核对，再提出另一项写入操作。

角色和权限范围均适用：Reader 可以读取数据，包括安全的 lookup_animal_by_eid；Editor 或 Owner 可以创建和更新数据并确认出生记录；删除动物、群组、记录或标识符需要 Owner 权限。确认出生记录还需要 write:records、write:animals 和 write:groups 权限范围。缺少权限范围和缺少角色权限是两个不同的问题。

直接录入出生记录的流程是 preview_birth_event → 批准 → confirm_birth_event。对于已保存记录的修订和标记为误录的记录，应在连接版本支持的情况下，使用 preview_workflow 并设置 operation: "amend_birth"、记录修订版本和原因，然后获得确切批准并调用 commit_workflow。绝不要通过重新录入出生记录来更正记录；如果缺少相应功能，请停止操作并联系 support。处理出生记录前，请先阅读 出生事件参考。

农场可以配置带版本的 record_birth 模板，以驱动通用的 preview_workflow → 批准 → commit_workflow 流程。list_workflow_templates、 get_workflow_template、create_workflow_template、publish_workflow_template_version、 update_workflow_template_state 和 set_default_workflow_template 工具用于管理该 配置（使用 write:farms 权限的 Owner 写入）。从缺少 write:farms 权限的登录状态升级后，请运行 ranchbot-mcp login 并批准新的授权。刷新会保留现有授权，无法添加权限范围。新授权不会提升你的农场角色。 提交操作需要从最新预览中读取的确切 preview_hash；过期的哈希会被拒绝。模板只会更改 标签、可见性、默认值和自定义观察项，不会改变核心出生字段的含义及其审核控制。运行和配置步骤请参阅 工作流指南。

Agent 技能

此软件包附带公开的 Agent Skill 包，位于 skills/ranchbot（包含 SKILL.md 和 references/）。它是可选指南，不是功能或安全边界；安装详情请参阅 MCP 参考。

任务参考

• MCP 参考 — 连接、工具发现、农场上下文、 错误和可选技能安装。
• 出生事件参考 — 预览、确认、 重试、已保存记录的修订和功能限制。
• 导出参考 — 创建、轮询、取消和下载归档。
• 混合来源核对 — 历史 导入、覆盖范围台账和贷款方文件注意事项。

外部助手的任务

生产者可以授权本地助手，将多年的产羔电子表格、iPhone 备忘录、消息和畜牧业 PDF 与单个农场的数据进行核对，生成自定义报告，或将农场历史与针对相同群体和日期获授权的贷款方或 AgriStability 快照进行比较。汇总数据属于汇总证据，不能代表单只动物，也不能证明动物当前属于某个群组；这是畜牧业数据核对，不是财务建议。请遵循 混合来源核对流程和 工作流中的分页规则；MCP 不会持久化覆盖范围台账。

软件包指南

• 工作流 — 查找动物、保存普通记录，以及预览并确认出生记录，涵盖输入、分页和恢复。
• 架构 — 请求路径以及各组件负责实施哪些保证。
• 故障排查 — 登录、牧场选择、锁定和访问问题。
• 开发 — 无需凭据的检查、经过身份验证的开发服务器以及打包。
• 贡献 — 变更如何进入此导出仓库，以及如何提交反馈。
• 安全 — 如何私下报告漏洞。

维护者说明

请参阅 MAINTAINING.md，了解开发、管理员登录、本地安装、EID 迁移、身份验证故障排查以及详细的凭据锁定恢复说明。有关 shell 命令，请参阅 CLI setup。有关日常记录录入，请参阅 SMS and web setup。支持邮箱： [email protected]。

许可证

MIT。请参阅 LICENSE。