# Oxford Dictionary MCP Server (Vercel / Streamable HTTP)

Oxford Dictionaries API を利用した **リモート MCP サーバー**です。
Vercel にデプロイして、URL 経由でどの端末からでも使えます。Bearer トークン認証付き。

- 通信方式: **Streamable HTTP**（`mcp-handler`）
- MCP エンドポイント: `/api/mcp`
- ツール:
  - `get_word_definition` — 単語の定義・発音・語源・意味
  - `get_random_word` — 今日の単語（easy / medium / hard）

---

## 1. デプロイ手順（Vercel）

### 前提
- [Vercel アカウント](https://vercel.com/signup)（無料枠でOK）
- Oxford の App ID / App Key（[取得先](https://developer.oxforddictionaries.com/)）

### A. Vercel CLI でデプロイする場合

```bash
# 1) Vercel CLI を導入（初回のみ）
npm i -g vercel

# 2) このフォルダでログイン & デプロイ
cd oxford-mcp-vercel
vercel login
vercel            # プレビューデプロイ
vercel --prod     # 本番デプロイ
```

### B. GitHub 連携でデプロイする場合
1. このフォルダを GitHub リポジトリに push（`.env.local` は `.gitignore` 済みなので上がりません）
2. Vercel ダッシュボードで **New Project** → そのリポジトリを import
3. 下記の環境変数を設定してデプロイ

---

## 2. 環境変数（Vercel の Project Settings → Environment Variables）

`.env.example` を参照。設定する4つ:

| 変数名 | 説明 |
|--------|------|
| `OXFORD_APP_ID` | Oxford の App ID |
| `OXFORD_APP_KEY` | Oxford の App Key |
| `OXFORD_BASE_URL` | Sandbox: `https://od-api-sandbox.oxforddictionaries.com/api/v2` / 本番: `https://od-api.oxforddictionaries.com/api/v2` |
| `MCP_AUTH_TOKEN` | クライアントが提示する秘密トークン。長いランダム文字列にする（例: `openssl rand -hex 32`） |

> ⚠️ `MCP_AUTH_TOKEN` が未設定の場合、サーバーは**すべてのリクエストを拒否**します（fail-closed）。必ず設定してください。

デプロイ後、`https://<your-project>.vercel.app/api/mcp` が MCP エンドポイントになります。

---

## 3. Claude Desktop からの接続

Claude Desktop の設定ファイル（`%APPDATA%\Claude\claude_desktop_config.json`）に、
`mcp-remote` を使ってリモート接続を追加します（認証ヘッダーを渡せます）。

```json
{
  "mcpServers": {
    "oxford-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-project>.vercel.app/api/mcp",
        "--header",
        "Authorization: Bearer ${OXFORD_MCP_TOKEN}"
      ],
      "env": {
        "OXFORD_MCP_TOKEN": "ここに MCP_AUTH_TOKEN と同じ値"
      }
    }
  }
}
```

設定後、Claude Desktop を完全に再起動すれば「oxford-remote」として使えます。

> 補足: `claude.ai`（ブラウザ版）の Custom Connector からも、同じ URL で接続できます。

---

## 4. ローカルで動かす / テストする

```bash
npm install
cp .env.example .env.local   # 値を自分のものに書き換える
npm run dev                  # http://localhost:3000

# 別ターミナルで動作確認（認証あり/なしをテスト）
node test-client.mjs
```

---

## 制限事項（Oxford Sandbox）

無料の Sandbox は **「a」で始まる単語のみ**引けます。全単語を使うには
Oxford の有料プランに契約し、`OXFORD_BASE_URL` を本番 URL に変更してください
（コード変更は不要）。`get_random_word` の単語リスト（`lib/oxford.ts`）も
Sandbox 用に a 始まりに揃えてあるので、有料化後は自由に広げられます。