MCP Dust 服务器

本仓库包含了一个 Model Context Protocol (MCP) 服务器的实现，该服务器设计用于与 Dust 代理进行交互。服务器分为两个主要组件：MCP 服务器（处理 Dust API 交互）和 MCP 测试客户端（提供用于测试的 Web 界面）。

目录

• MCP Dust 服务器
  • 目录
  • 功能
  • 架构
  • Dust.tt 代理 AI
  • 安装
    • 先决条件
    • 步骤
  • 启动服务器和客户端
    • 预期输出
  • API 端点
  • 调试
  • 集成
    • Windsurf IDE 配置
    • Claude 桌面集成
  • 测试
  • API 概览
  • 开发者文档
  • 许可证

功能

• 分离的 MCP 服务器和测试客户端组件
• 通过 Dust API 与 Dust AI 代理进行交互
• 使用 Server-Sent Events (SSE) 和 HTTP Stream Transport 实现实时流响应
• 完全支持 JSON-RPC 2.0，包括 'initialize'、'message'、'terminate' 和 'run' 方法
• 通过 'run' 方法直接执行工具，简化客户端集成
• 强大的会话管理和上下文保存
• 在日志中安全处理 API 密钥并屏蔽 PII
• 心跳机制以保持持久连接
• 自动重连断开的连接
• 全面的错误处理和报告
• 支持最新的 MCP 规范（2025-03-26）
• 用于监控和健康检查的状态端点

架构

MCP Dust 服务器使用以下组件构建：

图 1： MCP 服务器架构显示了服务器和客户端组件

1. MCP 服务器 (server.ts):

   • 处理与 Dust API 的 MCP 协议交互
   • 管理会话状态和上下文
   • 实现完整的 MCP 生命周期（初始化、消息、终止）
   • 支持 SSE 和 HTTP Stream Transport
   • 提供用于监控的状态端点

2. MCP 测试客户端 (client.ts):

   • 提供一个用于测试的 Web 界面
   • 允许与 MCP 服务器进行交互
   • 支持实时流和调试
   • 包括会话管理和连接跟踪

Dust.tt 代理 AI

Dust.tt 是一个旨在帮助组织构建和部署满足其特定需求的自定义 AI 代理的平台。它集成了先进的 AI 模型，如 GPT-4、Claude、Gemini 和 Mistral，并结合企业级安全特性，以简化工作流程、自动化任务并提高各种业务功能的生产力。

图 2： Dust.tt 平台界面截图，展示了代理功能

自定义 AI 代理：个性化代理：创建具有自定义指令和工具的代理，以满足团队或个人需求。

公司上下文：将代理与内部工具（如 Notion、Slack、GitHub）或外部 API 集成，以便无缝访问公司数据。

多代理工作流：在一个工作流中组合和链接多个具有独特能力的代理。

与数据源集成：数据连接：将代理连接到 SharePoint、Zendesk、Jira、Salesforce、Snowflake 等的数据。

动态查询：使用代理通过自然语言或 SQL 查询来分析电子表格、数据库和仓库。

实时更新：持续同步公司知识以获得最新响应。

开源：在 GitHub 上以 MIT 许可证提供。拥有庞大的用户和开发者社区。

托管：SaaS 或在您自己的服务器上自行托管

安装

前提条件

• Node.js（推荐：通过 nvm 安装的最新 LTS 版本）
• npm（随 Node.js 一起安装）
• TypeScript

步骤

1. 克隆仓库：

   git clone https://github.com/ma3u/mcp-dust-server.git
   cd mcp-dust-server
   

2. 安装依赖项：

   npm install
   

3. 配置环境变量：
   在根目录下基于 .env.example 创建一个 .env 文件：

   # 启动模式 (server, client, 或 both)
   START_MODE=both
   
   # MCP 服务器配置
   MCP_NAME=Dust MCP Server JS
   MCP_HOST=127.0.0.1
   MCP_PORT=5001
   MCP_TIMEOUT=30 # 秒
   
   # MCP 测试客户端配置
   CLIENT_HOST=127.0.0.1
   CLIENT_PORT=6001
   
   # Dust API 配置
   DUST_API_KEY=your_dust_api_key_here
   DUST_WORKSPACE_ID=your_workspace_id_here
   DUST_AGENT_ID=your_agent_id_here
   DUST_DOMAIN=https://dust.tt
   
   # 用户上下文信息（用于 Dust API 请求）
   DUST_USERNAME=your_username
   DUST_EMAIL=your_email@example.com
   DUST_FULLNAME=Your Full Name
   DUST_TIMEZONE=Europe/Berlin
   

启动服务器和客户端

您可以分别或同时运行 MCP 服务器和测试客户端。项目提供了几种不同的 npm 脚本来应对不同场景：

1. 同时启动服务器和客户端：

   npm run start
   

2. 仅启动 MCP 服务器：

   npm run start:server
   

3. 仅启动测试客户端：

   npm run start:client
   

预期输出

如果一切配置正确，您应该会看到类似以下的输出：

对于 MCP 服务器：

MCP Server running on http://127.0.0.1:5001 (timeout: 30s)
Server name: Dust MCP Bridge
Dust workspace: your_workspace_id
Dust agent: your_agent_id

对于测试客户端：

MCP Test Client running on http://127.0.0.1:6001

API 端点

服务器提供了几个用于健康检查和 MCP 协议通信的端点。有关详细的 API 文档，请参阅 开发者文档。

关键端点包括：

• 健康检查: /health, /ready, /live
• MCP 协议: /sse (服务器发送事件), /stream (HTTP 流传输)

调试

有关调试工具和技术的详细信息，包括 MCP Inspector，请参阅开发者文档。

解决连接问题

如果您在使用 MCP Inspector 或其他客户端时遇到连接问题，请检查以下常见问题：

1. 端口配置不匹配: 确保您的 .env 文件中的端口设置（MCP_PORT, MCP_MIN_PORT, MCP_MAX_PORT）一致。

2. 传输模式: 对于 Claude Desktop 或使用 stdio 传输的 MCP Inspector，请在 .env 中设置 TRANSPORT_MODE=stdio。

3. 多个响应头: 如果您看到 "ERR_HTTP_HEADERS_SENT" 错误，请检查是否有中间件发送了多个响应。

有关全面的故障排除指南，请参阅开发者文档中的解决常见问题部分。

集成

Windsurf IDE 配置

要将 Dust MCP 服务器与 Windsurf IDE 集成，请更新配置文件 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "dust-mcp": {
      "command": "npm",
      "args": [
        "run",
        "start:server"
      ],
      "env": {
        "DUST_API_KEY": "${YOUR_API_KEY}",
        "DUST_WORKSPACE_ID": "${YOUR_WORKSPACE_ID}",
        "DUST_AGENT_ID": "${YOUR_AGENT_ID}"
      },
      "host": "127.0.0.1",
      "port": 5001,
      "timeout": 30000
    }
  }
}

Claude Desktop 集成

要将 Dust MCP 服务器与 Claude Desktop 集成，请更新其配置文件：

{
  "mcpServers": {
    "dust-agent": {
      "command": "npm",
      "args": [
        "run",
        "start:server"
      ],
      "cwd": "path/to/mcp-dust-server",
      "host": "127.0.0.1",
      "port": 5001,
      "timeout": 30000,
      "env": {
        "DUST_API_KEY": "${YOUR_API_KEY}",
        "DUST_WORKSPACE_ID": "${YOUR_WORKSPACE_ID}",
        "DUST_AGENT_ID": "${YOUR_AGENT_ID}"
      }
    }
  }
}

测试

该项目包括基于 Web 和命令行的测试工具。有关详细的测试信息，请参阅开发者文档。

当您运行客户端组件时，可以通过 http://localhost:6001 访问基于 Web 的测试客户端，从而与您的 Dust 代理进行交互并测试 MCP 服务器的功能。

API 概览

服务器提供了多个用于健康检查和 MCP 协议通信的端点。有关详细的 API 文档，请参阅开发者文档。

开发者文档

有关项目结构、API 文档、调试工具和安全注意事项等详细技术信息，请参阅开发者文档。

许可证

本项目采用 MIT 许可证。