Ynosis では、ブラウザからの登録に加えて、AIエージェントから施設や成分表を本番データへ登録できます。この経路を Agent API と呼びます。

ここでいう AIエージェントは、特定の製品に限りません。例えば次のようなツールから使えます。

• Claude（Claude Code や、ターミナルから動かす Claude 系の CLI）
• Codex（OpenAI のコーディングエージェント）
• Gemini CLI（Google のターミナル向けエージェント）
• Cursor など、チャットやエージェント機能つきのエディタ

公開されているのは Ynosis の HTTPS API です。手元の道具は次です。ソースリポジトリは非公開のため、git clone は不要です。運営がホストするリモート MCP サーバもありません。

• PyPI の ynosis-agent … ターミナルの CLI（pip install）
• MCP（アプリに設定を貼る）
  • Node がある場合（Cursor で多い）: npm の ynosis-agent-mcp を npx で起動
  • Python / uv がある場合: 同じ PyPI パッケージを uvx で起動（uv は 別途インストールが必要です）

何ができるか

• 施設の新規登録 … 名前・都道府県などを送り、マスタに下書きとして追加できる
• 成分表の登録 … 次のいずれかで解析した結果を、施設とあわせて登録できる
  • **手元の画像認識（Vision）**で分析書を文字にしてから、Ynosis が公式の形に整える（OCR の月間枠は使いません）
  • Ynosis の OCR（ブラウザの成分表読み取りと同じ仕組み）で画像を解析した結果
• 重複確認のための検索 … 登録前に、既存施設（管理者未承認の Agent 登録分を含む）を検索できる

既存の施設に当たった場合の変更は、画面からの 編集依頼 と同じく、管理者が差分を確認してから反映されます。公開データをその場で上書きはしません。

誰が使えるか

1. Ynosis に ログインする
2. マイページ 右上の 「…」 を開く
3. Agent API を選び、用途を書いて申請する
4. 管理者が許可すると、同じダイアログから API キーを発行できる（yna_ で始まる。キーは発行時に一度だけ表示されます）

キーは共有せず、漏洩したときは再発行してください。Chrome 拡張用の API キーとは別物です（拡張は Google Maps保存リストから一括登録）。

つなぎ方の選び方

どの AIエージェントを使う場合も、やることは共通です。キーを渡し、本番 API（または ynosis-agent CLI）を呼ばせることです。

セットアップ

クライアントの CLI は PyPI（ynosis-agent） から入手します。

CLI を使う場合は Python 3.11 以降で次を実行します。

pip install ynosis-agent
export YNOSIS_AGENT_API_KEY='yna_...'
# 接続先の既定は https://ynosis.jp です

MCP だけ使う場合は、リポジトリの clone も CLI の常設インストールも不要です。次のどちらかです。

• Node.js 18 以降がある（Cursor 利用者に多い）… 後述の npx 設定を貼る
• **uv（uvx）**がある … 後述の uvx 設定を貼る。uv は Python とは別に入れる必要があります。入っていないと MCP は起動しません

キーは Git に置かないでください。

CLI の例（おすすめ）

エージェントに「このコマンドを実行して」と頼むだけで足ります。ツールの種類は問いません。

# 重複確認
ynosis-agent search --q 草津 --limit 5

# 施設 1 件（JSON ファイル）
ynosis-agent facility facility.json

# 成分表（JSON + 画像。サーバーが圧縮保存し、管理者の承認時の根拠になる）
ynosis-agent register payload.json --image photo.jpg

# 手元の画像認識で分析書を文字にしたあと、公式の形に整える（OCR の月間枠は使いません）
ynosis-agent parse-prompt transcript.txt --out prompt.json
# prompt.json の system / user を手元の LLM に渡し、返ってきた JSON を llm_result.json に保存する
ynosis-agent parse transcript.txt --llm-json llm_result.json --for-register --out parsed.json

# Ynosis OCR で画像を解析してから登録（施設名は自分で指定）
ynosis-agent analyze photo.jpg --out analyzed.json
ynosis-agent register-from-image photo.jpg --name 〇〇温泉 --prefecture 大分県

# 複数枚の OCR は 1 枚ずつ（並列にしない）。間隔の既定は 6 秒
ynosis-agent analyze-batch ./photos --out-dir ./out

よく使う AIエージェント別のヒント

製品ごとの画面や設定名は変わることがあります。ここでは「どうつなぐか」だけを押さえます。

Claude（Claude Code / CLI）

ターミナルで動く Claude 系エージェントには、上記の ynosis-agent コマンドをそのまま実行させるのが手早いです。YNOSIS_AGENT_API_KEY をシェルに渡したうえで、検索や登録コマンドを依頼してください。

Codex

Codex もシェル経由で同じ CLI を呼べます。キーはリポジトリや会話ログに書かず、環境変数やシークレット機能側に置きます。一括登録や OCR 連続実行では、並列にしないよう指示に含めてください。

Gemini CLI

Gemini CLI も同様に、ynosis-agent を実行させる使い方が向いています。接続先の既定は https://ynosis.jp なので、本番向けなら Base URL の指定は省略できます。

Cursor など MCP 対応のエディタ

MCP に対応している場合は、アプリの設定に短い起動コマンドを貼るだけで使えます（任意）。どの経路でも git clone は不要です。

Cursor では Node が入っていることが多いので、先に npx を試してください。uvx は uv が入っていないと起動しません。

起動コマンド（Node / npx）:

npx -y ynosis-agent-mcp

起動コマンド（Python / uvx）:

uvx --from ynosis-agent[mcp] ynosis-agent-mcp

あわせて環境変数 YNOSIS_AGENT_API_KEY に発行したキーを渡します。接続先の既定は https://ynosis.jp です。

Cursor の例（npx・推奨。yna_REPLACE_ME を置換）:

{
  "mcpServers": {
    "ynosis-agent": {
      "command": "npx",
      "args": ["-y", "ynosis-agent-mcp"],
      "env": {
        "YNOSIS_AGENT_API_KEY": "yna_REPLACE_ME",
        "YNOSIS_AGENT_API_BASE": "https://ynosis.jp"
      }
    }
  }
}

uv がある場合の Cursor 例:

{
  "mcpServers": {
    "ynosis-agent": {
      "command": "uvx",
      "args": ["--from", "ynosis-agent[mcp]", "ynosis-agent-mcp"],
      "env": {
        "YNOSIS_AGENT_API_KEY": "yna_REPLACE_ME",
        "YNOSIS_AGENT_API_BASE": "https://ynosis.jp"
      }
    }
  }
}

貼ったあと:

1. 設定を保存し、Cursor を再起動する
2. Customize → MCPs で ynosis-agent が有効か確認する
3. チャットのツール一覧に search_facilities などが出ていれば接続できている
4. チャットを作り直す必要はありません（ツールが出ないときだけ、再起動後のチャットを試す）

npx や uvx が「command not found」になるときは、そのコマンドがまだ入っていないか、Cursor から PATH が見えていません。入れるか、command に which npx / which uvx の絶対パスを書きます。失敗の詳細は Output の MCP Logs です。

Claude Code の例（npx）:

claude mcp add --transport stdio ynosis-agent \
  --env YNOSIS_AGENT_API_KEY=yna_REPLACE_ME \
  -- npx -y ynosis-agent-mcp

キーを設定ファイルに直書きしたくない場合は、各アプリのシークレット／環境変数機能を使ってください。MCP が使えない場合は、同じ API でも ynosis-agent をターミナル実行すれば足ります。

施設登録と座標（エージェント向け）

使うキーは2種類（別物）

Ynosis は Google キーを配布しません。Agent キーだけでも施設登録はできます。

Google キーがない場合（一般的な使い方）

1. 重複確認 … search_facilities 等（Agent キーのみ）
2. 住所を調べる … 公式サイト・観光協会・自治体ページから 都道府県＋市町村＋番地 を確認（Web 検索で可）
3. 登録 … 施設名・都道府県に加え、分かった 住所文字列 を付けて register。座標（緯度経度）は 省略してよい
4. （任意） ブラウザの Google マップで施設を開き、「共有」で得た URL（/maps/place/… 形式）を一緒に渡す
5. 管理者が承認するときに、地図上の位置を整えます

resolve_place_candidates をキーなしで呼ぶと エラー になりますが、代替の登録手順 が応答に含まれます。

Google キーがある場合（座標を自動で付けたいとき）

MCP 設定の env に GOOGLE_MAPS_API_KEY を追加（各自の Google Cloud で発行）。

1. 先に住所を調べる（上と同じ）
2. Places 検索 … resolve_place_candidates に address を渡す（フル住所 → 必要なら施設名+住所）
3. 候補を選ぶ … 番地が一致し同一施設と確信できるときだけ lat / lng / place_id を付ける。曖昧なら座標なしで登録（推測禁止）

施設名と都道府県だけの一括 Places 検索は精度が低いので使わないでください。

登録したデータはどう見えるか

• Agent からの 新規施設・成分表は、しばらく 一般の施設検索・詳細には出ません
• 管理者が内容を確認し、公開承認したあとに、みんなの検索対象になります
• 座標や Google マップ上の位置がはっきりしていない新規は、承認前に管理者が位置を整えることがあります

ブラウザからの通常登録（訪問登録・OCR・CSV）はこれまでどおり使えます。詳しくは 施設と成分表の登録 を参照してください。

Agent から Ynosis OCR を使う場合も、ブラウザ登録と同じ月間読み取り上限・サーバ側の同時実行制限がかかります。画像を連続で送るときは 1 枚ずつ（並列にしない）にしてください。手元の画像認識で文字起こしし、parse-prompt / parse で形を整える経路では、この OCR の月間枠は使いません。未承認のまま置ける件数にも上限があります（許可後のダイアログに表示）。

関連

• リリースノート（v4） … Agent API 公開の変更履歴
• 施設と成分表の登録 … ブラウザからの登録全般
• 施設と源泉の編集依頼 … 既存データの修正依頼
• プロフィールの設定と管理 … 申請ダイアログの場所
• 温泉データのご提供について … データ提供全般のお願い