# Universal MCP Server

OpenAIとClaude両対応のModel Context Protocolサーバー実装

## 特徴

- ✅ **マルチモード対応**
  - **STDIOモード**: Claude Desktop統合
  - **HTTPモード**: OpenAI、ngrok、外部アクセス対応
- ✅ OpenAI & Claude 完全対応
- ✅ ファイルの読み込み・書き込み・削除・検索機能
- ✅ MCP仕様に厳密に準拠（SDK v1.18.1）
- ✅ SSE (Server-Sent Events) サポート
- ✅ APIキー認証（オプション）
- ✅ CORS対応
- ✅ 包括的なロギング（Winston使用）
- ✅ 非同期書き込み制御（ロック機構）
- ✅ TypeScript完全型安全
- ✅ モジュール化された設計

## プロジェクト構造

```
universal-mcp-server/
├── src/
│   ├── index.ts             # メインサーバー実装（STDIOモード）
│   ├── index-multimode.ts   # マルチモード対応版
│   ├── http-server.ts       # HTTP/SSEサーバー実装
│   ├── logger.ts            # ロギングモジュール
│   └── storage.ts           # ストレージモジュール
├── build/                   # ビルド出力
├── data/                    # データストレージ
├── logs/                    # ログファイル
├── .env.example             # 環境設定例
├── NGROK.md                 # ngrok設定ガイド
├── OPENAI.md                # OpenAI統合ガイド
├── package.json
├── tsconfig.json
└── README.md
```

## インストール

```bash
npm install
npm run build
```

## クイックスタート

詳細は [QUICKSTART.md](./QUICKSTART.md) を参照してください。

### Claude Desktop（STDIOモード）

```bash
npm start
```

### OpenAI / Web統合（HTTPモード）

```bash
# 認証なし（開発用）
MCP_MODE=http npm run dev:http

# 認証あり（推奨）
export MCP_API_KEY=$(openssl rand -hex 32)
./start-http.sh
```

### ngrokで外部公開

#### 最も簡単な方法（オールインワン）
```bash
# MCPサーバー + ngrokを同時起動
./start-all.sh
```

#### 個別起動
```bash
# ターミナル1: MCPサーバー
./start-http.sh

# ターミナル2: ngrok
./start-ngrok.sh
```

#### 手動起動
```bash
ngrok http 3000
```

詳細: [NGROK.md](./NGROK.md), [OPENAI.md](./OPENAI.md)

## 使用方法

### STDIOモード（Claude Desktop用）

```bash
# 開発モード
npm run dev

# 本番実行
npm start
```

### HTTPモード（OpenAI、ngrok対応）

```bash
# 開発モード（認証なし）
MCP_MODE=http npm run dev:http

# 本番実行（認証なし）- 開発用のみ
MCP_MODE=http npm start:http

# 本番実行（認証あり）- 推奨
MCP_MODE=http MCP_HTTP_PORT=3000 MCP_API_KEY=your-secret-key npm start:http:auth
```

### 環境変数設定

```bash
# .envファイルを作成
cp .env.example .env

# .envファイルを編集
# MCP_MODE=http
# MCP_HTTP_PORT=3000
# MCP_HTTP_HOST=0.0.0.0
# MCP_API_KEY=your-secret-api-key
```

### ngrokでの外部公開

```bash
# 別のターミナルでngrokを起動
ngrok http 3000
```

詳細は [NGROK.md](./NGROK.md) を参照してください。

### OpenAIとの統合

詳細は [OPENAI.md](./OPENAI.md) を参照してください。

### デバッグ・インスペクター

```bash
npm run inspect
```

## Claude Desktopでの設定

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "universal-mcp": {
      "command": "node",
      "args": ["/path/to/universal-mcp-server/build/index.js"]
    }
  }
}
```

## HTTPモードのエンドポイント

| エンドポイント | メソッド | 説明 | 認証 |
|--------------|---------|------|------|
| `/health` | GET | ヘルスチェック | 不要 |
| `/info` | GET | サーバー情報 | 必要* |
| `/sse` | GET | SSE接続（MCP通信） | 必要* |
| `/message` | POST | メッセージ送信 | 必要* |

*APIキーが設定されている場合のみ

### 認証ヘッダー

```bash
curl -H "Authorization: Bearer your-api-key" \
     http://localhost:3000/info
```

## 停止方法

```bash
# すべてのプロセスを停止
./stop-all.sh

# ngrokのみ停止
./stop-ngrok.sh

# または個別に停止
pkill -f "node build/index"
pkill -f "ngrok"
```

## トラブルシューティング

プロセスが停止できない、ポートが専有されているなどの問題は [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) を参照してください。

よくある問題：
- ngrokが停止できない → `./stop-ngrok.sh`
- ポート3000が使用中 → `lsof -ti:3000 | xargs kill -9`
- "endpoint already online"エラー → 既存のngrokトンネルを停止

## 機能

### Resources（読み込み）
- `file:///{key}` - キーでファイルを読み込む
- `file:///list` - すべてのファイル一覧を取得

### Tools（書き込み・操作）
- `write_file` - ファイルに内容を書き込む
- `delete_file` - ファイルを削除
- `search_files` - テキスト検索

## ログ

すべての操作は詳細にログ記録されます:
- `logs/combined.log` - すべてのログ
- `logs/error.log` - エラーのみ
- stderr - リアルタイム出力

各ログエントリには以下が含まれます:
- タイムスタンプ
- セッションID
- リクエストID
- 操作タイプ
- コンテキスト情報

## ライセンス

MIT