内容
# Dust Agent 集成的 MCP 服务器
一个自定义的 MCP（多云提供商）服务器，通过 HTTP 调用连接到 Dust.tt 代理平台。该服务器通过 MCP 接口暴露 Dust AI 代理的功能。
## 目录
- [Dust Agent 集成的 MCP 服务器](#dust-agent-集成的-mcp-服务器)
- [目录](#目录)
- [功能](#功能)
- [项目结构](#项目结构)
- [文档](#文档)
- [先决条件](#先决条件)
- [安装](#安装)
- [配置](#配置)
- [Dust Agent 设置](#dust-agent-设置)
- [MCP 服务器设置](#mcp-服务器设置)
- [运行服务器](#运行服务器)
- [Claude Desktop 集成](#claude-desktop-集成)
- [1. 安装](#1-安装)
- [2. 初始设置](#2-初始设置)
- [3. 与 MCP 服务器集成](#3-与-mcp-服务器集成)
- [4. 应用配置更改](#4-应用配置更改)
- [5. 在 Claude Desktop 中测试](#5-在-claude-desktop-中测试)
- [故障排除](#故障排除)
- [Dust.tt API 工作流程](#dusttt-api-工作流程)
- [1. 创建新对话](#1-创建新对话)
- [2. 向对话发送消息](#2-向对话发送消息)
- [3. 从对话中检索消息](#3-从对话中检索消息)
- [关于 API 的重要说明](#关于-api-的重要说明)
- [错误处理](#错误处理)
- [贡献](#贡献)
## 功能
- 通过 API 连接到 Dust.tt AI 代理
- 系统思维代理集成，具备认知神经科学和问题解决能力
- 支持 RAG（检索增强生成）
- 网络导航能力
- 简化的 MCP 工具接口
- 模块化代码结构，便于维护
- 外部化配置和 API 客户端类
## 项目结构
该项目遵循模块化结构，以提高可维护性：
- `server.py`：主服务器实现，注册工具并处理 MCP 功能
- `config.py`：包含 `DustAgentConfig` 类，用于管理配置设置
- `api_client.py`：包含 `DustAPIClient` 类，用于处理与 Dust.tt 的 API 交互
- `.env`：环境变量文件（未提交到版本控制）
- `.env.example`：环境变量模板
- `docs.md`：项目架构和 API 的全面文档
## 文档
有关架构、API 和故障排除的详细信息，请参阅 [全面文档](./docs.md)。
## 先决条件
- Python 3.10 或更高版本
- `pip` 包管理器
- 一个具有 API 访问权限的 Dust.tt 账户
- 一个现有的 Dust 代理配置
## 安装
1. **克隆此仓库：**
```bash
git clone https://github.com/Ma3u/mcp-server-dust.git
cd mcp-server-dust
```
2. **创建并激活虚拟环境：**
```bash
python3 -m venv .venv
# 在 macOS/Linux 上
source .venv/bin/activate
# 在 Windows 上
.venv\Scripts\activate
```
3. **安装所需依赖：**
```bash
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` 类管理。参数从环境变量加载，默认值如下：
```python
# 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 服务器：
```bash
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 网站](https://www.anthropic.com/claude/download) 下载 Claude Desktop
- 按照屏幕上的说明安装应用程序
### 2. 初始设置
- 安装后启动应用程序
- 使用你的 Anthropic 账户登录（免费账户即可）
### 3. 与 MCP 服务器集成
- 启动 Claude Desktop 并进入设置
- 在左侧边栏选择“开发者”选项卡
- 点击屏幕底部的“编辑配置”按钮
- 通过将 Dust MCP 服务器添加到 `mcpServers` 数组中来更新配置：
```json
{
"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.
```
## 故障排除
查看 Claude Desktop 中 Dust MCP 服务器的日志文件：
```bash
# 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 请求遵循以下过程：
### 1. 创建新对话
首先，服务器与 Dust 代理创建一个新对话：
```bash
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，用于后续请求：
```json
{
"conversation": {
"sId": "DhvpbhW74S",
"title": "Systems Thinking Conversation",
"created_at": 1742923287427
}
}
```
### 2. 向对话发送消息
接下来，服务器将用户的查询作为消息发送到对话中：
```bash
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：
```json
{
"message": {
"sId": "qwenj3rusI",
"conversation_sId": "DhvpbhW74S",
"content": "Explain the MCP Protocol in detail",
"author_name": "User",
"author_type": "user",
"created_at": 1742923287627
}
}
```
### 3. 从对话中检索消息
最后，服务器检索代理的响应。这需要特定格式的消息检索请求：
```bash
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"
}
}'
```
响应包含对话中的所有消息，包括代理的响应：
```json
{
"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。
连接信息
猜你喜欢
暂无推荐服务器