Vaali MCP Server

🚀 Vaali MCP 服務器

Vaali MCP 服務器是一個模型上下文協議（MCP）服務器，它通過交互式參數收集和上下文工作流自動化展示了高級 AI 代理功能。它支持官方 MCP 啟發式交互和智能參數引導模式，能讓 AI 助手（如 Claude）更智能、更實用。

🚀 快速開始

前提條件

• 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 的服務器（標準輸入輸出模式）
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 發佈配置文件：

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

3. 添加 GitHub 機密：
   • 進入你復刻的倉庫 → 設置 → 機密和變量 → Actions
   • 點擊“新建倉庫機密”
   • 名稱：AZURE_WEBAPP_PUBLISH_PROFILE
   • 值：粘貼步驟 2 中的 XML 輸出。
4. 自動部署：
   • ✅ 推送到主分支 → 自動構建並部署。
   • ✅ TypeScript 編譯 → 正確處理構建過程。
   • ✅ 生產就緒 → 自動配置環境。

🎯 自動化部署的作用

• ✅ 正確將 TypeScript 編譯為 JavaScript。
• ✅ 安裝生產依賴項。
• ✅ 部署到 Azure App Service。
• ✅ 配置 Node.js 環境。
• ✅ 提供部署狀態和 URL。

🏗️ Azure 基礎設施設置

如果你需要先創建 Azure 資源，可以使用 Bicep/ARM 模板：

🏗️ 手動創建基礎設施

# 創建資源組
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/7 運行。請查看當前 Azure 定價 以瞭解你所在地區的價格。

💻 使用示例

基礎用法

# 克隆並設置項目
git clone <repository-url>
cd vaali

# 安裝依賴
npm install

# 構建項目
npm run build

高級用法

# 啟動適用於 Claude Desktop 的服務器（標準輸入輸出模式）
npm run start:stdio

# 啟動使用 SSE 傳輸的服務器（用於調試）
npm run start:sse

📚 詳細文檔

面向用戶和初學者

• 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 - 技術架構概述。

🔧 技術細節

🧠 技術創新（面向研究人員）

本項目實現了 官方 MCP 啟發式交互和智能參數引導模式，展示了在 AI 代理工作流中進行交互式參數收集的全面方法。

混合方法：兩種互補的方式

1. 🔥 官方 MCP 啟發式交互（新特性）：在工具執行期間收集缺失參數的交互式工作流。
   • 服務器使用 server.elicitInput() 直接從客戶端請求結構化數據。
   • 支持客戶端使用 JSON 模式驅動的表單和對話框。
   • 採用接受/拒絕/取消響應模型，可立即收集參數。
   • 標準化協議特性，提升用戶體驗。
2. 📋 參數引導模式：使用現有 MCP 特性的通用兼容方法。
   • 通過智能錯誤處理和上下文引導，可與任何 MCP 客戶端配合使用。
   • 提供豐富的上下文幫助、示例和智能建議。
   • 客戶端具備錯誤恢復和偏好學習的智能能力。

關鍵技術貢獻

• 🚀 交互式工作流：工具開始執行並逐步收集缺失參數。
• 🔄 混合兼容性：相同的工具可與支持啟發式交互的客戶端和標準 MCP 客戶端配合使用。
• 🛡️ 優雅回退：自動檢測客戶端能力並採用適當的響應模式。
• 🎯 漸進式增強：為支持的客戶端提供增強體驗，為所有客戶端提供通用功能。
• 📊 全面實現：完整的 MCP 服務器，包含資源、工具、提示和啟發式交互功能。

研究意義

• 交互式 AI 工作流：展示了工具如何在執行過程中無縫收集參數。
• 協議演變：展示了官方 MCP 啟發式交互與現有參數引導模式的協同工作。
• 通用兼容性：單一實現可適用於所有 MCP 客戶端能力。
• 用戶體驗：從錯誤消息到交互式表單的漸進式增強。
• 混合架構：結合了標準化啟發式交互和通用回退機制的優點。

🔀 傳輸協議解釋

STDIO 傳輸（本地）

• 使用場景：與 Claude Desktop 直接集成。
• 工作原理：進程間通信。
• 優點：低延遲、安全、無網絡開銷。
• 配置：Claude Desktop 配置文件。

SSE 傳輸（Azure/Web）

• 使用場景：基於 Web 的 MCP 客戶端、雲部署。
• 工作原理：HTTP 服務器發送事件。
• 優點：可通過防火牆、與 Web 兼容、可擴展。
• 配置：HTTP 端點 URL。

🔧 環境變量

本地開發

NODE_ENV=development
TRANSPORT=stdio

Azure 生產環境

NODE_ENV=production
TRANSPORT=sse
PORT=3001
WEBSITE_NODE_DEFAULT_VERSION=18-lts
SCM_DO_BUILD_DURING_DEPLOYMENT=true

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🤝 貢獻

歡迎貢獻代碼！本項目展示了高級 MCP 模式，非常適合以下人群：

• 研究人員：擴展啟發式交互模式和協議研究。
• 開發者：添加新工具並改進客戶端兼容性。
• 學生：學習交互式 AI 工作流和協議設計。

開發設置

# 開發模式，支持熱重載
npm run dev:stdio

# 持續運行測試
npm run test:watch

# 使用 VS Code 進行調試
按 F5 → 選擇調試配置

貢獻領域

• 額外的啟發式交互模式和示例。
• 展示參數收集的新交互式工具。
• 客戶端兼容性測試和改進。
• 文檔和教育內容。
• 性能優化和錯誤處理。

想了解交互式工作流如何改變 AI 交互嗎？ 運行 npm run test:advanced-concept 進行教育性演練！