--- slug: "dust-mcp服务器" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/ma3u/mcp-server-dust-py@main/README.md" repo: "https://github.com/ma3u/mcp-server-dust-py" source_file: "README.md" branch: "main" --- # MCP Server for Dust Agent Integration A custom MCP (Multi-Cloud Provider) server that connects to the Dust.tt agent platform via HTTP calls. This server exposes the capabilities of Dust AI agents through the MCP interface. ## Table of Contents - [MCP Server for Dust Agent Integration](#mcp-server-for-dust-agent-integration) - [Table of Contents](#table-of-contents) - [Features](#features) - [Project Structure](#project-structure) - [Documentation](#documentation) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configuration](#configuration) - [Dust Agent Setup](#dust-agent-setup) - [MCP Server Settings](#mcp-server-settings) - [Running the Server](#running-the-server) - [Claude Desktop Integration](#claude-desktop-integration) - [1. Installation](#1-installation) - [2. Initial Setup](#2-initial-setup) - [3. Integration with MCP Server](#3-integration-with-mcp-server) - [4. Applying Configuration Changes](#4-applying-configuration-changes) - [5. Testing in Claude Desktop](#5-testing-in-claude-desktop) - [Troubleshooting](#troubleshooting) - [Dust.tt API Workflow](#dusttt-api-workflow) - [1. Create a New Conversation](#1-create-a-new-conversation) - [2. Send a Message to the Conversation](#2-send-a-message-to-the-conversation) - [3. Retrieve Messages from the Conversation](#3-retrieve-messages-from-the-conversation) - [Important Notes About the API](#important-notes-about-the-api) - [Error Handling](#error-handling) - [Contributing](#contributing) ## Features - Connect to Dust.tt AI agents via API - Systems Thinking agent integration with cognitive neuroscience and problem-solving capabilities - RAG (Retrieval Augmented Generation) support - Web navigation capability - Simplified MCP tool interface - Modular code structure for better maintainability - Externalized configuration and API client classes ## Project Structure The project follows a modular structure for improved maintainability: - `server.py`: Main server implementation that registers tools and handles MCP functionality - `config.py`: Contains the `DustAgentConfig` class for managing configuration settings - `api_client.py`: Contains the `DustAPIClient` class for handling API interactions with Dust.tt - `.env`: Environment variables file (not committed to version control) - `.env.example`: Template for environment variables - `docs.md`: Comprehensive documentation of the project architecture and API ## Documentation For detailed information about the architecture, API, and troubleshooting, please refer to the [comprehensive documentation](https://github.com/ma3u/mcp-server-dust-py/blob/HEAD/docs.md). ## Prerequisites - Python 3.10 or higher - `pip` package manager - A Dust.tt account with API access - An existing Dust agent configuration ## Installation 1. **Clone this repository:** ```bash git clone https://github.com/Ma3u/mcp-server-dust.git cd mcp-server-dust ``` 2. **Create and activate a virtual environment:** ```bash python3 -m venv .venv # On macOS/Linux source .venv/bin/activate # On Windows .venv\Scripts\activate ``` 3. **Install required dependencies:** ```bash pip install --upgrade pip pip install mcp requests python-dotenv ``` ## Configuration ### Dust Agent Setup Create a `.env` file in the root directory with your configuration (you can copy from `.env.example` and modify): ``` # 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 ``` > **Security Note:** Make sure to add `.env` to your `.gitignore` file to prevent committing sensitive information. ### MCP Server Settings The server configuration parameters are now managed by the `DustAgentConfig` class in `config.py`. Parameters are loaded from environment variables with the following defaults: ```python # 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 ``` ## Running the Server To start the MCP server: ```bash python server.py ``` You should see output similar to: ``` Starting MCP server 'Dust MCP Server' on 127.0.0.1:5001 Connected to Dust agent 'SystemsThinking' (ID: 8x9nuXXXX) ``` The server will run until interrupted with Ctrl+C. ## Claude Desktop Integration To configure Claude Desktop for use with this MCP server: ### 1. Installation - Download Claude Desktop from the [official Anthropic website](https://www.anthropic.com/claude/download) - Install the application following the on-screen instructions for your OS ### 2. Initial Setup - Launch the app after installation - Sign in with your Anthropic account (free account is sufficient) ### 3. Integration with MCP Server - Launch Claude Desktop and go to Settings - Select the "Developer" tab on the left sidebar - Click the "Edit Config" button at the bottom of the screen - Add your Dust MCP server to the configuration by including it in the `mcpServers` array: ```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 } } } ``` > **Note:** If there are existing entries in the `mcpServers` array, add your configuration as a new item. ### 4. Applying Configuration Changes - After making changes to your MCP server configuration: - For Claude Desktop, quit the application completely - Relaunch Claude Desktop for the new configuration to take effect - Verify the connection by checking if your server appears in the list in the Developer settings ### 5. Testing in Claude Desktop Type the following in Claude Desktop to test your integration: ``` Use Systemsthinking Agent to explain MCP Protocol. ``` ![alt text](https://github.com/ma3u/mcp-server-dust-py/raw/HEAD/image-1.png) ## Troubleshooting View the log file for the Dust MCP server in Claude Desktop: ```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 Workflow The MCP Server interfaces with Dust.tt's API through a multi-step workflow. Each Claude request that uses the Dust agent follows this process: ![Dust API Workflow Diagram](https://github.com/ma3u/mcp-server-dust-py/raw/HEAD/image.png) ### 1. Create a New Conversation First, the server creates a new conversation with the Dust agent: ```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" }' ``` This returns a conversation ID that's used in subsequent requests: ```json { "conversation": { "sId": "DhvpbhW74S", "title": "Systems Thinking Conversation", "created_at": 1742923287427 } } ``` ### 2. Send a Message to the Conversation Next, the server sends the user's query as a message to the conversation: ```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" } }' ``` The response includes the message 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. Retrieve Messages from the Conversation Finally, the server retrieves the agent's response. This requires a specific format for the message retrieval request: ```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" } }' ``` The response contains all messages in the conversation, including the agent's response: ```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" } ] } ``` ### Important Notes About the API - The message retrieval endpoint serves a dual purpose - it can be used to create new messages OR retrieve conversation history - For message retrieval, a properly structured payload is required even though it's essentially a GET operation - The content field is required and must be at least one character (we use "RETRIEVAL_QUERY" as a placeholder) - The mentions and context fields must be structured correctly as shown above - You need to poll this endpoint multiple times until the agent's response appears ### Error Handling Common errors when working with the Dust.tt API: - **400 Bad Request**: Often indicates malformed JSON or missing required fields in your request payload - **401 Unauthorized**: Check your API key - **404 Not Found**: Verify your workspace ID and conversation ID - **429 Too Many Requests**: You've exceeded API rate limits For debugging purposes, the server logs all API requests in curl format so you can reproduce and troubleshoot them manually. ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.