MCP 服务器

MCP Server for Dust Agent Integration

通过 HTTP 调用连接到 Dust Agent

ma3u

开发者工具

访问服务器

README

用于 Dust Agent 集成的 MCP 服务器

一个自定义的 MCP (多云提供商) 服务器，通过 HTTP 调用连接到 Dust.tt 代理平台。此服务器通过 MCP 接口公开 Dust AI 代理的功能。

功能

通过 API 连接到 Dust.tt AI 代理
具有认知神经科学和问题解决能力的系统思维代理集成
RAG (检索增强生成) 支持
Web 导航能力
简化的 MCP 工具界面
模块化代码结构，提高可维护性
外部化配置和 API 客户端类

项目结构

该项目遵循模块化结构，以提高可维护性：

server.py: 主要服务器实现，注册工具并处理 MCP 功能
config.py: 包含 DustAgentConfig 类，用于管理配置设置
api_client.py: 包含 DustAPIClient 类，用于处理与 Dust.tt 的 API 交互
.env: 环境变量文件 (不提交到版本控制)
.env.example: 环境变量模板
docs.md: 项目架构和 API 的综合文档

文档

有关架构、API 和故障排除的详细信息，请参阅综合文档。

先决条件

Python 3.10 或更高版本
pip 包管理器
具有 API 访问权限的 Dust.tt 帐户
现有的 Dust 代理配置

安装

克隆此存储库：

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

创建并激活虚拟环境：

python3 -m venv .venv

# 在 macOS/Linux 上
source .venv/bin/activate

# 在 Windows 上
.venv\Scripts\activate

安装所需的依赖项：

pip install --upgrade pip
pip install mcp requests python-dotenv

配置

Dust Agent 设置

在根目录中创建一个 .env 文件，其中包含您的配置 (您可以从 .env.example 复制并修改)：

# MCP 服务器配置
MCP_NAME=Dust MCP Server
MCP_HOST=127.0.0.1
MCP_PORT=5001
MCP_TIMEOUT=30

# Dust Agent 配置
DUST_AGENT_ID=your_agent_id
DUST_DOMAIN=https://dust.tt
DUST_WORKSPACE_ID=your_workspace_id
DUST_WORKSPACE_NAME=your_workspace_name
DUST_API_KEY=your_api_key
DUST_AGENT_NAME=your_agent_name
DUST_TIMEZONE=Europe/Berlin
DUST_USERNAME=your_username
DUST_FULLNAME=Your Full Name

安全提示： 确保将 .env 添加到您的 .gitignore 文件中，以防止提交敏感信息。

MCP 服务器设置

服务器配置参数现在由 config.py 中的 DustAgentConfig 类管理。参数从环境变量加载，并具有以下默认值：

# MCP 服务器配置
MCP_NAME = "Dust MCP Server"  # MCP 服务器的名称
MCP_HOST = "127.0.0.1"        # 运行服务器的主机
MCP_PORT = 5001               # 运行服务器的端口
MCP_TIMEOUT = 30              # 请求超时时间（秒）

# Dust Agent 配置
DUST_AGENT_ID = "8x9nuWdMnR"  # 您的 Dust 代理 ID
DUST_DOMAIN = "https://dust.tt" # Dust API 域名
# ... 以及其他 Dust 特定的设置

运行服务器

要启动 MCP 服务器：

python server.py

您应该看到类似于以下的输出：

Starting MCP server 'Dust MCP Server' on 127.0.0.1:5001
Connected to Dust agent 'SystemsThinking' (ID: 8x9nuXXXX)

服务器将运行直到被 Ctrl+C 中断。

Claude Desktop 集成

要配置 Claude Desktop 以与此 MCP 服务器一起使用：

1. 安装

从 Anthropic 官方网站下载 Claude Desktop
按照屏幕上的说明为您的操作系统安装应用程序

2. 初始设置

安装后启动应用程序
使用您的 Anthropic 帐户登录 (免费帐户就足够了)

3. 与 MCP 服务器集成

启动 Claude Desktop 并转到设置
选择左侧边栏上的“开发者”选项卡
单击屏幕底部的“编辑配置”按钮
通过将其包含在 mcpServers 数组中，将您的 Dust MCP 服务器添加到配置中：

{
    "mcpServers": {
        "dust": {
            "command": "/Users/ma3u/projects/mcp-server-dust/.venv/bin/python",
            "args": [
                "/Users/ma3u/projects/mcp-server-dust/server.py"
            ],
            "host": "127.0.0.1",
            "port": 5001,
            "timeout": 10000
        }
    }
}

注意： 如果 mcpServers 数组中存在现有条目，请将您的配置添加为新项目。

4. 应用配置更改

在更改 MCP 服务器配置后：
- 对于 Claude Desktop，完全退出应用程序
- 重新启动 Claude Desktop 以使新配置生效
通过检查您的服务器是否出现在开发者设置的列表中来验证连接

5. 在 Claude Desktop 中测试

在 Claude Desktop 中键入以下内容以测试您的集成：

Use Systemsthinking Agent to explain MCP Protocol.

alt text

故障排除

在 Claude Desktop 中查看 Dust MCP 服务器的日志文件：

# macOS/Linux
tail -f ~/Library/Logs/Claude/mcp-server-dust.log

# Windows
Get-Content -Path "C:\Users\{username}\AppData\Local\Logs\Claude\mcp-server-dust.log" -Wait

Dust.tt API 工作流程

MCP 服务器通过多步骤工作流程与 Dust.tt 的 API 交互。每个使用 Dust 代理的 Claude 请求都遵循此过程：

Dust API Workflow Diagram

1. 创建新对话

首先，服务器与 Dust 代理创建一个新的对话：

curl -X POST "https://dust.tt/api/v1/w/{WORKSPACE_ID}/assistant/conversations" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Systems Thinking Conversation",
    "model": "claude-3-5-sonnet-20240620"
  }'

这将返回一个对话 ID，该 ID 用于后续请求：

{
  "conversation": {
    "sId": "DhvpbhW74S",
    "title": "Systems Thinking Conversation",
    "created_at": 1742923287427
  }
}

2. 向对话发送消息

接下来，服务器将用户的查询作为消息发送到对话：

curl -X POST "https://dust.tt/api/v1/w/{WORKSPACE_ID}/assistant/conversations/{CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Explain the MCP Protocol in detail",
    "mentions": [{
      "configurationId": "{AGENT_ID}",
      "context": {
        "timezone": "Europe/Berlin",
        "modelSettings": {"provider": "anthropic"}
      }
    }],
    "context": {
      "timezone": "Europe/Berlin"
    }
  }'

响应包括消息 ID：

{
  "message": {
    "sId": "qwenj3rusI",
    "conversation_sId": "DhvpbhW74S",
    "content": "Explain the MCP Protocol in detail",
    "author_name": "User",
    "author_type": "user",
    "created_at": 1742923287627
  }
}

3. 从对话中检索消息

最后，服务器检索代理的响应。这需要消息检索请求的特定格式：

curl -X POST "https://dust.tt/api/v1/w/{WORKSPACE_ID}/assistant/conversations/{CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "RETRIEVAL_QUERY",
    "mentions": [{
      "configurationId": "{AGENT_ID}",
      "context": {
        "timezone": "Europe/Berlin",
        "modelSettings": {"provider": "anthropic"}
      }
    }],
    "context": {
      "timezone": "Europe/Berlin",
      "username": "api_retrieval",
      "queryType": "history_analysis"
    }
  }'

响应包含对话中的所有消息，包括代理的响应：

{
  "messages": [
    {
      "id": "msg_user123",
      "role": "user",
      "content": "Explain the MCP Protocol in detail",
      "timestamp": 1742923287627,
      "status": "processed"
    },
    {
      "id": "msg_agent456",
      "role": "assistant",
      "content": "The MCP (Mission Control Protocol) is a framework designed for...",
      "timestamp": 1742923290000,
      "status": "processed"
    }
  ]
}

关于 API 的重要说明

消息检索端点具有双重用途 - 它可用于创建新消息或检索对话历史记录
对于消息检索，即使它本质上是一个 GET 操作，也需要正确结构的有效负载
content 字段是必需的，并且必须至少包含一个字符 (我们使用 "RETRIEVAL_QUERY" 作为占位符)
mentions 和 context 字段必须按照上述方式正确构造
您需要多次轮询此端点，直到代理的响应出现

错误处理

使用 Dust.tt API 时的常见错误：

400 Bad Request: 通常表示 JSON 格式错误或请求有效负载中缺少必需字段
401 Unauthorized: 检查您的 API 密钥
404 Not Found: 验证您的工作区 ID 和对话 ID
429 Too Many Requests: 您已超出 API 速率限制

为了进行调试，服务器以 curl 格式记录所有 API 请求，以便您可以手动重现和排除故障。

贡献

欢迎贡献！请随时提交 Pull Request。