QUICKSTART.md•4.78 kB
# クイックスタートガイド
## 🚀 5分で始めるUniversal MCP Server
### 前提条件
- Node.js 20以上
- npm
### 1. インストール
```bash
cd universal-mcp-server
npm install
npm run build
```
### 2. モード選択
#### A. Claude Desktop用（STDIOモード） - 最も簡単
```bash
npm start
```
Claude Desktopの設定ファイルに追加:
```json
{
"mcpServers": {
"universal-mcp": {
"command": "node",
"args": ["/絶対パス/universal-mcp-server/build/index.js"]
}
}
}
```
#### B. OpenAI / Web統合用（HTTPモード）
##### 認証なし（開発用のみ）
```bash
MCP_MODE=http npm run dev:http
```
##### 認証あり（推奨）
```bash
# APIキーを生成
export MCP_API_KEY=$(openssl rand -hex 32)
echo "Your API Key: $MCP_API_KEY"
# サーバー起動
./start-http.sh
```
または
```bash
MCP_MODE=http MCP_HTTP_PORT=3000 MCP_API_KEY=your-key node build/index-multimode.js
```
### 3. テスト
#### STDIOモードのテスト
```bash
./test.sh
```
#### HTTPモードのテスト
```bash
# 別のターミナルでサーバーが起動している状態で
./test-http.sh
# または
curl http://localhost:3000/health
```
### 4. ngrokで外部公開（オプション）
#### 方法1: 自動起動（最も簡単）
```bash
# MCPサーバー + ngrokを一度に起動
./start-all.sh
```
このスクリプトは以下を自動で行います：
- APIキーの生成（未設定の場合）
- MCPサーバーの起動
- ngrokの起動
- URL情報の表示
- URLをクリップボードにコピー（可能な場合）
#### 方法2: 個別起動
```bash
# ターミナル1: MCPサーバー起動
./start-http.sh
# ターミナル2: ngrok起動
./start-ngrok.sh
```
#### 方法3: 手動起動
```bash
# ターミナル1: MCPサーバー起動
MCP_MODE=http MCP_HTTP_PORT=3000 npm start:http
# ターミナル2: ngrok起動
ngrok http 3000
```
ngrokが起動すると以下のような情報が表示されます:
```
🌐 公開URL (HTTPS):
https://xxxx-xx-xx-xx-xx.ngrok-free.app
📡 利用可能なエンドポイント:
Health: https://xxxx.ngrok-free.app/health
Info: https://xxxx.ngrok-free.app/info
SSE: https://xxxx.ngrok-free.app/sse
```
### 5. OpenAIから使用
詳細は [OPENAI.md](./OPENAI.md) を参照
```python
import requests
# ngrokのURL
url = "https://your-ngrok-url.ngrok-free.app"
# ヘルスチェック
response = requests.get(f"{url}/health")
print(response.json())
# サーバー情報（認証が必要な場合）
headers = {"Authorization": "Bearer your-api-key"}
response = requests.get(f"{url}/info", headers=headers)
print(response.json())
```
## 🎯 使用例
### ファイルの作成
```bash
# Claude Desktopで
"Create a file called 'test.txt' with content 'Hello World'"
# HTTPモード + curlで
curl -X POST http://localhost:3000/message \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "write_file",
"arguments": {
"key": "test",
"content": "Hello World"
}
},
"id": 1
}'
```
### ファイルの検索
```bash
# Claude Desktopで
"Search for files containing 'Hello'"
```
## 🔒 セキュリティ
### 開発環境
- 認証なしでOK
- localhostのみアクセス
### 本番環境・外部公開
1. **必ずAPIキーを設定**
```bash
export MCP_API_KEY=$(openssl rand -hex 32)
```
2. **HTTPSを使用**（ngrokは自動的にHTTPS）
3. **ファイアウォール設定**
```bash
# 特定IPのみ許可
sudo ufw allow from YOUR_IP to any port 3000
```
4. **レート制限の実装**（本番環境）
## 📊 モニタリング
ログは以下に保存されます:
```
logs/
├── combined.log # すべてのログ
└── error.log # エラーのみ
```
リアルタイム監視:
```bash
tail -f logs/combined.log
```
## 🆘 トラブルシューティング
### ポートが既に使用中
```bash
# 別のポートを使用
MCP_HTTP_PORT=3001 ./start-http.sh
```
### ビルドエラー
```bash
rm -rf build node_modules
npm install
npm run build
```
### 接続エラー
1. ファイアウォール設定を確認
2. ポートが開いているか確認: `netstat -an | grep 3000`
3. ログを確認: `tail logs/error.log`
## 📚 詳細ドキュメント
- [README.md](./README.md) - 全体概要
- [NGROK.md](./NGROK.md) - ngrok設定詳細
- [OPENAI.md](./OPENAI.md) - OpenAI統合
- [CHANGELOG.md](./CHANGELOG.md) - 変更履歴
## 💡 次のステップ
1. カスタムツールの追加
2. データベース統合
3. 認証システムの強化
4. レート制限の実装
5. メトリクスとモニタリング
Happy coding! 🎉