Repository avatar
AI Tools
v1.5.0
active

migawari

io.github.akihidem/migawari

Migawari stands in for AI agents in Japan: shopping, checks, photos, reservations, queueing.

Documentation

Japan Hands — app

日本、東京で唯一のエージェント向けサービス The only service in Tokyo, Japan designed exclusively for AI agents.

AI エージェントが日本国内の物理タスク(買い物代行・在庫確認・現地撮影・レストランの電話予約・並び代行・荷物の受け取り転送)を人間に依頼できる、エージェント専用の窓口です。人間向け店舗サイトは作りません。仕様の正本は ../SPEC.md。

  • ランディング: public/index.html(最小限。人間が読んでも分かる体裁)
  • 機械可読カタログ: GET /api/services(別名 /catalog)、GET /llms.txt、GET /server.json
  • MCP サーバ: POST /mcp(streamable HTTP、ステートレス JSON-RPC)
  • REST: POST /api/quote / GET /api/quotes/{id} / POST /api/quotes/{id}/accept / POST /api/quotes/{id}/decline / GET /api/tasks/{id}/evidence / GET /api/health

ゼロ依存(Node 標準のみ)。Vercel プロジェクトとして完結します。

運営コンソール

タスクの確認・却下、状態遷移、証拠の添付、依頼者への返信は運営側 CLI で行います(HTTP には公開しません)。

vercel env pull .env.local   # 本番 KV の認証情報を取得(.env.local は gitignore 済み)
node scripts/ops.mjs list
node scripts/ops.mjs confirm <task_id> --note "..."
node scripts/ops.mjs decline <task_id> --reason "..."
node scripts/ops.mjs status <task_id> in_progress|completed|failed
node scripts/ops.mjs evidence <task_id> --type photo --url <url> --label "..."
node scripts/ops.mjs reply <id> --message "..."

セキュリティと支払いゲート

  • レート制限: IP 単位で見積もり 20件/時、書き込み系 60件/時、MCP 呼び出し 300件/時(環境変数で調整可)。超過は 429。
  • リクエスト上限: JSON ボディは 64KB まで。
  • アクセストークン: 見積もりごとに発行し、ハッシュ化して保存。タスクの読み書きには必須。
  • 支払いゲート: Stripe の Webhook(POST /api/stripe/webhook、署名検証必須・失敗時は閉じる)で入金を確認して初めてタスクが paid になり、運営コンソールの confirm は未払いタスクを拒否します。手作業で入金を記録する場合のみ ops.mjs paid を使います。つまり 入金確認が取れるまで仕事は始まりません。
  • 秘密情報はコードに入れません: 鍵類はすべて環境変数。公開リポジトリに秘密は含まれません。

ローンチ形の決定(2026-11-16)の反映

  • 見積もりは即時。ただし accept しても実行は確定しません。タスクは pending_review(担当者の確認待ち)になり、担当者が1件ずつ確認して可否を返します。エージェント向け文面のどこにも、即実行・即日完了の約束はありません。
  • 秋葉原の平日デイリー便・銀座プレミアムは「確認のうえ可否を返す」範囲でのみ触れています。
  • カタログに宿の予約は入れていません(電話予約はレストランのみ。旅行業法対応)。CAPTCHA 突破・本人確認の肩代わり等は not_offered として明示しています。
  • 決済(Stripe)の実連携は含みません。料金表示と見積もりロジックまでです。

料金

lib/catalog.js が唯一の正本です(見積もり手数料 ¥2,200/着手手数料はサービス別下限〜/最低着手料 ¥5,500/総額=商品代金+手数料+送料)。USD は見積もり時にレートを固定して明記します(HFA_USDJPY_RATE、未設定時は 150)。

開発・検証

npm run dev    # http://localhost:8787(Vercel と同じハンドラをマウント)
npm test       # スモークテスト(カタログ・見積もり計算・pending_review・宿拒否・MCP)

デプロイ(Vercel)

前提: Vercel コネクタの OAuth 接続(vercel status が not_connected の間はデプロイ不可)。

  1. 本人(または接続済みの窓口)が Vercel に接続する: 接続 URL は https://agent.meta.ai/connectors/connect/vercel
  2. 接続後、この app/ をプロジェクトとしてデプロイする(カスタムドメインは付けない。*.vercel.app の URL を使う)
  3. デプロイ URL が確定したら、次を差し替える:
    • server.json と public/server.json の remotes[0].url(https://<deployment>/mcp)
    • public/index.html の curl 例の YOUR-DEPLOYMENT
  4. 本番では必ず KV を設定する(下記)。未設定だと台帳は /tmp の一時ファイルになり、再デプロイで消えます。

環境変数

変数用途
KV_REST_API_URL, KV_REST_API_TOKENVercel KV / Upstash Redis の REST 接続。台帳(quotes/tasks)の保存先。未設定時はローカルファイルにフォールバック(HFA_STORE_FILE で変更可)
HFA_NOTIFY_ENABLED1 で新規依頼・accept のメール通知を有効化
RESEND_API_KEY通知メール送信(Resend API)
HFA_NOTIFY_TO通知先。運営者のメールアドレス(必須・環境変数で指定)
HFA_NOTIFY_FROM通知元。既定は Resend の onboarding アドレス(本番では独自ドメイン推奨)
HFA_USDJPY_RATEUSD 見積もりの固定レート(円/ドル)。未設定時は 150

通知(受付 → 運営者のメール)の設定方法

  1. Resend(https://resend.com)で API キーを発行する
  2. Vercel のプロジェクト環境変数に HFA_NOTIFY_ENABLED=1、RESEND_API_KEY=...、HFA_NOTIFY_TO=<運営者のメールアドレス> を設定して再デプロイ
  3. request_quote と accept_quote のたびに、依頼内容の JSON がメールで届く。通知の失敗は依頼フロー自体を止めません(レスポンスの notification フィールドで成否が分かります)
  4. 届いた依頼は台帳(KV / ローカルファイル)にも必ず残ります。担当者はメールを起点に、本人へ1件ずつ相談してから可否を返します

MCP レジストリ登録

server.json(ルートと public/ の2か所、同内容)が公式 MCP レジストリ用のマニフェストです。

  1. デプロイ URL を確定し、server.json の remotes[0].url を差し替える
  2. 名前 ai.handsforagents/hands-for-agents はドメイン(handsforagents.ai)の所有確認が前提です。ドメイン取得は本人の担当範囲なので、取得までは登録を進めません。ドメインなしで先に試す場合は GitHub 方式の名前(io.github.<owner>/hands-for-agents)に差し替えてください
  3. 登録手順(公式レジストリ https://registry.modelcontextprotocol.io):
    # mcp-publisher を取得(https://github.com/modelcontextprotocol/registry の Releases)
    ./mcp-publisher login dns --domain handsforagents.ai   # または login github
    ./mcp-publisher publish                                 # server.json のある場所で実行
    
  4. 登録後は GET https://registry.modelcontextprotocol.io/v0/servers?search=hands-for-agents で掲載を確認する

構成

api/            Vercel Functions(mcp / services / quote / quotes / tasks / health)
lib/            catalog.js(料金・カタログの正本)/ pricing.js / tools.js(MCP・REST 共通実装)
                store.js(KV ⇄ ファイルのアダプタ)/ notify.js(メール通知フック)/ http.js
public/         index.html(ランディング)/ llms.txt / server.json
server.json     MCP レジストリ用マニフェスト
dev-server.js   ローカル開発用(Vercel と同じハンドラ)
test/smoke.mjs  スモークテスト