ranch

Ranch.Bot MCP サーバー

ご自身のコンピューター上のローカル MCP サーバーを通じて、牛と羊の記録を読み書きできます。stdio トランスポートを使用して Ranch.Bot アカウントに接続し、一度に 1 つの農場を公開します。ホスト型接続はまだ一般公開されていません。ChatGPT からのアクセスは限定的なパイロット提供です。Ranch.Bot の Claude コネクターは審査中ですが、カスタムコネクターとして非公開で接続できます。

必要なもの：Node.js 22 以降、Ranch.Bot アカウント、農場へのアクセス権。

インストールとサインイン

これらのコマンドを実行すると、このソースパッケージのバージョン（0.2.0）がインストールされます。推奨される一般公開リリースを使用するには、セットアップの正本であるMCP のセットアップに記載されたバージョン固定コマンドを使用してください。リリース状況と昇格ルールはMAINTAINING.mdに記載されています。アップグレードする前に、古い CLI と MCP のプロセスを停止してください。アクティブなロックファイルは削除しないでください。

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

表示された URL を開いてサインインし、ブラウザーで表示されたコードと要求されたアクセス権を明示的に承認してください。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、および RFC3339 形式で明示する適用日時の包含／除外範囲 applied_from／applied_before を受け付けます。最初の 3 つと日時範囲を指定すると、期間を限定した履歴モードが有効になります。対象で絞り込む場合、スコープ付き認証情報には対応する追加の読み取りスコープが必要です。

読み取り専用タスクの例：「選択した農場の現在の在庫を要約してください。」対象となる個体群全体を読み取り、各操作のページネーション（skip／take）と返された total に従ってください。取得が不完全な場合は、最初のページを全件の回答として提示せず、取得が不完全であることを報告してください。

農場データの書き込み

通常の書き込みは、アプリの確認画面や変更履歴を経由せず、サーバーの権限に基づいて直接保存されます。何らかの変更を行う前に、操作内容、農場、解決済みの対象、正確な値、結果を提示し、明示的な承認を得てください。その後、結果を読み返してください。結果が不確かな場合は、別の書き込みを提案する前に、読み取りによって状況を照合してください。

ロールとスコープの両方が適用されます。Reader は、安全な lookup_animal_by_eid を含む読み取りができます。Editor または Owner は、作成と更新、および出生の確定ができます。動物、グループ、記録、識別子の削除には Owner アクセスが必要です。出生の確定には、write:records、write:animals、write:groups のスコープも必要です。スコープが不足している場合と、ロールが不足している場合は別の問題です。

直接の出生処理は preview_birth_event → 承認 → confirm_birth_event の順に行います。保存済みの修正および入力誤りの記録には、接続先のリリースで利用可能な場合、operation: "amend_birth"、記録のリビジョン、理由を指定した preview_workflow を使い、正確な内容の承認を得てから commit_workflow を実行します。訂正のために出生を再記録してはいけません。必要な機能がない場合は、処理を中止してサポートにお問い合わせください。出生を扱う前に、出生イベントのリファレンスをお読みください。

農場では、共有の preview_workflow → 承認 → commit_workflow フローを制御する、バージョン管理された record_birth テンプレートを設定できます。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 Skill バンドルが skills/ranchbot（SKILL.md と references/）に含まれています。これは任意のガイダンスであり、機能でもセキュリティ境界でもありません。インストールの詳細は、MCP リファレンスをご覧ください。

タスク別リファレンス

• MCP リファレンス — 接続、ツールの検出、農場コンテキスト、エラー、任意のスキルのインストール。
• 出生イベントのリファレンス — プレビュー、確定、再試行、保存済みの修正、機能の制限。
• エクスポートのリファレンス — アーカイブの作成、状態確認、キャンセル、ダウンロード。
• 複数ソースの照合 — 過去のインポート、網羅性台帳、融資関連書類に関する注意事項。

外部アシスタント向けのタスク

生産者は、ローカルのアシスタントに権限を付与して、何年分もの分娩記録のスプレッドシート、iPhone のメモ、メッセージ、家畜関連 PDF を1つの農場と照合したり、カスタムレポートを作成したり、同じ個体群と日付を対象とする、認可済みの融資機関または AgriStability のスナップショットと農場の履歴を比較したりできます。合計値は集計された証拠であり、個々の動物を示すものでも、現在のグループ所属を証明するものでもありません。これは家畜データの照合であり、財務上の助言ではありません。複数ソースの照合の手順と、ワークフローのページネーション規則に従ってください。MCP は網羅性台帳を保持しません。

パッケージガイド

• ワークフロー — 動物を検索し、通常の記録を保存して、入力、ページネーション、復旧を含む分娩のプレビューと確定を行います。
• アーキテクチャ — リクエストの経路と、各保証をどのコンポーネントが適用するかを説明します。
• トラブルシューティング — ログイン、農場の選択、ロック、アクセスに関する問題を扱います。
• 開発 — 認証情報不要のチェック、認証済み開発サーバー、パッケージ化について説明します。
• コントリビューション — 変更がこのエクスポートされたリポジトリに反映される仕組みと、フィードバックの送付先を説明します。
• セキュリティ — 脆弱性を非公開で報告する方法を説明します。

メンテナー向け手順

開発、管理者ログイン、ローカルインストール、EID の移行、認証のトラブルシューティング、認証情報ロックからの詳細な復旧方法については、MAINTAINING.md を参照してください。シェルコマンドについては、CLI のセットアップを利用してください。日常的な記録入力については、SMS とウェブのセットアップを利用してください。サポート： [email protected]。

ライセンス

MIT。LICENSEを参照してください。