Universal MCP Server

# 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