# Mcp Server Samples

> MCP server from nogataka/mcp-server-samples.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nogataka-mcp-server-samples`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nogataka](https://agentstack.voostack.com/s/nogataka)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nogataka](https://github.com/nogataka)
- **Source:** https://github.com/nogataka/mcp-server-samples

## Install

```sh
agentstack add mcp-nogataka-mcp-server-samples
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)で報告してください。**

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nogataka](https://github.com/nogataka)
- **Source:** [nogataka/mcp-server-samples](https://github.com/nogataka/mcp-server-samples)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nogataka-mcp-server-samples
- Seller: https://agentstack.voostack.com/s/nogataka
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.