星战科技xingzhan.cloud
返回市场
瓦里_MCP_服务器

瓦里_MCP_服务器

作者：ushakrishnan2 星标更新：2025-10-16
安装使用来源：spider==github.com

项目介绍

Vaali MCP Server

License: MIT Node.js TypeScript MCP SDK Azure App Service Infrastructure as Code GitHub Actions Platform Cost Optimized

☁️ Azure 部署

您的 MCP 服务器可以部署到 Azure 应用服务以获得云访问和可扩展性。

🚀 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 密钥：

    • 前往您的分叉仓库 → 设置 → 密钥和变量 → 动作
    • 点击“新建仓库密钥”
    • 名称：AZURE_WEBAPP_PUBLISH_PROFILE
    • 值：粘贴步骤 2 中的 XML 输出

  4. 自动部署：

    • ✅ 推送到主分支 → 自动构建和部署
    • ✅ TypeScript 编译 → 正确处理构建过程
    • ✅ 生产就绪 → 自动配置环境

🎯 自动化做了什么：

  • ✅ 正确地将 TypeScript 编译为 JavaScript
  • ✅ 安装生产依赖项
  • ✅ 部署到 Azure 应用服务
  • ✅ 配置 Node.js 环境
  • ✅ 提供部署状态和 URL

一个 模型上下文协议 (MCP) 服务器，通过交互式参数收集和上下文工作流自动化来展示高级 AI 代理的能力，包括官方 MCP 引发和智能参数引导模式。

📑 目录

🎯 这是什么？

Vaali 使 AI 助手（如 Claude）变得更聪明和更有帮助，通过提供：

  • 🔧 工具 它们可以使用（天气、计算、文本分析）
  • 📋 提示 指导复杂的工作流程
  • 📁 资源 包含您的数据和偏好
  • 🤖 交互式参数收集 智能地询问缺失的信息

简单示例：

您： "天气怎么样？"

带有引发能力的客户端：
✨ 出现一个交互表单询问位置
📍 您输入 "西雅图，华盛顿州"
🌤️ "西雅图当前天气：45°F，多云"

标准客户端：
📋 "我可以帮助查询天气！请提供您的位置：
   • 城市：'西雅图'，'伦敦'，'东京'
   • 带区域的城市：'奥斯汀，德克萨斯州'，'巴黎，法国'
   或输入任何城市名称..."

📸 实际 Claude 桌面引发操作

这是 Vaali MCP 服务器在 Claude 桌面上的引发操作：

Claude 桌面引发截图

截图展示了 Claude 桌面与 Vaali MCP 服务器的交互式参数收集，演示了无缝的用户体验和混合引发模式。

🧠 技术创新（针对研究人员）

本项目实现了 官方 MCP 引发和智能参数引导模式，展示了交互式参数收集在 AI 代理工作流中的全面方法。

混合方法：两种互补的方法

  1. 🔥 官方 MCP 引发（新）：在工具执行过程中收集缺失参数的交互工作流

    • 服务器直接使用 server.elicitInput() 向客户端请求结构化数据
    • 支持客户端中的 JSON 模式驱动的表单和对话框
    • 接受/拒绝/取消响应模型，立即收集参数
    • 标准化协议特性，增强用户体验

  2. 📋 参数引导模式：通过智能错误处理和上下文引导实现普遍兼容性的方法

    • 通过现有的 MCP 特性与任何 MCP 客户端兼容
    • 丰富的上下文帮助、示例和智能建议
    • 客户端侧智能错误恢复和偏好学习

关键技术贡献

  • 🚀 交互式工作流：工具在执行过程中逐步收集缺失参数
  • 🔄 混合兼容性：相同的工具适用于引发能力和标准 MCP 客户端
  • 🛡️ 平滑回退：自动检测客户端能力并采用适当的响应模式
  • 🎯 渐进增强：为有能力的客户端提供增强体验，为所有客户端提供通用功能
  • 📊 全面实现：完整的 MCP 服务器，包括资源、工具、提示和引发

研究意义

  • 交互式 AI 工作流：展示了工具如何在执行过程中无缝收集参数
  • 协议演进：展示了官方 MCP 引发与现有参数引导并存
  • 普遍兼容性：单一实现适用于所有 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 桌面启动服务器（stdio 模式）
npm run start:stdio

# 以 SSE 传输启动服务器（用于调试）
npm run start:sse

Claude 桌面集成

添加到您的 Claude 桌面配置文件中：

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

注意： 使用绝对路径以确保可靠运行。替换为您实际的项目路径。

然后尝试自然语言命令：

"东京的天气怎么样？"
"生成爱丽丝的天气报告"
"计算 25 * 4 + 10"
"测试引发工具"

🏗️ 完整的 MCP 实现

此服务器展示了所有四个 MCP 能力协同工作的示例：

✅ 资源（静态数据）

  • config: 应用程序配置和设置
  • sample-data: 用户资料和偏好
  • readme: 项目文档

✅ 工具（交互函数）

  • 天气工具：当前状况、预报、地点查找
  • 分析工具：文本分析、计算、数据处理
  • 引发工具：交互式参数收集测试

✅ 提示（工作流程模板）

  • 天气报告生成器：多步个性化报告
  • 代码审查：结构化检查清单
  • 文档编写器：综合文档生成

✅ 引发（交互式参数收集）

  • 官方 MCP 引发：JSON 模式驱动的交互表单
  • 参数引导：通过丰富的上下文帮助实现普遍兼容性
  • 混合实现：自动回退以实现最大兼容性

📚 更多了解

对用户和初学者

对开发者

对研究人员

🎮 VS Code 集成

调试模式目的如何使用
AI 工具构建者使用 AI 工具包测试F5 → "在 AI 工具构建者中调试"
MCP 检查器协议调试F5 → "在检查器中调试 SSE"
STDIO 模式客户端集成F5 → "在检查器中调试 STDIO"

🔬 这有什么特别之处

对本科生：交互式 AI 工具

代替僵硬的表单，AI 工具可以在对话过程中自然地收集信息——例如，在询问天气时询问您的位置，或在发送消息时询问邮件主题。

对研究生：双模式参数收集

实现了两种互补的方法：官方 MCP 引发，支持丰富交互表单的客户端，以及通过智能错误处理和提示实现普遍兼容性的参数引导。

对博士生：混合协议架构

展示了结构化协议的渐进增强——工具自动检测客户端能力，并提供最佳用户体验（交互表单），同时保持普遍兼容性（引导回退）。展示了如何在不破坏现有实现的情况下进化协议。

🧪 研究应用

  • 交互式 AI 工作流：工具如何在执行过程中无缝收集参数
  • 协议增强：在保持兼容性的同时扩展 MCP 的渐进能力
  • 用户体验设计：从错误消息到交互式表单再到自然对话
  • 客户端-服务器架构：能力检测和优雅降级模式
  • 混合系统设计：结合标准化协议和智能行为

🎯 项目状态

✅ 完整的 MCP 实现，具有所有四种能力（资源、工具、提示、引发）
✅ 交互式工作流工具，在执行过程中收集参数
✅ 混合兼容性 —— 适用于引发能力和标准客户端
✅ 全面的测试套件，展示交互式工作流
✅ Claude 桌面集成，支持自然语言使用
✅ 学习导向的服务器架构，适合教育和实验
✅ MIT 许可 —— 开源且准备接受贡献

基于 MCP SDK 1.7.0，旨在教学目的展示交互式 AI 工具的能力。

☁️ 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

� 定价层级：

层级使用场景相对成本
B1 基础学习、演示最低 ✅
B2 基础团队开发2x B1
S1 标准生产~5x B1

⚠️ 注意： 应用服务全天候运行。请查看您所在地区的 Azure 定价。

🔧 配置指南

📱 本地开发设置

对于 Claude 桌面集成（推荐用于开发）：

  1. 构建项目：

    npm install
npm run build

  2. 配置 Claude 桌面：

    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",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

  3. 测试连接：

    • 重启 Claude 桌面
    • 尝试："您有哪些可用的工具？"
    • 尝试："测试降雨预测的引发工具"

对于本地 SSE 测试：

# 在 SSE 模式下启动服务器
npm run start:sse

# 测试连接
curl http://localhost:3001/sse

☁️ Azure 生产设置

部署到 Azure 后，您的服务器将在以下地址可用：

  • 主要 URL: https://vaali-mcp-server.azurewebsites.net
  • SSE 端点: https://vaali-mcp-server.azurewebsites.net/sse

对于支持 SSE 传输的 MCP 客户端：

// 示例：连接到 Azure 部署的 Vaali 服务器
const { SSEClientTransport } = require('@modelcontextprotocol/sdk/client/sse.js');
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');

const client = new Client(
  {
    name: "vaali-client",
    version: "1.0.0"
  },
  {
    capabilities: {}
  }
);

const transport = new SSEClientTransport(
  new URL('https://your-app-name.azurewebsites.net/sse')
);

await client.connect(transport);

对于 Web 应用：

<!-- 从浏览器直接连接 SSE -->
<script>
const eventSource = new EventSource('https://your-app-name.azurewebsites.net/sse');
eventSource.onmessage = function(event) {
  console.log('MCP 消息:', event.data);
};
</script>

🔀 传输协议解释

STDIO 传输（本地）

  • 使用场景： 与 Claude 桌面直接集成
  • 如何工作： 进程间通信
  • 优点： 低延迟，安全，无网络开销
  • 配置： Claude 桌面配置文件

SSE 传输（Azure/Web）

  • 使用场景： Web 基础的 MCP 客户端，云部署
  • 如何工作： HTTP 服务器发送事件
  • 优点： 通过防火墙，Web 兼容，可扩展
  • 配置： HTTP 端点 URL

🧪 测试您的部署

本地测试（STDIO）：

# 测试基本功能
npm run test:advanced-concept

# 使用 Claude 桌面测试
# 1. 配置 Claude 桌面（参见上文）
# 2. 在 Claude 中："东京的天气怎么样？"
# 3. 在 Claude 中："测试引发工具"

Azure 测试（SSE）：

# 健康检查
curl https://your-app-name.azurewebsites.net/sse

# 测试 MCP 能力
curl -X POST https://your-app-name.azurewebsites.net/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc