Skip to main content
Glama
io.github.akihidem/japan-hands

io.github.akihidem/japan-hands

by akihidem
README.md
# 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 には公開しません)。

```bash
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)。

## 開発・検証

```bash
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_TOKEN` | Vercel KV / Upstash Redis の REST 接続。台帳(quotes/tasks)の保存先。未設定時はローカルファイルにフォールバック(`HFA_STORE_FILE` で変更可) |
| `HFA_NOTIFY_ENABLED` | `1` で新規依頼・accept のメール通知を有効化 |
| `RESEND_API_KEY` | 通知メール送信(Resend API) |
| `HFA_NOTIFY_TO` | 通知先。運営者のメールアドレス(必須・環境変数で指定) |
| `HFA_NOTIFY_FROM` | 通知元。既定は Resend の onboarding アドレス(本番では独自ドメイン推奨) |
| `HFA_USDJPY_RATE` | USD 見積もりの固定レート(円/ドル)。未設定時は 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):
   ```bash
   # 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  スモークテスト
```