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
インストール
npm install
npm run build
クイックスタート
詳細は QUICKSTART.md を参照してください。
Claude Desktop（STDIOモード）
npm start
OpenAI / Web統合（HTTPモード）
# 認証なし（開発用）
MCP_MODE=http npm run dev:http
# 認証あり（推奨）
export MCP_API_KEY=$(openssl rand -hex 32)
./start-http.sh
ngrokで外部公開
最も簡単な方法（オールインワン）
# MCPサーバー + ngrokを同時起動
./start-all.sh
個別起動
# ターミナル1: MCPサーバー
./start-http.sh
# ターミナル2: ngrok
./start-ngrok.sh
手動起動
ngrok http 3000
使用方法
STDIOモード（Claude Desktop用）
# 開発モード
npm run dev
# 本番実行
npm start
HTTPモード（OpenAI、ngrok対応）
# 開発モード（認証なし）
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
環境変数設定
# .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での外部公開
# 別のターミナルでngrokを起動
ngrok http 3000
詳細は NGROK.md を参照してください。
OpenAIとの統合
詳細は OPENAI.md を参照してください。
デバッグ・インスペクター
npm run inspect
Claude Desktopでの設定
~/Library/Application Support/Claude/claude_desktop_config.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キーが設定されている場合のみ
認証ヘッダー
curl -H "Authorization: Bearer your-api-key" \
http://localhost:3000/info
停止方法
# すべてのプロセスを停止
./stop-all.sh
# ngrokのみ停止
./stop-ngrok.sh
# または個別に停止
pkill -f "node build/index"
pkill -f "ngrok"
トラブルシューティング
プロセスが停止できない、ポートが専有されているなどの問題は 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