Dust MCP Server

Dust MCP Server

🚀 A TypeScript-based MCP (Model Context Protocol) Server with advanced agent conversation features.

GitHub Repository: dust-mcp-server-postman-railway

User Manual

Features

• ✅ TypeScript-powered MCP server
• 🏗️ Modern ES2022+ JavaScript features
• 🔍 Built-in API documentation
• 🧪 Comprehensive test suite with Jest
• 🛠️ Developer-friendly tooling
• 🔄 Hot-reloading development server
• 📦 Module aliases for clean imports
• 🔒 Environment-based configuration
• 🧩 Extensible architecture

🚀 Getting Started

⚙️ Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18+ required, v20+ recommended)
• npm (included with Node.js)
• TypeScript (included as a dev dependency)
• Git (for version control)

🛠️ Installation

1. Clone the repository

   git clone https://github.com/ma3u/dust-mcp-server-postman-railway.git
   cd dust-mcp-server-postman-railway
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   Create a .env file in the root directory with the following variables:

   PORT=3000
   NODE_ENV=development
   DEFAULT_WORKSPACE_ID=default
   WORKSPACE_DEFAULT_API_KEY=your_api_key_here
   WORKSPACE_DEFAULT_NAME=Default Workspace
   

🏗️ Development

1. Start the development server

   npm run dev
   

   This will start the server with hot-reloading enabled.

2. Build for production

   npm run build
   npm start
   

3. Run tests

   npm test        # Run all tests
   npm run test:watch  # Run tests in watch mode
   npm run test:coverage  # Generate test coverage report
   

4. Linting and Formatting

   npm run lint     # Check for linting errors
   npm run lint:fix # Automatically fix linting issues
   npm run format   # Format code using Prettier
   

Developer Manual

Architecture

[Architecture overview]

Agent Conversation Flow

The following diagram illustrates the conversation flow between MCP Client, MCP Server, and Dust with session management:

sequenceDiagram
    participant User
    participant MCPClient as MCP Client
    participant MCPServer as MCP Server
    participant SessionMgr as Session Manager
    participant ConvMgr as Conversation Manager
    participant Dust as Dust Service

    %% Session Initialization
    User->>MCPClient: Start New Session
    MCPClient->>MCPServer: POST /api/sessions
    MCPServer->>SessionMgr: createSession()
    SessionMgr-->>MCPServer: {sessionId, status: 'active'}
    MCPServer->>ConvMgr: new Conversation(sessionId)
    ConvMgr-->>MCPServer: {conversationId, state: 'initializing'}
    MCPServer-->>MCPClient: {sessionId, conversationId, status: 'active'}
    MCPClient-->>User: Session Ready

    %% Message Flow
    loop While Session Active
        User->>MCPClient: Send Message
        MCPClient->>MCPServer: POST /api/conversations/{conversationId}/messages
        MCPServer->>ConvMgr: processMessage(message)
        alt Has Files
            ConvMgr->>FileUploadHandler: handleUpload(files)
            FileUploadHandler-->>ConvMgr: {fileIds, paths}
        end
        ConvMgr->>Dust: forwardMessage(conversationId, message, files)
        Dust-->>ConvMgr: {response, metadata}
        ConvMgr->>ConversationHistory: addMessage(message, response)
        MCPServer-->>MCPClient: {response, state, metadata}
        MCPClient-->>User: Display Response
        
        %% Timeout Handling
        alt Idle Timeout Reached
            ConvMgr->>ConvMgr: handleIdleTimeout()
            ConvMgr->>SessionMgr: updateSession(sessionId, {state: 'idle'})
            SessionMgr-->>ConvMgr: {status: 'updated'}
            ConvMgr-->>MCPServer: {event: 'stateChange', state: 'idle'}
            MCPServer-->>MCPClient: {event: 'sessionIdle'}
        end
    end

    %% Session Termination
    User->>MCPClient: End Session
    MCPClient->>MCPServer: DELETE /api/sessions/{sessionId}
    MCPServer->>SessionMgr: deleteSession(sessionId)
    SessionMgr->>ConvMgr: destroy()
    ConvMgr->>ConversationHistory: clear()
    ConvMgr-->>SessionMgr: {status: 'destroyed'}
    SessionMgr-->>MCPServer: {status: 'deleted'}
    MCPServer-->>MCPClient: {status: 'session_ended'}
    MC