MCP Server 実装例集

このリポジトリには、Model Context Protocol (MCP) サーバーの3つの異なるトランスポート方式による実装例が含まれています。

💡 このサンプルアプリについて

各実装は、OpenAI APIをMCPツールとして提供するシンプルなサーバーです。Claude DesktopなどのMCPクライアントから、OpenAIのGPTモデルに質問を投げて回答を得ることができます。

主な機能:

• ask_openaiツール: OpenAI APIに質問を送信し、回答を取得
• モデル選択: 使用するGPTモデルを指定可能（デフォルト: gpt-4o-mini）
• エラーハンドリング: API呼び出しの失敗を適切に処理

ユースケース例:

Claude: 「OpenAIのGPT-4に、Pythonのリスト内包表記について説明してもらえますか？」
→ MCPサーバーがask_openaiツールを実行
→ OpenAI APIから回答を取得
→ Claudeに結果を返す

このシンプルな実装を通じて、MCPサーバーの3つの異なるトランスポート方式（STDIO、SSE、HTTP）の違いと使い分けを学ぶことができます。

📚 ドキュメント

• クイックスタートガイド - 素早く始めるための手順
• 詳細な比較記事 - 3つの実装方式の徹底比較と解説

🗂️ プロジェクト構成

mcp-server-samples/
├── mcp-stdio/              # STDIO トランスポート実装
│   ├── src/
│   │   └── index.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-sse/                # SSE トランスポート実装
│   ├── src/
│   │   └── index.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-streamable-http/    # Streamable HTTP トランスポート実装
│   ├── src/
│   │   └── index.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── MCP_SERVER_COMPARISON.md # 詳細な比較記事
├── QUICKSTART.md           # クイックスタートガイド
├── setup.sh                # 一括セットアップスクリプト
└── README.md               # このファイル

🚀 クイックスタート

1. リポジトリのクローン

git clone https://github.com/nogataka/mcp-server-samples.git
cd mcp-server-samples

2. 一括セットアップ

chmod +x setup.sh
./setup.sh

3. 環境変数の設定

各プロジェクトで.envファイルを作成：

# 例: mcp-stdio
cd mcp-stdio
cp .env.example .env
# .envファイルを編集してOPENAI_API_KEYを設定

4. サーバーを起動

# STDIO Server
cd mcp-stdio && npm start

# SSE Server
cd mcp-sse && npm start
# → http://localhost:3000

# Streamable HTTP Server
cd mcp-streamable-http && npm start
# → http://localhost:3001

詳細はクイックスタートガイドを参照してください。

📊 3つの実装方式

1. STDIO トランスポート (mcp-stdio/)

標準入出力を使用したMCPサーバー

const transport = new StdioServerTransport();
await server.connect(transport);

特徴:

• ✅ 最もシンプルな実装
• ✅ 低レイテンシー
• ✅ プロセス間通信（IPC）
• ❌ ローカル環境専用

適用シーン:

• Claude Desktopアプリ
• ローカル開発ツール
• 個人プロジェクト

2. SSE トランスポート (mcp-sse/)

Server-Sent Eventsを使用したMCPサーバー

app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/message", res);
  await server.connect(transport);
});

特徴:

• ✅ リアルタイム通信
• ✅ HTTP上で動作
• ✅ サーバープッシュ対応
• ⚠️ 2つのHTTPチャネルが必要

適用シーン:

• Webアプリケーション
• リアルタイムダッシュボード
• 通知システム

3. Streamable HTTP トランスポート (mcp-streamable-http/)

標準的なHTTP POST/Responseを使用したMCPサーバー

app.post("/mcp", async (req, res) => {
  const response = await server.handleRequest(req.body);
  res.json(response);
});

特徴:

• ✅ 最も汎用的
• ✅ REST APIライク
• ✅ 高スケーラビリティ
• ✅ ファイアウォールフレンドリー

適用シーン:

• マイクロサービス
• エンタープライズシステム
• 公開API

📋 比較表

項目	STDIO	SSE	Streamable HTTP
実装難易度	⭐ 易	⭐⭐ 中	⭐⭐ 中
パフォーマンス	⭐⭐⭐ 最高	⭐⭐ 良	⭐⭐ 良
スケーラビリティ	⭐ 低	⭐⭐ 中	⭐⭐⭐ 高
ネットワーク対応	❌	✅	✅
リアルタイム性	⭐⭐⭐	⭐⭐⭐	⭐⭐
デバッグ容易性	⭐⭐	⭐⭐	⭐⭐⭐

詳細な比較はMCP_SERVER_COMPARISON.mdを参照してください。

🛠️ 技術スタック

• 言語: TypeScript
• ランタイム: Node.js 18+
• フレームワーク: Express (SSE/HTTP版)
• SDK: @modelcontextprotocol/sdk
• API: OpenAI API

📝 各プロジェクトの機能

全ての実装で以下のツールを提供：

ask_openai ツール

OpenAI APIを使用して質問に回答します。

パラメータ:

• prompt (string, required): OpenAIに送信する質問
• model (string, optional): 使用するモデル（デフォルト: gpt-4o-mini）

使用例:

{
  "name": "ask_openai",
  "arguments": {
    "prompt": "TypeScriptの特徴を教えてください",
    "model": "gpt-4o-mini"
  }
}

🧪 テスト方法

STDIO Server

Claude Desktopで設定して使用します。

SSE Server

# ヘルスチェック
curl http://localhost:3000/health

# SSE接続
curl -N http://localhost:3000/sse

Streamable HTTP Server

# ツール一覧
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# ツール実行
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"ask_openai",
      "arguments":{"prompt":"Hello!"}
    }
  }'

🔧 開発

ビルド

npm run build

実行

npm start

開発モード

npm run dev

📖 学習リソース

• Model Context Protocol 公式ドキュメント
• MCP TypeScript SDK
• OpenAI API Documentation
• このリポジトリ (GitHub)

🤝 コントリビューション

このプロジェクトは学習目的で作成されています。改善提案やバグ報告は歓迎します。

プルリクエストを送る前に：

1. リポジトリをフォーク
2. フィーチャーブランチを作成 (git checkout -b feature/amazing-feature)
3. 変更をコミット (git commit -m 'Add some amazing feature')
4. ブランチにプッシュ (git push origin feature/amazing-feature)
5. プルリクエストを作成

📄 ライセンス

MIT License

👤 著者

@nogataka

このプロジェクトは、MCPサーバーの異なる実装方式を学習・比較するために作成されました。

🎯 次のステップ

1. リポジトリをクローン
2. クイックスタートガイドで環境をセットアップ
3. 詳細な比較記事で各実装を理解
4. 自分のユースケースに合った実装を選択
5. カスタムツールを追加して拡張

⭐ Star をお願いします！

このプロジェクトが役に立ったら、GitHubでスターをつけていただけると嬉しいです！

---

質問や問題がある場合は、Issuesで報告してください。