Amana03/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

インストール

npm install
npm run build

クイックスタート

詳細は を参照してください。

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

詳細は を参照してください。

OpenAIとの統合

詳細は を参照してください。

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

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モードのエンドポイント

*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"

トラブルシューティング

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

よくある問題：

• 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