MCP 除尘服务器

此代码库包含一个模型上下文协议 (MCP) 服务器的实现，用于与 Dust 代理交互。该服务器分为两个主要组件：MCP 服务器（用于处理 Dust API 交互）和 MCP 测试客户端（提供用于测试的 Web 界面）。

目录

• MCP 除尘服务器
  • 目录
  • 特征
  • 建筑学
  • Dust.tt Agentic AI
  • 安装
    • 先决条件
    • 步骤
  • 启动服务器和客户端
    • 预期输出
  • API 端点
  • 调试
  • 一体化
    • Windsurf IDE 配置
    • Claude 桌面集成
  • 测试
  • API 概述
  • 开发人员文档
  • 执照

特征

• 分离 MCP 服务器和测试客户端组件
• 通过 Dust API 与 Dust AI 代理进行交互
• 使用服务器发送事件 (SSE) 和 HTTP 流传输进行实时流响应
• 完全支持 JSON-RPC 2.0，具有“初始化”、“消息”、“终止”和“运行”方法
• 通过“运行”方法直接执行工具，以简化客户端集成
• 强大的会话管理和上下文保存
• 使用日志中的 PII 屏蔽来保护 API 密钥处理
• 心跳机制维持持久连接
• 断开连接后自动重新连接
• 全面的错误处理和报告
• 支持最新MCP规范（2025-03-26）
• 监控和健康检查的状态端点

建筑学

MCP Dust 服务器由以下组件构成：

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

1. MCP 服务器（server.ts） ：
   • 处理与 Dust API 的 MCP 协议交互
   • 管理会话状态和上下文
   • 实现完整的 MCP 生命周期（初始化、消息、终止）
   • 支持 SSE 和 HTTP 流传输
   • 提供监控状态端点
2. MCP 测试客户端（client.ts） ：
   • 提供用于测试的 Web 界面
   • 允许与 MCP 服务器交互
   • 支持实时流和调试
   • 包括会话管理和连接跟踪

Dust.tt Agentic AI

Dust.tt 是一个旨在帮助企业构建和部署定制化 AI 代理的平台，以满足其特定需求。它集成了 GPT-4、Claude、Gemini 和 Mistral 等先进的 AI 模型，并具备企业级安全功能，从而简化工作流程、实现任务自动化，并提升各项业务职能的生产力。

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

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

公司环境：将代理与 Notion、Slack、GitHub 等内部工具或外部 API 集成，以无缝访问公司数据。

多代理工作流：在单个工作流中组合并链接多个代理，每个代理都有独特的功能。

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

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

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

开源：基于 MIT 许可证，可在GitHub上获取。拥有庞大的用户和开发者社区。

托管：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文件：
   # Startup Mode (server, client, or both) START_MODE=both # MCP Server Configuration MCP_NAME=Dust MCP Server JS MCP_HOST=127.0.0.1 MCP_PORT=5001 MCP_TIMEOUT=30 # seconds # MCP Test Client Configuration CLIENT_HOST=127.0.0.1 CLIENT_PORT=6001 # Dust API Configuration 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 # User Context Information (used in Dust API requests) 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 服务器：

对于测试客户端：

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. 传输模式：对于使用 stdio 传输的 Claude Desktop 或 MCP Inspector，请在.env中设置TRANSPORT_MODE=stdio
3. 多个响应标头：如果您看到“ERR_HTTP_HEADERS_SENT”错误，请检查中间件是否发送了多个响应

有关全面的故障排除指南，请参阅开发人员文档中的“故障排除常见问题”部分。

一体化

Windsurf IDE 配置

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

Claude 桌面集成

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

测试

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

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

API 概述

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

开发人员文档

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

执照

该项目已获得MIT 许可。