尘埃-MCP服务器

Name: 尘埃-MCP服务器
Author: ma3u

作者：ma3u5 星标更新：2025-05-28

安装使用来源：spider==github.com

项目介绍

Dust MCP Server

用于Dust.tt代理的模型上下文协议（MCP）服务器，旨在通过标准输入输出（STDIO）与Claude Desktop无缝集成。提供强大的代理查询、列表和配置工具。

用户指南

概述

Dust MCP服务器提供了通过模型上下文协议（MCP）与Dust.tt代理交互的标准接口。它支持与Claude Desktop和其他兼容MCP客户端的无缝集成，提供诸如代理发现、会话管理和消息处理等功能。

用户旅程

本节概述了与Dust MCP服务器及其集成代理进行交互时的典型用户旅程。

1. 初始设置和代理发现

入口点：用户登录到Dust平台
代理发现：
- 查看代理市场中的可用代理
- 根据类别筛选代理（例如，数据分析、内容创作、研究）
- 审阅代理功能、评分和文档
代理选择：
- 根据任务需求选择多个代理
- 创建新工作区或选择现有工作区

2. 工作区配置

布局设置：
- 在自定义布局中排列代理面板
- 配置特定于代理的设置和权限
上下文共享：
- 启用/禁用代理之间的上下文共享
- 设置代理之间的数据流
文件管理：
- 将文件上传到共享工作区
- 在项目文件夹中组织文件
- 为每个代理设置文件访问权限

3. 多代理协作

对话流程：
- 与主要代理发起聊天
- @提及其他代理以将其引入对话
- 在专用线程中查看代理间的通信
任务委派：
- 将特定任务分配给专业代理
- 跨代理监控任务进度
- 查看任务依赖关系和状态
文件协作：
- 与特定代理分享文件
- 跟踪文件访问和修改
- 查看版本历史和代理贡献

4. 高级交互

代理链式操作：
- 通过链接代理创建工作流
- 设置代理交接的条件逻辑
- 配置代理之间的自动触发器
上下文管理：
- 查看并编辑共享上下文
- 解决代理之间的上下文冲突
- 保存上下文快照以供未来参考

5. 报告和分析

报告生成：
- 请求分析代理生成报告
- 自定义报告模板和参数
- 导出多种格式的报告（PDF、Markdown、HTML）
洞察可视化：
- 查看交互式仪表板
- 过滤和深入数据可视化
- 比较来自不同代理的输出

快速开始

先决条件

Node.js v18或更高版本
npm 9.x或更高版本
带有API访问权限的Dust.tt账户
Redis服务器（用于会话管理）

会话管理

Dust MCP服务器包括一个使用Redis进行持久化的强大会话管理系统。这允许在服务器的多个实例之间安全且可扩展地处理会话。

功能

基于Redis的会话存储：安全且可扩展的会话存储
会话过期：自动清理过期会话
分布式支持：适用于分布式环境
会话数据：每个会话存储任意数据
API端点：用于会话管理的RESTful API

配置

Redis配置

环境变量 将这些变量添加到您的.env文件中：

# Redis配置
REDIS_ENABLED=true  # 设置为false以禁用Redis（使用内存存储）
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=  # 如果没有密码，请留空
REDIS_TLS=false  # 设置为true以启用安全连接
SESSION_SECRET=your_session_secret_here
SESSION_TTL=86400  # 24小时（秒）

测试连接

您可以使用以下命令测试您的Redis连接：

node -e "const { createClient } = require('redis'); (async () => { const client = createClient({ url: process.env.REDIS_URL }); await client.connect(); console.log('Redis连接成功'); await client.quit(); })().catch(console.error);"

开发中禁用Redis

如果您想在开发中不使用Redis运行服务器：
```
REDIS_ENABLED=false
```
这将使用内存存储。注意：这不适合生产环境。
跳过Redis缓存测试

要跳过与Redis相关的测试，请设置以下环境变量：
```
SKIP_REDIS_TESTS=true
```
或者在运行测试时：
```
SKIP_REDIS_TESTS=true npm test
```

将这些环境变量添加到您的.env文件中：

# Redis配置
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your_redis_password
REDIS_TLS=false
SESSION_SECRET=your_session_secret_here
SESSION_TTL=86400  # 24小时（秒）

API端点

创建会话

POST /api/sessions
Content-Type: application/json

{
  "userId": "user123",
  "data": {
    "角色": "管理员"
  },
  "ttl": 86400
}

获取会话

GET /api/sessions/:sessionId
授权: Bearer <会话令牌>

更新会话

PATCH /api/sessions/:sessionId
授权: Bearer <会话令牌>
Content-Type: application/json

{
  "data": {
    "角色": "管理员",
    "偏好设置": {}
  },
  "ttl": 86400
}

删除会话

DELETE /api/sessions/:sessionId
授权: Bearer <会话令牌>

验证会话

GET /api/sessions/:sessionId/validate
授权: Bearer <会话令牌>

使用会话中间件

要保护带有会话认证的路由，请使用sessionMiddleware：

import { sessionMiddleware } from './session/routes/sessionRoutes';
import { redisClient } from './config/redis';

// 应用于特定路由
app.get('/受保护的路由', sessionMiddleware(redisClient), (req, res) => {
  // 访问会话数据
  const session = req.session;
  res.json({ 消息: '访问已授权', 用户: session.userId });
});

// 或应用于所有路由
app.use(sessionMiddleware(redisClient));

会话数据结构

{
  "sessionId": "唯一会话ID",
  "userId": "user123",
  "data": {
    // 自定义会话数据
  },
  "过期时间": "2025-05-25T12:00:00.000Z",
  "创建时间": "2025-05-24T12:00:00.000Z",
  "更新时间": "2025-05-24T12:05:00.000Z"
}

最佳实践

保护会话密钥：使用强且唯一的密钥进行会话加密
适当设置TTL：在设置会话TTL时平衡安全性和用户体验
验证会话：在处理敏感操作之前始终验证会话
处理会话错误：实现适当的错误处理机制以应对会话相关操作
监控Redis：监控Redis服务器的健康状况和性能指标

故障排除

连接问题：验证Redis服务器是否正在运行且可访问
会话过期：检查会话是否过期太快，调整TTL
内存使用：监控Redis内存使用情况，特别是大型会话数据
日志：检查服务器日志中的会话相关错误

会话存储选项

服务器支持不同的会话存储后端：

内存存储（默认开发模式）

不需要额外设置
服务器重启时会话丢失
适合本地开发和测试

Redis存储（推荐生产模式）

# 安装Redis（macOS）
brew install redis

# 启动Redis服务器（在单独的终端中）
redis-server

# 在您的.env文件中：
SESSION_STORE_TYPE=redis
REDIS_URL=redis://localhost:6379

安装

克隆仓库：

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

安装依赖项：
```
npm install
```

设置环境变量：

cp .env.example .env
# 编辑.env文件以配置
LOG_LEVEL=info

# 高级配置
DUST_AGENT_IDS=代理1,代理2,代理3
MAX_SESSIONS=100
SESSION_TIMEOUT=3600

构建项目：
```
npm run build
```

启动服务器：

# 开发模式
npm run dev

# 生产模式
npm start

设置和配置

环境变量

变量	必需	描述	默认值
`DUST_API_KEY`	是	您的Dust.tt API密钥	-
`DUST_WORKSPACE_ID`	是	您的Dust.tt工作区ID	-
`PORT`	否	运行服务器的端口	`3000`
`NODE_ENV`	否	Node环境（开发/生产）	`开发`
`LOG_LEVEL`	否	日志级别（错误，警告，信息，调试）	`信息`
`DUST_AGENT_IDS`	否	要加载的代理ID的逗号分隔列表	-
`MAX_SESSIONS`	否	并发会话的最大数量	`1100`
`SESSION_TIMEOUT`	否	会话超时（秒）	`3600`（1小时）

Claude Desktop集成

要与Claude Desktop一起使用：

全局安装MCP工具：

npm install -g @modelcontextprotocol/tools

配置Claude Desktop以使用您的MCP服务器：

mcp configs set claude-desktop dust $(which node) $(pwd)/build/dust.js

重新启动Claude Desktop并开始与您的Dust代理互动。

MCP工具参考

以下MCP工具可用于与Dust代理交互：

`dust_list_agents`

列出配置工作区中的所有可用Dust代理。

参数：

includeDetails（布尔值，可选）：是否包含详细的代理信息

示例：

{
  "includeDetails": true
}

`dust_agent_query`

向Dust代理发送查询。

参数：

agentId（字符串，必需）：要查询的代理ID
query（字符串，必需）：要发送给代理的查询
sessionId（字符串，可选）：继续对话的会话ID
context（对象，可选）：查询的附加上下文

示例：

{
  "agentId": "代理123",
  "query": "今天的天气如何？",
  "sessionId": "会话456"
}

记忆银行系统

记忆银行系统为代理状态和配置提供持久存储：

活动上下文：跟踪所有活动代理会话的当前状态
决策日志：记录所有代理决策和行动
进度追踪：监控任务进度和完成状态
系统模式：定义可重用的交互模式
产品上下文：存储特定产品的配置和数据

开发者指南

项目结构

dust-mcp-server/
├── src/
│   ├── __tests__/           # 测试文件
│   │   ├── e2e/             # 端到端测试
│   │   ├── integration/     # 集成测试
│   │   └── unit/            # 单元测试
│   ├── agents/              # 代理实现
│   ├── api/                 # API路由和控制器
│   ├── middleware/          # Express中间件
│   ├── services/            # 业务逻辑服务
│   ├── tools/               # MCP工具实现
│   ├── types/               # TypeScript类型定义
│   └── utils/               # 实用函数
├── memory-bank/             # 代理状态的持久存储
│   ├── activeContext.md     # 活动会话的当前状态
│   ├── decisionLog.md       # 代理决策日志
│   ├── progress.md          # 任务进度追踪
│   ├── systemPatterns.md    # 可重用的交互模式
│   └── productContext.md    # 特定产品的配置
├── docs/                    # 文档文件
├── tests/                   # 额外的测试资源
├── .env.example             # 示例环境变量
├── .eslintrc.json           # ESLint配置
├── .gitignore               # Git忽略规则
├── jest.config.ts           # Jest测试配置
├── package.json             # 项目依赖项和脚本
├── README.md                # 此文件
└── tsconfig.json            # TypeScript配置

开发环境设置

克隆仓库并安装依赖项：

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

设置您的开发环境：

# 安装开发依赖项
npm install -D typescript ts-node ts-jest @types/jest @types/node

# 设置预提交钩子
npm run prepare

配置您的环境：

cp .env.example .env
# 编辑.env文件以配置

启动开发服务器：
```
npm run dev
```

测试

该项目包括全面的测试套件：

运行测试

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行端到端测试
npm run test:e2e

# 运行带覆盖率的测试
npm run test:coverage

测试结构

单元测试：隔离测试单个函数和类
集成测试：测试组件之间的交互
E2E测试：测试完整的用户流程

测试功能

外部服务的模拟实现
带有示例数据的测试数据库
API请求/响应验证
UI组件的快照测试

日志和调试

应用程序使用Winston进行日志记录，具有以下日志级别：

错误：导致应用程序失败的错误
警告：潜在有害的情况
信息：一般应用程序流程信息
调试：详细的调试信息
详细：非常详细的调试信息

在VS Code中调试

将此配置添加到您的.vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "调试测试",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test:debug"],
      "端口": 9229,
      "跳过文件": ["<node_internals>/**"]
    }
  ]
}

常见问题

TypeScript错误：运行npm run lint:fix以自动修复常见问题
测试失败：使用npm run test:reset清除测试数据库
依赖项问题：删除node_modules并运行npm install

API文档

API文档位于docs目录中，并可通过以下方式生成：

npm run docs:generate

API使用OpenAPI（Swagger）进行文档编写，可以在开发模式下通过/api-docs查看。

部署

先决条件

Node.js 18+
npm 9+
Docker（可选）

生产构建

# 安装生产依赖项
npm ci --only=production

# 构建应用
npm run build

# 启动服务器
NODE_ENV=生产 npm start

Docker

# 构建Docker镜像
docker build -t dust-m