灰尘MCP服务器

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

特性

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

配置

Redis配置

环境变量

将这些变量添加到您的 .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

测试连接

您可以通过以下方式测试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);"

禁用Redis进行开发

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

   REDIS_ENABLED=false

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

跳过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"
}

最佳实践

保护您的会话密钥：使用强大、唯一的密钥进行会话加密
设置适当的TTL：设置会话TTL时平衡安全性和用户便利性
验证会话：在处理敏感操作之前，始终验证会话
处理会话错误：对会话相关操作实施适当的错误处理
监控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

安装

克隆存储库：

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

安装依赖项：

   npm install

设置环境变量：

   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

构建项目：

   npm run build

启动服务器：

   # For development
   npm run dev

   # For production
   npm start

设置和配置

环境变量

变量	必填	描述	默认值
`DUST_API_KEY`	是	您的Dust.tt API密钥	-
`DUST_WORKSPACE_ID`	是	您的Dust.tt工作区ID	-
`PORT`	无	运行服务器的端口	`3000`
`NODE_ENV`	否	节点环境(`development`/`production`)	`development`
`LOG_LEVEL`	否	日志记录级别(`error`, `warn`, `info`, `debug`)	`info`
`DUST_AGENT_IDS`	否	要加载的以逗号分隔的代理ID列表	-
`MAX_SESSIONS`	否	最大并发会话数	`100`
`SESSION_TIMEOUT`	否	会话超时（秒）	`3600` （1小时）

Claude桌面集成

要与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_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

开发设置

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

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

设置您的开发环境：

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

   # Set up pre-commit hooks
   npm run prepare

配置您的环境：

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

启动开发服务器：

   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": ["/**"]
    }
  ]
}

常见问题

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（可选）

生产建设

# 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

贡献

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

许可证

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

架构图

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

关键组件

客户端层:

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

MCP服务器:

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

核心服务:

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

存储体:

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

外部服务:

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

使用MCP工具

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

全局安装MCP工具

npm install -g mcptools

列出服务器中可用的工具

mcp tools node build/dust.js

调用特定工具

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"}'

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

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

使用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调试应用程序。

可用的调试配置

调试服务器（HTTP）

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

调试测试

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

调试当前测试文件

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

调试所有测试

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

如何使用

在VS Code中打开项目
通过单击行号旁边的空白处，在代码中设置断点
打开运行和调试视图（Ctrl+Shift+D或Cmd+Shift+D）
从下拉列表中选择调试配置
点击绿色播放按钮或按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 MCP Server (Ma3u)

快速接入

详细介绍

灰尘MCP服务器

目录

用户指南

概述

用户旅程

1.初始设置和代理发现

2.工作空间配置

3.多智能体协作

4.高级交互

5.报告和分析

快速开始

先决条件

会话管理

特性

配置

Redis配置

API终点

创建会话

获取会话

更新会话

删除会话

验证会话

使用会话中间件

会话数据结构

最佳实践

故障排除

会话存储选项

内存存储（开发默认）

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

安装

设置和配置

环境变量

Claude桌面集成

MCP工具参考

dust_list_agents

dust_agent_query

存储体系统

开发者指南

项目结构

开发设置

测试

运行测试

测试结构

测试特性

日志记录和调试

VS代码调试

常见问题

API文档

部署

先决条件

生产建设

码头工人

贡献

许可证

相关资源

运行服务器

HTTP模式

SSE活动

STDIO模式

停止服务器

架构图

关键组件

使用MCP工具

MCP工具参考

dust_list_agents

dust_agent_query

dust_create_session

dust_end_session

dust_get_session

dust_get_agent

项目结构

测试

测试特性

运行测试

手动测试

调试

VS代码调试

`dust_list_agents`

`dust_agent_query`

`dust_list_agents`

`dust_agent_query`

`dust_create_session`

`dust_end_session`

`dust_get_session`

`dust_get_agent`