Vaali MCP Server

🚀 Vaali MCP Server

このMCPサーバーは、対話型のパラメータ収集とコンテキストワークフロー自動化を通じて、高度なAIエージェント機能を実証します。公式MCP誘導とインテリジェントなパラメータガイダンスパターンの両方を備えています。

🚀 クイックスタート

前提条件

• Node.js 18+
• VS Code (推奨)

インストールとテスト

# クローンしてセットアップ
git clone <repository-url>
cd vaali

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

# 誘導コンセプトをテスト (教育的なウォークスルー)
npm run test:advanced-concept

# 実際のMCPクライアントでテスト
npm run test:working-advanced

# すべてのテストを実行
npm run test:all

# Claude Desktop用のサーバーを起動 (stdioモード)
npm run start:stdio

# SSEトランスポートでサーバーを起動 (デバッグ用)
npm run start:sse

Claude Desktopとの統合

Claude Desktopの設定ファイルに追加します。

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vaali": {
      "command": "node",
      "args": ["C:/absolute/path/to/vaali/lib/src/index.js", "stdio"],
      "cwd": "C:/absolute/path/to/vaali"
    }
  }
}

注意: 信頼性の高い動作のために絶対パスを使用してください。実際のプロジェクトパスに置き換えてください。

次に、自然言語のコマンドを試してみましょう。

"What's the weather in Tokyo?"
"Generate a weather report for Alice"
"Calculate 25 * 4 + 10"
"Test the elicitation tool"

✨ 主な機能

• 🔄 ハイブリッド誘導：公式MCP誘導と汎用的なパラメータガイダンスの両方を備えています。
• 📊 完全なMCP準拠：リソース、ツール、プロンプト、誘導機能を備えています。
• 🎯 段階的な機能強化：クライアントの機能に基づいて最適な体験を提供します。
• 🛡️ 汎用的な互換性：任意のMCPクライアントと互換性があります。
• 🧪 研究に適した：学術および産業研究のための包括的な例が用意されています。
• 🚀 本番環境での使用に適した：堅牢なエラーハンドリングと適切なフォールバック機能を備えています。

📦 インストール

☁️ Azureデプロイメント

MCPサーバーをAzure App Serviceにデプロイして、クラウドアクセスとスケーラビリティを実現できます。

🚀 GitHub Actionsデプロイメント (推奨)

最も簡単なデプロイ方法は、自動化されたGitHub Actionsを使用することです。

1. このリポジトリをフォーク して、あなたのGitHubアカウントに追加します。

2. Azure Publish Profileを取得する：

   az webapp deployment list-publishing-profiles -n your-app-name -g your-resource-group --xml
   

3. GitHubシークレットを追加する：

   • フォークしたリポジトリに移動 → 設定 → シークレットと変数 → アクション
   • "新しいリポジトリシークレット"をクリック
   • 名前: AZURE_WEBAPP_PUBLISH_PROFILE
   • 値: 手順2のXML出力を貼り付ける

4. 自動デプロイメント：

   • ✅ mainブランチにプッシュ → 自動的にビルドとデプロイが行われます。
   • ✅ TypeScriptコンパイル → ビルドプロセスを適切に処理します。
   • ✅ 本番環境での使用準備完了 → 環境を自動的に構成します。

🎯 自動化の機能：

• ✅ TypeScriptをJavaScriptに適切にビルドします。
• ✅ 本番環境で必要な依存関係をインストールします。
• ✅ Azure App Serviceにデプロイします。
• ✅ Node.js環境を構成します。
• ✅ デプロイメントのステータスとURLを提供します。

🏗️ 手動でのインフラストラクチャ作成

# リソースグループを作成
az group create --name vaali-mcp-rg --location centralus

# Bicepを使用してインフラストラクチャをデプロイ
az deployment group create \
  --resource-group vaali-mcp-rg \
  --template-file infra/main.bicep \
  --parameters webAppName=your-unique-app-name

# またはARMテンプレートを使用してデプロイ
az deployment group create \
  --resource-group vaali-mcp-rg \
  --template-file infra/azuredeploy.json \
  --parameters webAppName=your-unique-app-name

💸 価格帯

⚠️ 注意: App Serviceは24時間365日稼働します。あなたの地域の現在のAzure価格を確認してください。

💻 使用例

基本的な使用法

Claude Desktopで次のコマンドを試してみましょう。

"What's the weather in Seattle?"
"Calculate 25 * 4 + 10"
"Analyze the sentiment of 'This is amazing!'"
"Generate a weather report for Alice"
"Test the elicitation tool for rain prediction"

高度な使用法

AzureデプロイメントのAPI例です。

# 天気を取得 (SSE経由)
curl -X POST https://your-app.azurewebsites.net/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_weather", "arguments": {"location": "Tokyo"}}}'

# 誘導をテスト
curl -X POST https://your-app.azurewebsites.net/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "rain_prediction_with_elicitation", "arguments": {}}}'

📚 ドキュメント

ユーザーと初心者向け

• docs/CLAUDE_DESKTOP_GUIDE.md - Claude Desktopの完全な使い方ガイド
• docs/README.md - ドキュメントの索引とナビゲーション

開発者向け

• docs/IMPLEMENTATION_COMPREHENSIVE_GUIDE.md - 完全な技術的実装ガイド
• docs/test-documentation.md - テストスイートのドキュメント

研究者向け

• docs/ELICITATION_COMPREHENSIVE_GUIDE.md - 誘導パターンとベストプラクティス
• docs/ADVANCED_IMPLEMENTATION_SUMMARY.md - 技術アーキテクチャの概要

🔧 技術詳細

ハイブリッドアプローチ：2つの補完的な方法

1. 🔥 公式MCP誘導 (NEW)：ツールの実行中に欠落しているパラメータを収集する対話型ワークフロー

   • サーバーが server.elicitInput() を使用してクライアントから構造化データを直接要求します。
   • サポートするクライアントではJSONスキーマ駆動のフォームとダイアログが使用されます。
   • 即時のパラメータ収集を伴う受け入れ/拒否/キャンセル応答モデル。
   • ユーザー体験を向上させるための標準化されたプロトコル機能。

2. 📋 パラメータガイダンスパターン：既存のMCP機能を使用した汎用的な互換性アプローチ

   • インテリジェントなエラーハンドリングとコンテキストガイダンスを通じて、任意のMCPクライアントと動作します。
   • 豊富なコンテキストヘルプ、例、およびインテリジェントな提案。
   • エラー回復と嗜好学習のためのクライアント側のインテリジェンス。

主要な技術的貢献

• 🚀 対話型ワークフロー：実行を開始し、欠落しているパラメータを段階的に収集するツール。
• 🔄 ハイブリッド互換性：同じツールが誘導対応クライアントと標準MCPクライアントの両方で動作します。
• 🛡️ 適切なフォールバック：クライアントの機能を自動的に検出し、適切な応答パターンを提供します。
• 🎯 段階的な機能強化：対応するクライアントには強化された体験を、すべてのクライアントには汎用的な機能を提供します。
• 📊 包括的な実装：リソース、ツール、プロンプト、および誘導を備えた完全なMCPサーバー。

研究的意義

• 対話型AIワークフロー：ツールが実行中にシームレスにパラメータを収集する方法を実証します。
• プロトコルの進化：公式MCP誘導が既存のパラメータガイダンスと並行して動作することを示します。
• 汎用的な互換性：単一の実装がすべてのMCPクライアントの機能に対応します。
• ユーザー体験：エラーメッセージから対話型フォームへの段階的な機能強化。
• ハイブリッドアーキテクチャ：標準化された誘導と汎用的なフォールバックの両方の利点を兼ね備えています。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、LICENSEファイルを参照してください。