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 連携でデプロイする場合

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

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