mcp-oracle-claude desktop

ローカルな MCP（Model Context Protocol）サーバーで、顧客データをクエリ可能なツールとして公開します。これにより、Claude はこのサーバーを直接呼び出して、顧客に関する自然言語の質問に答えることができます。

現在、データはローカルでモックされています（data/customers.json に、注文履歴付きのモック顧客レコードが28件）。将来は、このモックデータ層を Oracle AI Agent Studio への実際の接続に置き換えても、MCP ツールのコードには一切触れる必要がありません。詳細は下記の Oracle AI Agent Studio への置き換え を参照してください。

このプロジェクトの機能

stdio ベースのMCPサーバーで、5つのツールを提供します。

Claude Desktop にカスタムコネクタとして登録すると、Claude はこれらのツールを自ら呼び出して、「どの顧客が離脱しましたか？」や「John Smith は何を注文しましたか？」といった質問に答えることができます。

プロジェクト構造

/mcp-oracle-demo
  /data
    customers.json          # mock customer + order data
  /src
    data_source.ts          # ONLY file that touches raw data — the Oracle swap point
    server.ts                # MCP server entry point, registers all tools
    tools/
      search_customers.ts
      get_customer_details.ts
      get_customer_orders.ts
      list_customers_by_status.ts
      get_customer_stats.ts
  /test
    test_data_source.ts     # manual test walkthrough (npm test)
  package.json
  tsconfig.json
  README.md

ローカルでのインストールと実行

Node.js 18 以上が必要です。

cd mcp-oracle-demo
npm install
npm run build      # compiles src/ -> dist/
npm start           # runs the compiled server over stdio

ビルドステップなしでローカル開発する場合:

npm run dev          # runs src/server.ts directly via tsx

Claude Desktop に接続する前にすべてが動作することを確認するには、テストウォークスルーを実行してください。データアクセス層とすべてのツールハンドラーを実行し、各チェックの PASS/FAIL を出力します。

npm test

stdio の MCP サーバーは、それ自体では stdout に何も出力しません（stdout はプロトコルストリーム用に予約されています）。起動すると、stderr に customer-data-mcp server running on stdio という行が表示され、その後クラブ（Claude Desktop など）からの接続を待ちます。

Claude Desktop への登録

claude_desktop_config.json にエントリを追加します（Claude Desktop メニュー → Settings → Developer → Edit Config）。ここではコンパイル済みサーバーを指定します。

{
  "mcpServers": {
    "customer-data": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-oracle-demo/dist/server.js"]
    }
  }
}

絶対パスを使用してください。Claude Desktop は、このプロジェクトのフォルダではなく自身の作業ディレクトリからプロセスを起動します。設定を保存したら Claude Desktop を再起動すると、接続済みツールソースとして「customer-data」が表示されるはずです（新しいチャットで 🔌 / ツールアイコンを探してください）。

接続後に試す質問例

• 「アクティブな顧客をすべて表示して。」

• 「[顧客名] は何を注文しましたか？」

• 「どの顧客が離脱しましたか？」

• 「顧客 CUST-0012 は当社までいくら使いましたか？また平均注文額はいくらですか？」

• 「Acme Co. の顧客を探してください。」

Oracle AI Agent Studio への置き換え

src/data_source.ts は、生の顧客データに触れる唯一のファイルです。すべての MCP ツールは、JSON ファイルを直接読むのではなく、このファイルがエクスポートする関数（getCustomerById、searchCustomers、getCustomerOrders、getCustomersByStatus、getCustomerStats）を呼び出します。つまり、後で実際のバックエンドに接続するには、このファイルだけを編集すればよく、ツール定義やサーバーコードを変更する必要ありません。

data_source.ts 内で変更が必要になる点は次のとおりです:

1. 認証処理 — Oracle AI Agent Studio の API 向けにトークンフロー（例: OAuth クライアント認証情報や API キー）を追加します。認証情報はハードコードせず、環境変数から読み取るようにし、毎回の呼び出しで再認証しないように短期間のトークンキャッシュも追加します。

2. ローカルJSON読み込みの置き換え — loadCustomers() を、Oracle のエンドポイントへの認証付き REST 呼び出し（例: GET /customers/{id}、GET /customers/search?q=...、GET /customers?status=...）に置き換えます。そして、Oracle のレスポンス形式を、同じファイルで定義済みの Customer / Order TypeScript インターフェースにマッピングします（Oracle のスキーマが異なる場合はインターフェースを調整します）。

3. エラーハンドリング — 実 API は、ローカルファイル読み込みでは起き得ないタイムアウトやレート制限、エラーが発生する可能性があります。そのため、ツールが Claude に返せるように try/catch と明確なエラーメッセージを追加してください。

4. キャッシュ — 現在のインメモリキャッシュは静的データを前提としています。実際のライブなバックには、キャッシュを削除するか、短い TTL を設定する必要があります。

これらの各項目の詳細は、src/data_source.ts の末尾にもコメントとして直接記載されています。

テスト

npm test は test/test_data_source.ts を実行します。このスクリプトは:

• data_source.ts のすべての関数を直接呼び出し、結果をモックデータの既知の特性と照合します（例: 既知の顧客 ID は解決される、未知の ID は null を返す、検索は大文字小文字を区別しないなど）。

• すべてのツールのハンドラー関数を直接呼び出し（MCP transports を経由せず）、返された JSON が整形式で、基になるデータと一致することを確認します。

これはプレーンなスクリプト（テストフレームワークはありません）なので、画面共有デモで1行ごとに読み取って説明するのが簡単です。