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 进行教育性演练！