MCP Server Demo: OAuth, TypeScript & Firestore Patterns

MCP サーバーのデモ：OAuth、TypeScript、Firestore のパターン

このリポジトリでは、Model Context Protocol（MCP）サーバーのシンプルな解説用実装を提供します。付属の記事で詳しく説明しているアーキテクチャパターン、セキュリティ上の考慮事項（OAuth 2.0）、開発手法（TypeScript、Firestore、Zod）を紹介します。

➡️ 詳細はこちら：「OAuth、TypeScript、そして実戦で得た教訓を活用した、本番環境対応の MCP サーバーの構築」

このデモでは MCP リソースサーバーのコンポーネントに焦点を当てており、別途 OAuth 2.0 認可サーバーがあることを前提としています。

更新：MCP SDK バージョン 1.12.0 では Authorization Server Metadata（/.well-known/oauth-authorization-server）のサポートが導入され、MCP リソースサーバー経由で OAuth 呼び出しをプロキシする必要がなくなりました。

目的

このリポジトリは、次の内容を学ぶためのリソースとして作られています。

• TypeScript MCP SDK を使った MCP サーバーの実践的な実装を紹介します。
• ツール呼び出しを保護するために OAuth 2.0 を統合する方法を説明します。
• ワークスペースコンテキストとマルチテナンシーを管理するパターンを紹介します。
• スキーマ定義と検証に Zod を使用する例を提供します。
• ツールの構成、共通ロジックに高階コンポーネント（HOC）を使用する方法、Firestore とのやり取りについて説明します。

これは、あらゆるユースケースに対応する本番環境対応の、すぐに使えるサーバーではありません。 個別のビジネスロジックは含まず、OAuth 認可サーバーがすでに存在することを前提としています。

紹介する主な機能とパターン

• MCP TypeScript SDK の統合： サーバーの基本設定とツールの登録。
• OAuth 2.0 トークンの検証： ベアラートークンを安全に処理します（SDK ミドルウェア経由）。
• ワークスペースコンテキストの管理：
  • ツール引数に明示的な workspace_id を指定します。
  • 認証とワークスペース認可に withWorkspaceAccess 高階コンポーネント（HOC）を使用します。
• Firestore の統合：
  • ユーザーデータ、OAuth トークン情報（概念上のもの）、およびツール固有のデータを取得します。
  • ローカルでの開発とテストに Firestore エミュレーターを使用します。
• Zod によるスキーマと検証： ツールの入力スキーマを定義し、実行時の検証に Zod を活用します。
• 型安全な開発： TypeScript を活用して堅牢なコードを作成します。
• ユーティリティ関数： データ取得の重複を避ける fetchResourceList の例。
• 標準化されたエラー処理： 明確なエラー伝播のために throw new Error() を使用します。
• ツール構成の例： パターンを紹介する基本的なツール定義。
• 環境変数の設定： データベースと OAuth の設定。

アーキテクチャの概要

このデモは MCP リソースサーバーを表します。別の OAuth 認可サーバーが発行した OAuth 2.0 ベアラートークンを想定しています。

[Client / LLM with MCP Client SDK]
       |
       | (HTTPS Request with Bearer Token)
       v
[This MCP Resource Server (Node.js / TypeScript)]
       |  1. MCP SDK Middleware (parses request, extracts token)
       |  2. `withWorkspaceAccess` HOC
       |     a. Using the userId associated with the token
       |     b. Validates the user can access the workspace_id in the request
       |  3. Tool Handler Execution (interacts with Firestore based on validated context)
       |
       v
[Google Firestore (Database)]

OAuth 認可サーバー（自身で用意するか、既存のものを使用します）は、次の役割を担います。

• ユーザーを認証します。
• OAuth トークン（アクセストークン、リフレッシュトークン）を発行します。
• OAuth クライアントを管理します（動的検出）。

このリソースサーバーは、クライアントから受け取ったトークンを検証します。

前提条件

• Node.js（v18.x 以降を推奨）
• npm または yarn
• Firestore が有効になっている Google Cloud プロジェクトへのアクセス、または Firestore Emulator 用に設定された Google Cloud SDK。
• 既存の OAuth 2.0 認可サーバー。

はじめに

1. リポジトリをクローンします：

   git clone https://github.com/portal-labs-infrastructure/mcp-server-blog
   cd mcp-server-blog
   

2. 依存関係をインストールします：

   npm install
   # or
   yarn install
   

3. 環境変数を設定します： .env.example ファイルを .env という名前の新しいファイルにコピーします：

   cp .env.example .env
   

   次に、.env を編集し、必要な設定値を入力します：

   # Firestore Configuration
   # If using Firestore Emulator, these might not all be strictly needed,
   # but ensure your gcloud CLI is configured or provide necessary emulator host.
   PROJECT_ID="your-gcp-project-id"
   # FIRESTORE_EMULATOR_HOST="localhost:8081" # Uncomment if using emulator and not relying on gcloud config
   
   # OAuth 2.0 Configuration (for this Resource Server to validate tokens)
   # This depends on your OAuth Authorization Server's setup.
   OAUTH_ISSUER_URL="https_your_auth_server_com"
   
   # MCP Server Configuration
   BASE_URL="http://localhost:8080" # URL this server is accessible at
   

   重要： OAuth の設定は非常に重要です。このサーバーは、認可サーバーが発行したトークンを検証する方法を把握している必要があります。認可サーバーのドキュメントを参照してください。

4. （任意）Firestore データをシードします： シードスクリプトがある場合や、Firestore インスタンス／エミュレーターにサンプルユーザー、OAuth トークン（認可サーバーが発行するものと一致するもの）、ワークスペースデータを手動で追加する場合は、ここで行ってください。これにより、ツールをより有意義にテストできます。

サーバーの実行

• 開発モード（自動再起動のため Nodemon を使用）：

  npm run dev
  

• 本番モード： bash npm run build npm start サーバーは通常 http://localhost:8080（または .env で指定されたポート）で起動します。

Firestore エミュレーターを使用した実行

1. Google Cloud SDK がインストールされ、設定されていることを確認します。
2. 別のターミナルで Firestore エミュレーターを起動します：

   gcloud emulators firestore start --host-port=localhost:8081
   

   （必要に応じてポートを調整し、.env の FIRESTORE_EMULATOR_HOST を更新するか、アプリケーションが gcloud の環境変数から自動的に検出できることを確認してください。）
3. 上記の手順に従って MCP サーバーを実行します。エミュレーターに接続されるはずです。

コードで確認できる主なパターンと概念

src ディレクトリで、以下のパターンを確認してください：

• src/index.ts: MCP サーバーのメインセットアップ。
• src/controllers/mcpController.ts: ツールの登録と、受信リクエストを処理する MCP コントローラー。
• src/services/: Firestore とのやり取りを処理するサービスレイヤー。
• src/tools/: ツール定義の例。
  • 各ツールには inputSchema（Zod）と handler があります。
  • ハンドラーは withWorkspaceAccess でラップされている場合があります。
• src/utils/withWorkspaceAccess.ts: ワークスペースのチェックを行う高階コンポーネント。
• src/utils/fetchResourceList.ts: 再利用可能なデータ取得ユーティリティの例。
• src/utils/types.ts: 共通の TypeScript 型と Zod スキーマ（EntityType、ResourceType など）。

ディレクトリ構成

.
├── src/
│   ├── tools/                # Tool definitions
│   │   ├── getAgentTool.ts
│   │   └── ...
│   ├── utils/                # Shared utilities, HOCs, types
│   │   ├── withWorkspaceAccess.ts
│   │   ├── types.ts
│   │   └── ...
│   ├── services/             # Interaction logic
│   │   ├── firestoreService.ts    # Firestore interaction logic
│   │   └── ...
│   ├── config/               # Configuration loading
│   └── index.ts              # Main server setup
├── .env.example              # Example environment variables
├── .env                      # Your local environment variables (ignored by git)
├── package.json
├── tsconfig.json
└── ...

このデモでできること（できないこと）

• できること： セキュアなマルチテナント MCP リソースサーバーを構築するためのサーバー側パターンを紹介します。
• できること： MCP のコンテキストで TypeScript、Zod、Firestore、OAuth の概念がどのように適用されるかを確認できます。
• できないこと： 完全な本番環境対応の OAuth 認可サーバーではありません（認可サーバーは別途用意する必要があります）。
• できないこと： そのまま利用できるライブラリや SDK ではありません（サンプルアプリケーションです）。
• できないこと： 複雑なビジネスロジックは含まれていません（ツールは説明用です）。

コントリビューション

これは主にデモ用のリポジトリです。ただし、バグを見つけた場合や、紹介しているパターンの明確さを向上させる提案がある場合は、気軽に issue を作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細は LICENSE ファイルを参照してください。

謝辞

このデモは、記事「OAuth、TypeScript、そして苦労の末に得た知見を活用した、本番環境対応の MCP サーバーの構築」で紹介されている経験やパターンに大きな影響を受けています。