Dust Py

用于粉尘剂集成的MCP服务器

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

目录

• 用于粉尘剂集成的MCP服务器

- 目录 - 特性 - 项目结构 - 文档 - 先决条件 - 安装 - 配置 - 除尘剂设置 - MCP服务器设置 - 运行服务器 - Claude桌面集成 - 1.安装 - 2.初始设置 - 3.与MCP服务器集成 - 4.应用配置更改 - 5.在Claude Desktop中进行测试 - 故障排除 - Dust.tt API工作流 - 1.创建新对话 - 2.向对话发送消息 - 3.从对话中检索消息 - 关于API的重要说明 - 错误处理 - 贡献

特性

• 通过API连接Dust.tt AI代理
• 系统思维代理与认知神经科学和问题解决能力的整合
• RAG（检索增强生成）支持
• Web导航功能
• 简化的MCP工具界面
• 模块化代码结构，可更好地维护
• 外部化配置和API客户端类

项目结构

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

• server.py：注册工具和处理MCP功能的主服务器实现
• config.py：包含 DustAgentConfig 用于管理配置设置的类
• api_client.py：包含 DustAPIClient 用于处理API与Dust.tt交互的类
• .env：环境变量文件（未提交版本控制）
• .env.example：环境变量模板
• docs.md：项目架构和API的全面文档

文档

有关体系结构、API和故障排除的详细信息，请参阅 全面的文件.

先决条件

• Python 3.10或更高版本
• pip 包管理器
• 拥有API访问权限的Dust.tt帐户
• 现有的除尘剂配置

安装

1. 克隆此存储库：

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

1. 创建并激活虚拟环境：

   python3 -m venv .venv

   # On macOS/Linux
   source .venv/bin/activate

   # On Windows
   .venv\Scripts\activate

1. 安装所需的依赖项：

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

配置

除尘剂设置

创建一个 .env 根目录中包含您的配置的文件（您可以从以下位置复制 .env.example 并修改）：

# MCP Server Configuration
MCP_NAME=Dust MCP Server
MCP_HOST=127.0.0.1
MCP_PORT=5001
MCP_TIMEOUT=30

# Dust Agent Configuration
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服务器设置

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

# MCP Server Configuration
MCP_NAME = "Dust MCP Server"  # Name of your MCP server
MCP_HOST = "127.0.0.1"        # Host to run the server on
MCP_PORT = 5001               # Port to run the server on
MCP_TIMEOUT = 30              # Request timeout in seconds

# Dust Agent Configuration
DUST_AGENT_ID = "8x9nuWdMnR"  # Your Dust agent ID
DUST_DOMAIN = "https://dust.tt" # Dust API domain
# ... and other Dust-specific settings

运行服务器

要启动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桌面集成

要配置Claude Desktop以与此MCP服务器一起使用，请执行以下操作：

1.安装

• 从下载克劳德桌面 Anthropic官方网站
• 按照操作系统的屏幕说明安装应用程序

2.初始设置

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

3.与MCP服务器集成

• 启动克劳德桌面并转到设置
• 选择左侧边栏的“开发人员”选项卡
• 点击屏幕底部的“编辑配置”按钮
• 将您的Dust MCP服务器添加到配置中 mcpServers 数组：

{
    "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：

{
  "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操作
• 内容字段是必需的，并且必须至少包含一个字符（我们使用“RETRIEVAL_QUERY”作为占位符）
• 提及和上下文字段的结构必须正确，如上所示
• 您需要多次轮询此端点，直到代理的响应出现

错误处理

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

• 400错误请求：通常表示JSON格式错误或请求负载中缺少必填字段
• 401未经授权：检查您的API密钥
• 404未找到：验证您的工作区ID和对话ID
• 429请求太多：您已超过API费率限制

出于调试目的，服务器以curl格式记录所有API请求，以便您可以手动复制和排除它们的故障。

贡献

欢迎投稿！请随时提交拉取请求。