Dust MCP Server (Ma3u)

灰尘MCP服务器

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

目录

• 用户指南

- 概述 - 用户旅程 - 快速开始 - 设置和配置 - MCP工具参考 - 存储体系统

• 开发者指南

- 项目结构 - 开发设置 - 测试 - 日志记录和调试 - API文档 - 部署 - 贡献 - 许可证 - 相关资源

用户指南

概述

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 Server包括一个使用Redis进行持久化的强大会话管理系统。这允许跨服务器的多个实例进行安全和可扩展的会话处理。

特性

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

配置

Redis配置

1. 环境变量

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

   # Redis Configuration
   REDIS_ENABLED=true  # Set to false to disable Redis (uses in-memory store)
   REDIS_URL=redis://localhost:6379
   REDIS_PASSWORD=  # Leave empty if no password is set
   REDIS_TLS=false  # Set to true for secure connections
   SESSION_SECRET=your_session_secret_here
   SESSION_TTL=86400  # 24 hours in seconds

1. 测试连接

您可以通过以下方式测试Redis连接：

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

1. 禁用Redis进行开发

如果你想在没有Redis的情况下运行服务器进行开发：

   REDIS_ENABLED=false

这将使用内存存储。注意：这不适合生产。

1. 跳过Redis缓存测试

要跳过Redis相关测试，请设置以下环境变量：

   SKIP_REDIS_TESTS=true

或者在运行测试时：

   SKIP_REDIS_TESTS=true npm test

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

# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your_redis_password
REDIS_TLS=false
SESSION_SECRET=your_session_secret_here
SESSION_TTL=86400  # 24 hours in seconds

API终点

创建会话

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

{
  "userId": "user123",
  "data": {
    "role": "admin"
  },
  "ttl": 86400
}

获取会话

GET /api/sessions/:sessionId
Authorization: Bearer 

更新会话

PATCH /api/sessions/:sessionId
Authorization: Bearer 
Content-Type: application/json

{
  "data": {
    "role": "admin",
    "preferences": {}
  },
  "ttl": 86400
}

删除会话

DELETE /api/sessions/:sessionId
Authorization: Bearer 

验证会话

GET /api/sessions/:sessionId/validate
Authorization: Bearer 

使用会话中间件

要使用会话身份验证保护路由，请使用 sessionMiddleware:

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

// Apply to specific routes
app.get('/protected-route', sessionMiddleware(redisClient), (req, res) => {
  // Access session data
  const session = req.session;
  res.json({ message: 'Access granted', user: session.userId });
});

// Or apply to all routes
app.use(sessionMiddleware(redisClient));

会话数据结构

{
  "sessionId": "unique-session-id",
  "userId": "user123",
  "data": {
    // Custom session data
  },
  "expiresAt": "2025-05-25T12:00:00.000Z",
  "createdAt": "2025-05-24T12:00:00.000Z",
  "updatedAt": "2025-05-24T12:05:00.000Z"
}

最佳实践

1. 保护您的会话密钥：使用强大、唯一的密钥进行会话加密
2. 设置适当的TTL：设置会话TTL时平衡安全性和用户便利性
3. 验证会话：在处理敏感操作之前，始终验证会话
4. 处理会话错误：对会话相关操作实施适当的错误处理
5. 监控Redis：监控Redis服务器运行状况和性能指标

故障排除

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

会话存储选项

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

内存存储（开发默认）

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

Redis商店（推荐用于生产环境）

# Install Redis (macOS)
brew install redis

# Start Redis server (in a separate terminal)
redis-server

# In your .env file:
SESSION_STORE_TYPE=redis
REDIS_URL=redis://localhost:6379

安装

1. 克隆存储库：

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

1. 安装依赖项：

   npm install

1. 设置环境变量：

   cp .env.example .env
   # Edit .env with your configuration
   LOG_LEVEL=info

   # Advanced Configuration
   DUST_AGENT_IDS=agent1,agent2,agent3
   MAX_SESSIONS=100
   SESSION_TIMEOUT=3600

1. 构建项目：

   npm run build

1. 启动服务器：

   # For development
   npm run dev

   # For production
   npm start

设置和配置

环境变量

Claude桌面集成

要与Claude Desktop一起使用：

1. 全局安装MCP工具：

   npm install -g @modelcontextprotocol/tools

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

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

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

MCP工具参考

以下MCP工具可用于与粉尘剂交互：

dust_list_agents

列出配置的工作区中所有可用的除尘剂。

参数：

• includeDetails （boolean，可选）：是否包含详细的代理信息

例子：

{
  "includeDetails": true
}

dust_agent_query

向Dust代理发送查询。

参数：

• agentId （string，必填）：要查询的代理的ID
• query （string，必填）：要发送给代理的查询
• sessionId （字符串，可选）：用于继续对话的会话ID
• context （object，可选）：查询的其他上下文

例子：

{
  "agentId": "agent123",
  "query": "What is the weather today?",
  "sessionId": "session_456"
}

存储体系统

内存库系统为代理状态和配置提供持久存储：

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

______________________________________________________________________

开发者指南

项目结构

dust-mcp-server/
├── src/
│   ├── __tests__/           # Test files
│   │   ├── e2e/             # End-to-end tests
│   │   ├── integration/     # Integration tests
│   │   └── unit/            # Unit tests
│   ├── agents/              # Agent implementations
│   ├── api/                 # API routes and controllers
│   ├── middleware/          # Express middleware
│   ├── services/            # Business logic services
│   ├── tools/               # MCP tool implementations
│   ├── types/               # TypeScript type definitions
│   └── utils/               # Utility functions
├── memory-bank/             # Persistent storage for agent state
│   ├── activeContext.md     # Current state of active sessions
│   ├── decisionLog.md       # Log of agent decisions
│   ├── progress.md          # Task progress tracking
│   ├── systemPatterns.md    # Reusable interaction patterns
│   └── productContext.md    # Product-specific configurations
├── docs/                    # Documentation files
├── tests/                   # Additional test resources
├── .env.example             # Example environment variables
├── .eslintrc.json           # ESLint configuration
├── .gitignore               # Git ignore rules
├── jest.config.ts           # Jest test configuration
├── package.json             # Project dependencies and scripts
├── README.md                # This file
└── tsconfig.json            # TypeScript configuration

开发设置

1. 克隆存储库并安装依赖项：

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

1. 设置您的开发环境：

   # Install development dependencies
   npm install -D typescript ts-node ts-jest @types/jest @types/node

   # Set up pre-commit hooks
   npm run prepare

1. 配置您的环境：

   cp .env.example .env
   # Edit .env with your configuration

1. 启动开发服务器：

   npm run dev

测试

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

运行测试

# Run all tests
npm test

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run end-to-end tests
npm run test:e2e

# Run tests with coverage
npm run test:coverage

测试结构

• 单元测试：单独测试单个函数和类
• 集成测试：测试组件之间的相互作用
• E2E测试：测试完整的用户流

测试特性

• 外部服务的模拟实现
• 包含样本数据的测试数据库
• API请求/响应验证
• UI组件的快照测试

日志记录和调试

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

• error：导致应用程序失败的错误
• warn：潜在的有害情况
• info：一般应用程序流程信息
• debug：详细的调试信息
• silly：非常详细的调试信息

VS代码调试

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

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test:debug"],
      "port": 9229,
      "skipFiles": ["/**"]
    }
  ]
}

常见问题

1. TypeScript错误：运行 npm run lint:fix 自动修复常见问题
2. 测试失败：使用清除测试数据库 npm run test:reset
3. 依赖性问题：删除 node_modules 然后跑 npm install

API文档

API文档可在 docs 目录，可以使用以下命令生成：

npm run docs:generate

API使用OpenAPI（Swagger）进行文档记录，可以在 /api-docs 在开发模式下运行时。

部署

先决条件

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

生产建设

# Install production dependencies
npm ci --only=production

# Build the application
npm run build

# Start the server
NODE_ENV=production npm start

码头工人

# Build the Docker image
docker build -t dust-mcp-server .

# Run the container
docker run -p 3000:3000 --env-file .env dust-mcp-server

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关资源

• Dust.tt文件
• 模型上下文协议
• 克劳德桌面
• TypeScript文档
• Express.js文档
• Jest测试框架
• 温斯顿测井

运行服务器

您可以在两种不同的模式下运行MCP服务器：HTTP模式或STDIO模式。

HTTP模式

要在HTTP模式下运行服务器（适用于基于web的客户端）：

npm run build
npm start -- --http

服务器将在指定的端口上侦听 PORT 环境变量（默认值：3000）。

您可以通过以下网址与API进行交互： http://localhost:3000/api.

SSE活动

服务器支持通过服务器发送事件（SSE）进行实时事件流式传输。

• 连接到 http://localhost:3000/events 与SSE兼容的客户端一起接收服务器事件（例如，健康、代理更新）。
• 示例使用 curl:

  curl -N http://localhost:3000/events

STDIO模式

当您希望服务器通过标准输入/输出流而不是HTTP进行通信时，使用STDIO模式。这是Claude Desktop和其他通过STDIO通信的MCP客户端使用的模式。

要在STDIO模式下启动服务器：

# Start the server in STDIO mode
node build/dust.js

在STDIO模式下运行时：

• 服务器的设计不会向stdout产生任何输出，因为此通道是为MCP协议通信保留的
• 任何日志或错误消息都会被定向到logs目录和stderr
• 服务器立即准备好接受MCP客户端连接

停止服务器

要停止服务器，您可以在运行服务器的终端中使用Ctrl+C，或终止进程：

pkill -f "node.*dust-mcp-server"

架构图

flowchart TD
    subgraph Client["Client Layer"]
        A[Claude Desktop] -- "MCP Protocol" --> B[MCP Server]
    end

    subgraph Server["Dust MCP Server"]
        B --> C[Request Handler]
        C --> D[Auth Middleware]
        D --> E[Windsurf Rules Engine]
        E --> F[Tool Router]
        
        subgraph Tools["MCP Tools"]
            F --> G[dust_list_agents]
            F --> H[dust_agent_query]
            F --> I[dust_create_session]
            F --> J[dust_end_session]
            F --> K[dust_get_session]
            F --> L[dust_get_agent]
        end
        
        subgraph Services["Core Services"]
            M[DustApiService]  N[AgentService]
            N  O[SessionManager]
            O  P[MemoryBank]
        end
    end
    
    subgraph External["External Services"]
        Q[(Dust AI Platform)]
    end
    
    subgraph Memory["Memory Bank"]
        R[productContext.md]
        S[systemPatterns.md]
        T[activeContext.md]
        U[decisionLog.md]
        V[progress.md]
    end
    
    Tools --> Services
    Services --> Q
    Services --> Memory
    
    %% Styling
    classDef client fill:#e1f5fe,stroke:#01579b,color:#01579b
    classDef server fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef external fill:#f3e5f5,stroke:#4a148c,color:#4a148c
    classDef memory fill:#fff3e0,stroke:#e65100,color:#e65100
    
    class A,Client client
    class B,C,D,E,F,G,H,I,J,K,L,Server server
    class Q,External external
    class R,S,T,U,V,Memory memory

关键组件

1. 客户端层:

- Claude Desktop使用MCP协议与MCP服务器通信

1. MCP服务器:

- 请求处理器：处理传入的MCP请求 - 身份验证中间件：验证API密钥和权限 - 风浪规则引擎：强制执行特定于项目的规则和工作流 - 工具路由器：将请求路由到相应的MCP工具 - MCP工具：用于代理交互和会话管理的个人工具

1. 核心服务:

- DustApi服务：处理与Dust AI平台的通信 - 代理服务：管理代理生命周期和交互 - 会话管理器：维护会话状态和上下文 - 记忆库：使用内存库系统管理持久存储

1. 存储体:

- productContext.md：项目目标和高层架构 - systemPatterns.md：设计模式和实施细节 - activeContext.md：现状和最近的变化 - decisionLog.md：架构和实施决策 - progress.md：任务跟踪和里程碑

1. 外部服务:

- Dust AI平台：代理执行和处理的外部服务

使用MCP工具

此项目使用 MCP工具 用于测试和集成。以下是如何使用它们：

1. 全局安装MCP工具

npm install -g mcptools

1. 列出服务器中可用的工具

mcp tools node build/dust.js

1. 调用特定工具

mcp call dust_list_agents node build/dust.js --params '{"limit": 10}'

mcp call dust_agent_query node build/dust.js --params '{"query": "Give me a summary"}'

1. 将服务器添加到您的别名中

mcp alias add dust node build/dust.js
mcp alias list

1. 使用Claude Desktop进行配置

mcp configs set claude-desktop dust /path/to/node /path/to/dust-mcp-server/build/dust.js

MCP工具参考

服务器提供以下MCP工具用于与Dust.tt代理交互：

dust_list_agents

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

参数：

• query （字符串，可选）：按名称或描述筛选代理
• view （字符串，可选）：筛选代理的视图类型
• limit （number，可选）：要返回的最大代理数（默认值：10）

请求示例：

mcp call dust_list_agents node build/dust.js --params '{"limit": 10}'

答复：

interface AgentDescriptor {
  id: string;
  name: string;
  description: string;
  capabilities: string[];
  isActive?: boolean;
  lastUsed?: string;
}

dust_agent_query

在会话中查询除尘剂。

参数：

• agentId （string，必填）：要查询的代理的ID
• message （string，必填）：要发送给代理的消息
• files （数组\，可选）：要包含在消息中的文件
• sessionId （字符串，可选）：现有会话ID以继续对话

请求示例：

{
  "agentId": "agent_123",
  "message": "What's the weather like?",
  "files": [
    {
      "name": "location.txt",
      "content": "San Francisco"
    }
  ]
}

答复：

interface DustMessageResponse {
  response: string;
  context: Record;
}

dust_create_session

使用Dust代理创建新会话。

参数：

• agentId （string，必填）：用于创建会话的代理的ID
• context （object，可选）：会话的初始上下文

请求示例：

mcp call dust_create_session node build/dust.js --params '{
  "agentId": "agent_123",
  "context": {
    "userPreferences": {
      "language": "en-US"
    }
  }
}'

答复：

interface SessionDescriptor {
  id: string;
  agentId: string;
  context: Record;
  isActive: boolean;
  createdAt: string;
  lastActivity: string;
}

dust_end_session

结束活动会话。

参数：

• sessionId （string，必填）：要结束的会话的ID

请求示例：

mcp call dust_end_session node build/dust.js --params '{"sessionId": "sess_123"}'

dust_get_session

获取特定会话的详细信息。

参数：

• sessionId （string，必填）：要检索的会话的ID

请求示例：

mcp call dust_get_session node build/dust.js --params '{"sessionId": "sess_123"}'

dust_get_agent

获取特定代理的详细信息。

参数：

• agentId （string，必填）：要检索的代理的ID

请求示例：

mcp call dust_get_agent node build/dust.js --params '{"agentId": "agent_123"}'

答复：

interface AgentDescriptor {
  id: string;
  name: string;
  description: string;
  capabilities: string[];
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
  configuration: Record;
}

项目结构

root/
├── src/                # Main source code
│   ├── services/       # Dust API integration layer
│   └── tools/          # (Deprecated) MCP tool implementations
├── build/              # Compiled JavaScript output
├── logs/               # Application and debug logs
│   └── debug/
├── memory-bank/        # Project context and memory files
├── docs/               # Documentation, images, and moved test/demo scripts
├── .env                # Environment configuration (not committed)
├── .env.example        # Example environment file
├── package.json        # Project manifest
└── README.md           # Main documentation (this file)

测试

测试特性

测试套件包括以下功能：

• 嘲笑：测试使用Jest mocking将MCP方法与实际API调用隔离开来
• 测试数据：中提供了示例代理配置和响应 test/fixtures/
• 参数验证：测试验证参数是否正确验证
• 全覆盖：测试涵盖所有参数和响应格式

运行测试

您可以使用npm脚本运行测试：

# Install dependencies first (if not already installed)
npm install

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

手动测试

您还可以使用中的脚本手动测试MCP功能 docs/:

# Test MCP tools functionality
node docs/test-mcp-tools.js

# Test STDIO transport
node docs/test-stdio.js

调试

VS代码调试

该项目包括服务器和测试的VS代码调试配置。您可以使用这些配置直接从VS Code调试应用程序。

可用的调试配置

1. 调试服务器（HTTP）

- 在调试模式下启动服务器并自动重新加载 - 附加到正在运行的Node.js进程 - 支持断点和步骤调试

1. 调试测试

- 在调试模式下运行测试套件 - 支持测试文件中的断点 - 显示详细的测试输出

1. 调试当前测试文件

- 运行当前打开的带有调试器的测试文件 - 有助于专注于特定的测试用例 - 支持测试文件和源代码中的断点

1. 调试所有测试

- 使用附加的调试器运行项目中的所有测试 - 可用于调试测试套件或集成测试 - 支持测试文件和源代码中的断点

如何使用

1. 在VS Code中打开项目
2. 通过单击行号旁边的空白处，在代码中设置断点
3. 打开运行和调试视图（Ctrl+Shift+D或Cmd+Shift+D）
4. 从下拉列表中选择调试配置
5. 点击绿色播放按钮或按F5开始调试

日志文件

日志存储在 logs/ 目录：

• app-YYYY-MM-DD.log：应用程序日志
• server-YYYY-MM-DD.log：服务器日志
• test-mcp-YYYY-MM-DD.log：MCP工具测试日志

发展

# Run in development mode with auto-reload
npm run dev

# Build the project
npm run build

API文档

有关Dust API的更多信息，请参阅官方文档：

• Dust API文件
• 代理配置
• 交谈
• 消息

许可证

麻省理工学院