Content
# MCP Server 実装例集
[](https://github.com/nogataka/mcp-server-samples)
このリポジトリには、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）の違いと使い分けを学ぶことができます。
## 📚 ドキュメント
- **[クイックスタートガイド](QUICKSTART.md)** - 素早く始めるための手順
- **[詳細な比較記事](MCP_SERVER_COMPARISON.md)** - 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. リポジトリのクローン
```bash
git clone https://github.com/nogataka/mcp-server-samples.git
cd mcp-server-samples
```
### 2. 一括セットアップ
```bash
chmod +x setup.sh
./setup.sh
```
### 3. 環境変数の設定
各プロジェクトで`.env`ファイルを作成：
```bash
# 例: mcp-stdio
cd mcp-stdio
cp .env.example .env
# .envファイルを編集してOPENAI_API_KEYを設定
```
### 4. サーバーを起動
```bash
# 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
```
詳細は[クイックスタートガイド](QUICKSTART.md)を参照してください。
## 📊 3つの実装方式
### 1. STDIO トランスポート (`mcp-stdio/`)
**標準入出力を使用したMCPサーバー**
```typescript
const transport = new StdioServerTransport();
await server.connect(transport);
```
**特徴:**
- ✅ 最もシンプルな実装
- ✅ 低レイテンシー
- ✅ プロセス間通信（IPC）
- ❌ ローカル環境専用
**適用シーン:**
- Claude Desktopアプリ
- ローカル開発ツール
- 個人プロジェクト
### 2. SSE トランスポート (`mcp-sse/`)
**Server-Sent Eventsを使用したMCPサーバー**
```typescript
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サーバー**
```typescript
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](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）
**使用例:**
```json
{
"name": "ask_openai",
"arguments": {
"prompt": "TypeScriptの特徴を教えてください",
"model": "gpt-4o-mini"
}
}
```
## 🧪 テスト方法
### STDIO Server
Claude Desktopで設定して使用します。
### SSE Server
```bash
# ヘルスチェック
curl http://localhost:3000/health
# SSE接続
curl -N http://localhost:3000/sse
```
### Streamable HTTP Server
```bash
# ツール一覧
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!"}
}
}'
```
## 🔧 開発
### ビルド
```bash
npm run build
```
### 実行
```bash
npm start
```
### 開発モード
```bash
npm run dev
```
## 📖 学習リソース
- [Model Context Protocol 公式ドキュメント](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [OpenAI API Documentation](https://platform.openai.com/docs)
- [このリポジトリ (GitHub)](https://github.com/nogataka/mcp-server-samples)
## 🤝 コントリビューション
このプロジェクトは学習目的で作成されています。改善提案やバグ報告は歓迎します。
プルリクエストを送る前に：
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](https://github.com/nogataka)
このプロジェクトは、MCPサーバーの異なる実装方式を学習・比較するために作成されました。
## 🎯 次のステップ
1. [リポジトリをクローン](https://github.com/nogataka/mcp-server-samples)
2. [クイックスタートガイド](QUICKSTART.md)で環境をセットアップ
3. [詳細な比較記事](MCP_SERVER_COMPARISON.md)で各実装を理解
4. 自分のユースケースに合った実装を選択
5. カスタムツールを追加して拡張
## ⭐ Star をお願いします！
このプロジェクトが役に立ったら、[GitHub](https://github.com/nogataka/mcp-server-samples)でスターをつけていただけると嬉しいです！
---
**質問や問題がある場合は、[Issues](https://github.com/nogataka/mcp-server-samples/issues)で報告してください。**
