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 アカウント（無料枠でOK）
Oxford の App ID / App Key（取得先）

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

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

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

B. GitHub 連携でデプロイする場合

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

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 を使ってリモート接続を追加します（認証ヘッダーを渡せます）。

{
  "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. ローカルで動かす / テストする

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 始まりに揃えてあるので、有料化後は自由に広げられます。