{"id":49003179,"url":"https://github.com/ma3u/dust-mcp-server","last_synced_at":"2026-04-18T19:07:31.172Z","repository":{"id":287070935,"uuid":"963208513","full_name":"ma3u/dust-mcp-server","owner":"ma3u","description":"A TypeScript MCP server bridging Dust.tt agents with external tools via JSON-RPC, SSE, and secure API integration. Implements MCP specs/sdk  for Claude Desktop compatibility, featuring session management, real-time streaming, and Dust API connectivity.  ","archived":false,"fork":false,"pushed_at":"2025-05-28T08:29:55.000Z","size":2453,"stargazers_count":5,"open_issues_count":22,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-15T14:38:59.672Z","etag":null,"topics":["agentic","ai","aiagent","dust","mcp","mcpserver"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ma3u.png","metadata":{"files":{"readme":"README.MD","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-09T10:22:59.000Z","updated_at":"2025-10-27T17:28:22.000Z","dependencies_parsed_at":"2025-04-30T20:31:58.268Z","dependency_job_id":"79a11c19-0fb8-494c-b10d-2af1a9120a54","html_url":"https://github.com/ma3u/dust-mcp-server","commit_stats":null,"previous_names":["ma3u/dust-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ma3u/dust-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma3u%2Fdust-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma3u%2Fdust-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma3u%2Fdust-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma3u%2Fdust-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ma3u","download_url":"https://codeload.github.com/ma3u/dust-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma3u%2Fdust-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31980845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai","aiagent","dust","mcp","mcpserver"],"created_at":"2026-04-18T19:07:29.738Z","updated_at":"2026-04-18T19:07:31.152Z","avatar_url":"https://github.com/ma3u.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dust MCP Server\n\nA Model Context Protocol (MCP) server for Dust.tt agents, designed for seamless integration with Claude Desktop via STDIO. Provides robust agent querying, listing, and configuration tools.\n\n## Table of Contents\n- [User Guide](#user-guide)\n  - [Overview](#overview)\n  - [User Journey](#user-journey)\n  - [Quick Start](#quick-start)\n  - [Setup and Configuration](#setup-and-configuration)\n  - [MCP Tools Reference](#mcp-tools-reference)\n  - [Memory Bank System](#memory-bank-system)\n- [Developer Guide](#developer-guide)\n  - [Project Structure](#project-structure)\n  - [Development Setup](#development-setup)\n  - [Testing](#testing)\n  - [Logging and Debugging](#logging-and-debugging)\n  - [API Documentation](#api-documentation)\n  - [Deployment](#deployment)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Related Resources](#related-resources)\n\n# User Guide\n\n## Overview\n\nThe Dust MCP Server provides a standardized interface for interacting with Dust.tt agents through the Model Context Protocol (MCP). It enables seamless integration with Claude Desktop and other MCP-compatible clients, offering features like agent discovery, session management, and message handling.\n\n## User Journey\n\nThis section outlines the typical user journey when interacting with the Dust MCP Server and its integrated agents.\n\n### 1. Initial Setup and Agent Discovery\n\n- **Entry Point**: User logs into the Dust platform\n- **Agent Discovery**:\n  - Views available agents in the Agent Marketplace\n  - Filters agents by category (e.g., Data Analysis, Content Creation, Research)\n  - Reviews agent capabilities, ratings, and documentation\n- **Agent Selection**:\n  - Selects multiple agents based on task requirements\n  - Creates a new workspace or selects existing one\n\n### 2. Workspace Configuration\n\n- **Layout Setup**:\n  - Arranges agent panels in a custom layout\n  - Configures agent-specific settings and permissions\n- **Context Sharing**:\n  - Enables/disables context sharing between agents\n  - Sets up data flow between agents\n- **File Management**:\n  - Uploads files to shared workspace\n  - Organizes files in project folders\n  - Sets file access permissions per agent\n\n### 3. Multi-Agent Collaboration\n\n- **Conversation Flow**:\n  - Initiates chat with primary agent\n  - @mentions other agents to bring them into conversation\n  - Views inter-agent communication in dedicated threads\n- **Task Delegation**:\n  - Assigns specific tasks to specialized agents\n  - Monitors task progress across agents\n  - Views task dependencies and status\n- **File Collaboration**:\n  - Shares files with specific agents\n  - Tracks file access and modifications\n  - Views version history and agent contributions\n\n### 4. Advanced Interactions\n\n- **Agent Chaining**:\n  - Creates workflows by chaining agents\n  - Sets up conditional logic for agent handoffs\n  - Configures automatic triggers between agents\n- **Context Management**:\n  - Reviews and edits shared context\n  - Resolves context conflicts between agents\n  - Saves context snapshots for future reference\n\n### 5. Reporting and Analysis\n\n- **Report Generation**:\n  - Requests reports from analysis agents\n  - Customizes report templates and parameters\n  - Exports reports in multiple formats (PDF, Markdown, HTML)\n- **Insight Visualization**:\n  - Views interactive dashboards\n  - Filters and drills down into data visualizations\n  - Compares outputs from different agents\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js v18 or later\n- npm 9.x or later\n- A Dust.tt account with API access\n- Redis server (for session management)\n\n## Session Management\n\nThe Dust MCP Server includes a robust session management system using Redis for persistence. This allows for secure and scalable session handling across multiple instances of the server.\n\n### Features\n\n- **Redis-based Session Storage**: Secure and scalable session storage\n- **Session Expiration**: Automatic cleanup of expired sessions\n- **Distributed Support**: Works in distributed environments\n- **Session Data**: Store arbitrary data with each session\n- **API Endpoints**: RESTful API for session management\n\n### Configuration\n\n#### Redis Configuration\n\n1. **Environment Variables**\n   Add these variables to your `.env` file:\n\n   ```env\n   # Redis Configuration\n   REDIS_ENABLED=true  # Set to false to disable Redis (uses in-memory store)\n   REDIS_URL=redis://localhost:6379\n   REDIS_PASSWORD=  # Leave empty if no password is set\n   REDIS_TLS=false  # Set to true for secure connections\n   SESSION_SECRET=your_session_secret_here\n   SESSION_TTL=86400  # 24 hours in seconds\n   ```\n\n2. **Test Connection**\n\n   You can test your Redis connection with:\n\n   ```bash\n   node -e \"const { createClient } = require('redis'); (async () =\u003e { const client = createClient({ url: process.env.REDIS_URL }); await client.connect(); console.log('Redis connected successfully'); await client.quit(); })().catch(console.error);\"\n   ```\n\n3. **Disabling Redis for Development**\n\n   If you want to run the server without Redis for development:\n\n   ```env\n   REDIS_ENABLED=false\n   ```\n\n   This will use an in-memory store instead. Note: This is not suitable for production.\n\n4. **Skipping Redis Cache Tests**\n\n   To skip Redis-related tests, set the following environment variable:\n\n   ```bash\n   SKIP_REDIS_TESTS=true\n   ```\n\n   Or when running tests:\n\n   ```bash\n   SKIP_REDIS_TESTS=true npm test\n   ```\n\nAdd these environment variables to your `.env` file:\n\n```\n# Redis Configuration\nREDIS_URL=redis://localhost:6379\nREDIS_PASSWORD=your_redis_password\nREDIS_TLS=false\nSESSION_SECRET=your_session_secret_here\nSESSION_TTL=86400  # 24 hours in seconds\n```\n\n### API Endpoints\n\n#### Create a Session\n\n```http\nPOST /api/sessions\nContent-Type: application/json\n\n{\n  \"userId\": \"user123\",\n  \"data\": {\n    \"role\": \"admin\"\n  },\n  \"ttl\": 86400\n}\n```\n\n#### Get Session\n\n```http\nGET /api/sessions/:sessionId\nAuthorization: Bearer \u003csession_token\u003e\n```\n\n#### Update Session\n\n```http\nPATCH /api/sessions/:sessionId\nAuthorization: Bearer \u003csession_token\u003e\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"role\": \"admin\",\n    \"preferences\": {}\n  },\n  \"ttl\": 86400\n}\n```\n\n#### Delete Session\n\n```http\nDELETE /api/sessions/:sessionId\nAuthorization: Bearer \u003csession_token\u003e\n```\n\n#### Validate Session\n\n```http\nGET /api/sessions/:sessionId/validate\nAuthorization: Bearer \u003csession_token\u003e\n```\n\n### Using Session Middleware\n\nTo protect routes with session authentication, use the `sessionMiddleware`:\n\n```typescript\nimport { sessionMiddleware } from './session/routes/sessionRoutes';\nimport { redisClient } from './config/redis';\n\n// Apply to specific routes\napp.get('/protected-route', sessionMiddleware(redisClient), (req, res) =\u003e {\n  // Access session data\n  const session = req.session;\n  res.json({ message: 'Access granted', user: session.userId });\n});\n\n// Or apply to all routes\napp.use(sessionMiddleware(redisClient));\n```\n\n### Session Data Structure\n\n```typescript\n{\n  \"sessionId\": \"unique-session-id\",\n  \"userId\": \"user123\",\n  \"data\": {\n    // Custom session data\n  },\n  \"expiresAt\": \"2025-05-25T12:00:00.000Z\",\n  \"createdAt\": \"2025-05-24T12:00:00.000Z\",\n  \"updatedAt\": \"2025-05-24T12:05:00.000Z\"\n}\n```\n\n### Best Practices\n\n1. **Secure Your Session Secret**: Use a strong, unique secret for session encryption\n2. **Set Appropriate TTL**: Balance security and user convenience when setting session TTL\n3. **Validate Sessions**: Always validate sessions before processing sensitive operations\n4. **Handle Session Errors**: Implement proper error handling for session-related operations\n5. **Monitor Redis**: Monitor Redis server health and performance metrics\n\n### Troubleshooting\n\n- **Connection Issues**: Verify Redis server is running and accessible\n- **Session Expiry**: Check if sessions are expiring too quickly by adjusting TTL\n- **Memory Usage**: Monitor Redis memory usage for large session data\n- **Logs**: Check server logs for session-related errors\n\n### Session Storage Options\n\nThe server supports different session storage backends:\n\n#### In-Memory Store (Default for Development)\n\n- No additional setup required\n- Sessions are lost on server restart\n- Perfect for local development and testing\n\n#### Redis Store (Recommended for Production)\n\n```bash\n# Install Redis (macOS)\nbrew install redis\n\n# Start Redis server (in a separate terminal)\nredis-server\n\n# In your .env file:\nSESSION_STORE_TYPE=redis\nREDIS_URL=redis://localhost:6379\n```\n\n### Installation\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/Ma3u/dust-mcp-server.git\n   cd dust-mcp-server\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   npm install\n   ```\n\n3. Set up environment variables:\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration\n   LOG_LEVEL=info\n   \n   # Advanced Configuration\n   DUST_AGENT_IDS=agent1,agent2,agent3\n   MAX_SESSIONS=100\n   SESSION_TIMEOUT=3600\n   ```\n\n4. Build the project:\n\n   ```bash\n   npm run build\n   ```\n\n5. Start the server:\n\n   ```bash\n   # For development\n   npm run dev\n   \n   # For production\n   npm start\n   ```\n\n## Setup and Configuration\n\n### Environment Variables\n\n| Variable | Required | Description | Default |\n|----------|----------|-------------|---------|\n| `DUST_API_KEY` | Yes | Your Dust.tt API key | - |\n| `DUST_WORKSPACE_ID` | Yes | Your Dust.tt workspace ID | - |\n| `PORT` | No | Port to run the server on | `3000` |\n| `NODE_ENV` | No | Node environment (`development`/`production`) | `development` |\n| `LOG_LEVEL` | No | Logging level (`error`, `warn`, `info`, `debug`) | `info` |\n| `DUST_AGENT_IDS` | No | Comma-separated list of agent IDs to load | - |\n| `MAX_SESSIONS` | No | Maximum number of concurrent sessions | `100` |\n| `SESSION_TIMEOUT` | No | Session timeout in seconds | `3600` (1 hour) |\n\n### Claude Desktop Integration\n\nTo use with Claude Desktop:\n\n1. Install MCP Tools globally:\n   ```bash\n   npm install -g @modelcontextprotocol/tools\n   ```\n\n2. Configure Claude Desktop to use your MCP server:\n   ```bash\n   mcp configs set claude-desktop dust $(which node) $(pwd)/build/dust.js\n   ```\n\n3. Restart Claude Desktop and start interacting with your Dust agents.\n\n## MCP Tools Reference\n\nThe following MCP tools are available for interacting with Dust agents:\n\n### `dust_list_agents`\n\nList all available Dust agents in the configured workspace.\n\n**Parameters:**\n\n- `includeDetails` (boolean, optional): Whether to include detailed agent information\n\n**Example:**\n\n```json\n{\n  \"includeDetails\": true\n}\n```\n\n### `dust_agent_query`\n\nSend a query to a Dust agent.\n\n**Parameters:**\n\n- `agentId` (string, required): The ID of the agent to query\n- `query` (string, required): The query to send to the agent\n- `sessionId` (string, optional): Session ID for continuing a conversation\n- `context` (object, optional): Additional context for the query\n\n**Example:**\n\n```json\n{\n  \"agentId\": \"agent123\",\n  \"query\": \"What is the weather today?\",\n  \"sessionId\": \"session_456\"\n}\n```\n\n## Memory Bank System\n\nThe Memory Bank system provides persistent storage for agent state and configuration:\n\n- **Active Context**: Tracks the current state of all active agent sessions\n- **Decision Log**: Records all agent decisions and actions\n- **Progress Tracking**: Monitors task progress and completion status\n- **System Patterns**: Defines reusable interaction patterns\n- **Product Context**: Stores product-specific configurations and data\n\n---\n\n# Developer Guide\n\n## Project Structure\n\n```text\ndust-mcp-server/\n├── src/\n│   ├── __tests__/           # Test files\n│   │   ├── e2e/             # End-to-end tests\n│   │   ├── integration/     # Integration tests\n│   │   └── unit/            # Unit tests\n│   ├── agents/              # Agent implementations\n│   ├── api/                 # API routes and controllers\n│   ├── middleware/          # Express middleware\n│   ├── services/            # Business logic services\n│   ├── tools/               # MCP tool implementations\n│   ├── types/               # TypeScript type definitions\n│   └── utils/               # Utility functions\n├── memory-bank/             # Persistent storage for agent state\n│   ├── activeContext.md     # Current state of active sessions\n│   ├── decisionLog.md       # Log of agent decisions\n│   ├── progress.md          # Task progress tracking\n│   ├── systemPatterns.md    # Reusable interaction patterns\n│   └── productContext.md    # Product-specific configurations\n├── docs/                    # Documentation files\n├── tests/                   # Additional test resources\n├── .env.example             # Example environment variables\n├── .eslintrc.json           # ESLint configuration\n├── .gitignore               # Git ignore rules\n├── jest.config.ts           # Jest test configuration\n├── package.json             # Project dependencies and scripts\n├── README.md                # This file\n└── tsconfig.json            # TypeScript configuration\n```\n\n## Development Setup\n\n1. Clone the repository and install dependencies:\n\n   ```bash\n   git clone https://github.com/Ma3u/dust-mcp-server.git\n   cd dust-mcp-server\n   npm install\n   ```\n\n2. Set up your development environment:\n\n   ```bash\n   # Install development dependencies\n   npm install -D typescript ts-node ts-jest @types/jest @types/node\n   \n   # Set up pre-commit hooks\n   npm run prepare\n   ```\n\n3. Configure your environment:\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration\n   ```\n\n4. Start the development server:\n\n   ```bash\n   npm run dev\n   ```\n\n## Testing\n\nThe project includes a comprehensive test suite:\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run unit tests\nnpm run test:unit\n\n# Run integration tests\nnpm run test:integration\n\n# Run end-to-end tests\nnpm run test:e2e\n\n# Run tests with coverage\nnpm run test:coverage\n```\n\n### Test Structure\n\n- **Unit Tests**: Test individual functions and classes in isolation\n- **Integration Tests**: Test interactions between components\n- **E2E Tests**: Test complete user flows\n\n### Test Features\n\n- Mock implementations for external services\n- Test database with sample data\n- API request/response validation\n- Snapshot testing for UI components\n\n## Logging and Debugging\n\nThe application uses Winston for logging with the following log levels:\n\n- `error`: Errors that cause the application to fail\n- `warn`: Potentially harmful situations\n- `info`: General application flow information\n- `debug`: Detailed debugging information\n- `silly`: Very detailed debugging information\n\n### Debugging in VS Code\n\nAdd this configuration to your `.vscode/launch.json`:\n\n```json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    {\n      \"type\": \"node\",\n      \"request\": \"launch\",\n      \"name\": \"Debug Tests\",\n      \"runtimeExecutable\": \"npm\",\n      \"runtimeArgs\": [\"run\", \"test:debug\"],\n      \"port\": 9229,\n      \"skipFiles\": [\"\u003cnode_internals\u003e/**\"]\n    }\n  ]\n}\n```\n\n### Common Issues\n\n1. **TypeScript Errors**: Run `npm run lint:fix` to automatically fix common issues\n2. **Test Failures**: Clear the test database with `npm run test:reset`\n3. **Dependency Issues**: Delete `node_modules` and run `npm install`\n\n## API Documentation\n\nAPI documentation is available in the `docs` directory and can be generated using:\n\n```bash\nnpm run docs:generate\n```\n\nThe API is documented using OpenAPI (Swagger) and can be viewed at `/api-docs` when running in development mode.\n\n## Deployment\n\n### Prerequisites\n\n- Node.js 18+\n- npm 9+\n- Docker (optional)\n\n### Production Build\n\n```bash\n# Install production dependencies\nnpm ci --only=production\n\n# Build the application\nnpm run build\n\n# Start the server\nNODE_ENV=production npm start\n```\n\n### Docker\n\n```bash\n# Build the Docker image\ndocker build -t dust-mcp-server .\n\n# Run the container\ndocker run -p 3000:3000 --env-file .env dust-mcp-server\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Related Resources\n\n- [Dust.tt Documentation](https://docs.dust.tt)\n- [Model Context Protocol](https://github.com/modelcontextprotocol/spec)\n- [Claude Desktop](https://claude.ai/desktop)\n- [Node.js Documentation](https://nodejs.org/en/docs/)\n- [TypeScript Documentation](https://www.typescriptlang.org/docs/)\n- [Express.js Documentation](https://expressjs.com/)\n- [Jest Testing Framework](https://jestjs.io/)\n- [Winston Logging](https://github.com/winstonjs/winston)\n\n### Running the Server\n\nYou can run the MCP server in two different modes: HTTP mode or STDIO mode.\n\n#### HTTP Mode\n\nTo run the server in HTTP mode (for web-based clients):\n\n```bash\nnpm run build\nnpm start -- --http\n```\n\nThe server will listen on the port specified by the `PORT` environment variable (default: 3000).\n\nYou can interact with the API at `http://localhost:3000/api`.\n\n#### SSE Events\n\nThe server supports real-time event streaming via Server-Sent Events (SSE).\n\n- Connect to `http://localhost:3000/events` with an SSE-compatible client to receive server events (e.g., health, agent updates).\n- Example using `curl`:\n  ```bash\n  curl -N http://localhost:3000/events\n  ```\n\n#### STDIO Mode\n\nSTDIO mode is used when you want the server to communicate through standard input/output streams rather than HTTP. This is the mode used by Claude Desktop and other MCP clients that communicate via STDIO.\n\nTo start the server in STDIO mode:\n\n```bash\n# Start the server in STDIO mode\nnode build/dust.js\n```\n\nWhen running in STDIO mode:\n- The server doesn't produce any output to stdout by design, as this channel is reserved for MCP protocol communication\n- Any logs or error messages are directed to the logs directory and stderr\n- The server is immediately ready to accept MCP client connections\n\n#### Stopping the Server\n\nTo stop the server, you can use Ctrl+C in the terminal where it's running, or kill the process:\n\n```bash\npkill -f \"node.*dust-mcp-server\"\n```\n\n## Architecture Diagram\n\n```mermaid\nflowchart TD\n    subgraph Client[\"Client Layer\"]\n        A[Claude Desktop] -- \"MCP Protocol\" --\u003e B[MCP Server]\n    end\n\n    subgraph Server[\"Dust MCP Server\"]\n        B --\u003e C[Request Handler]\n        C --\u003e D[Auth Middleware]\n        D --\u003e E[Windsurf Rules Engine]\n        E --\u003e F[Tool Router]\n        \n        subgraph Tools[\"MCP Tools\"]\n            F --\u003e G[dust_list_agents]\n            F --\u003e H[dust_agent_query]\n            F --\u003e I[dust_create_session]\n            F --\u003e J[dust_end_session]\n            F --\u003e K[dust_get_session]\n            F --\u003e L[dust_get_agent]\n        end\n        \n        subgraph Services[\"Core Services\"]\n            M[DustApiService] \u003c--\u003e N[AgentService]\n            N \u003c--\u003e O[SessionManager]\n            O \u003c--\u003e P[MemoryBank]\n        end\n    end\n    \n    subgraph External[\"External Services\"]\n        Q[(Dust AI Platform)]\n    end\n    \n    subgraph Memory[\"Memory Bank\"]\n        R[productContext.md]\n        S[systemPatterns.md]\n        T[activeContext.md]\n        U[decisionLog.md]\n        V[progress.md]\n    end\n    \n    Tools --\u003e Services\n    Services --\u003e Q\n    Services --\u003e Memory\n    \n    %% Styling\n    classDef client fill:#e1f5fe,stroke:#01579b,color:#01579b\n    classDef server fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20\n    classDef external fill:#f3e5f5,stroke:#4a148c,color:#4a148c\n    classDef memory fill:#fff3e0,stroke:#e65100,color:#e65100\n    \n    class A,Client client\n    class B,C,D,E,F,G,H,I,J,K,L,Server server\n    class Q,External external\n    class R,S,T,U,V,Memory memory\n```\n\n### Key Components\n\n1. **Client Layer**:\n   - Claude Desktop communicates with the MCP Server using the MCP protocol\n\n2. **MCP Server**:\n   - **Request Handler**: Processes incoming MCP requests\n   - **Auth Middleware**: Validates API keys and permissions\n   - **Windsurf Rules Engine**: Enforces project-specific rules and workflows\n   - **Tool Router**: Routes requests to the appropriate MCP tool\n   - **MCP Tools**: Individual tools for agent interaction and session management\n\n3. **Core Services**:\n   - **DustApiService**: Handles communication with the Dust AI platform\n   - **AgentService**: Manages agent lifecycle and interactions\n   - **SessionManager**: Maintains session state and context\n   - **MemoryBank**: Manages persistent storage using the memory-bank system\n\n4. **Memory Bank**:\n   - `productContext.md`: Project goals and high-level architecture\n   - `systemPatterns.md`: Design patterns and implementation details\n   - `activeContext.md`: Current status and recent changes\n   - `decisionLog.md`: Architectural and implementation decisions\n   - `progress.md`: Task tracking and milestones\n\n5. **External Services**:\n   - Dust AI Platform: External service for agent execution and processing\n\n\n### Using MCP Tools\n\nThis project uses [MCP Tools](https://github.com/f/mcptools) for testing and integration. Here's how to use them:\n\n1. Install MCP Tools globally\n\n```bash\nnpm install -g mcptools\n```\n\n2. List available tools in the server\n\n```bash\nmcp tools node build/dust.js\n```\n\n3. Call a specific tool\n\n```bash\nmcp call dust_list_agents node build/dust.js --params '{\"limit\": 10}'\n\nmcp call dust_agent_query node build/dust.js --params '{\"query\": \"Give me a summary\"}'\n```\n\n4. Add the server to your aliases\n\n```bash\nmcp alias add dust node build/dust.js\nmcp alias list\n```\n\n5. Configure with Claude Desktop\n\n```bash\nmcp configs set claude-desktop dust /path/to/node /path/to/dust-mcp-server/build/dust.js\n```\n\n## MCP Tools Reference\n\nThe server provides the following MCP tools for interacting with Dust.tt agents:\n\n### `dust_list_agents`\n\nList all available agents in the workspace.\n\n**Parameters:**\n\n- `query` (string, optional): Filter agents by name or description\n- `view` (string, optional): View type for filtering agents\n- `limit` (number, optional): Maximum number of agents to return (default: 10)\n\n**Example Request:**\n\n```bash\nmcp call dust_list_agents node build/dust.js --params '{\"limit\": 10}'\n```\n\n**Response:**\n\n```typescript\ninterface AgentDescriptor {\n  id: string;\n  name: string;\n  description: string;\n  capabilities: string[];\n  isActive?: boolean;\n  lastUsed?: string;\n}\n```\n\n#### `dust_agent_query`\n\nQuery a Dust agent within a session.\n\n**Parameters:**\n\n- `agentId` (string, required): ID of the agent to query\n- `message` (string, required): The message to send to the agent\n- `files` (Array\u003c{ name: string; content: string }\u003e, optional): Files to include with the message\n- `sessionId` (string, optional): Existing session ID to continue conversation\n\n**Example Request:**\n\n```json\n{\n  \"agentId\": \"agent_123\",\n  \"message\": \"What's the weather like?\",\n  \"files\": [\n    {\n      \"name\": \"location.txt\",\n      \"content\": \"San Francisco\"\n    }\n  ]\n}\n```\n\n**Response:**\n\n```typescript\ninterface DustMessageResponse {\n  response: string;\n  context: Record\u003cstring, any\u003e;\n}\n```\n\n#### `dust_create_session`\n\nCreate a new session with a Dust agent.\n\n**Parameters:**\n\n- `agentId` (string, required): ID of the agent to create a session with\n- `context` (object, optional): Initial context for the session\n\n**Example Request:**\n\n```bash\nmcp call dust_create_session node build/dust.js --params '{\n  \"agentId\": \"agent_123\",\n  \"context\": {\n    \"userPreferences\": {\n      \"language\": \"en-US\"\n    }\n  }\n}'\n```\n\n**Response:**\n\n```typescript\ninterface SessionDescriptor {\n  id: string;\n  agentId: string;\n  context: Record\u003cstring, any\u003e;\n  isActive: boolean;\n  createdAt: string;\n  lastActivity: string;\n}\n```\n\n#### `dust_end_session`\n\nEnd an active session.\n\n**Parameters:**\n\n- `sessionId` (string, required): ID of the session to end\n\n**Example Request:**\n\n```bash\nmcp call dust_end_session node build/dust.js --params '{\"sessionId\": \"sess_123\"}'\n```\n\n#### `dust_get_session`\n\nGet details of a specific session.\n\n**Parameters:**\n\n- `sessionId` (string, required): ID of the session to retrieve\n\n**Example Request:**\n\n```bash\nmcp call dust_get_session node build/dust.js --params '{\"sessionId\": \"sess_123\"}'\n```\n\n#### `dust_get_agent`\n\nGet details of a specific agent.\n\n**Parameters:**\n\n- `agentId` (string, required): ID of the agent to retrieve\n\n**Example Request:**\n\n```bash\nmcp call dust_get_agent node build/dust.js --params '{\"agentId\": \"agent_123\"}'\n```\n\n**Response:**\n\n```typescript\ninterface AgentDescriptor {\n  id: string;\n  name: string;\n  description: string;\n  capabilities: string[];\n  isActive: boolean;\n  createdAt: string;\n  updatedAt: string;\n  configuration: Record\u003cstring, any\u003e;\n}\n```\n\n## Project Structure\n\n```text\nroot/\n├── src/                # Main source code\n│   ├── services/       # Dust API integration layer\n│   └── tools/          # (Deprecated) MCP tool implementations\n├── build/              # Compiled JavaScript output\n├── logs/               # Application and debug logs\n│   └── debug/\n├── memory-bank/        # Project context and memory files\n├── docs/               # Documentation, images, and moved test/demo scripts\n├── .env                # Environment configuration (not committed)\n├── .env.example        # Example environment file\n├── package.json        # Project manifest\n└── README.md           # Main documentation (this file)\n```\n\n## Testing\n\n### Test Features\n\nThe test suite includes the following features:\n\n- **Mocking**: Tests use Jest mocking to isolate the MCP methods from actual API calls\n- **Test Data**: Sample agent configurations and responses are provided in `test/fixtures/`\n- **Parameter Validation**: Tests verify that parameters are correctly validated\n- **Complete Coverage**: Tests cover all parameters and response formats\n\n### Running Tests\n\nYou can run the tests using npm scripts:\n\n```bash\n# Install dependencies first (if not already installed)\nnpm install\n\n# Run all tests\nnpm test\n\n# Run only unit tests\nnpm run test:unit\n\n# Run only integration tests\nnpm run test:integration\n```\n\n### Manual Testing\n\nYou can also manually test the MCP functionality using the scripts in `docs/`:\n\n```bash\n# Test MCP tools functionality\nnode docs/test-mcp-tools.js\n\n# Test STDIO transport\nnode docs/test-stdio.js\n```\n\n## Debugging\n\n### VS Code Debugging\n\nThe project includes VS Code debugging configurations for both the server and tests. You can use these configurations to debug the application directly from VS Code.\n\n### Available Debug Configurations\n\n1. **Debug Server (HTTP)**\n   - Launches the server in debug mode with auto-reload\n   - Attaches to the running Node.js process\n   - Supports breakpoints and step debugging\n\n2. **Debug Tests**\n   - Runs the test suite in debug mode\n   - Supports breakpoints in test files\n   - Shows detailed test output\n\n3. **Debug Current Test File**\n   - Runs the currently open test file with the debugger attached\n   - Useful for focusing on a specific test case\n   - Supports breakpoints in test files and source code\n\n4. **Debug All Tests**\n   - Runs all tests in the project with the debugger attached\n   - Useful for debugging test suites or integration tests\n   - Supports breakpoints in test files and source code\n\n#### How to Use\n\n1. Open the project in VS Code\n2. Set breakpoints in your code by clicking in the gutter next to the line numbers\n3. Open the Run and Debug view (Ctrl+Shift+D or Cmd+Shift+D)\n4. Select a debug configuration from the dropdown\n5. Click the green play button or press F5 to start debugging\n\n### Log Files\n\nLogs are stored in the `logs/` directory:\n- `app-YYYY-MM-DD.log`: Application logs\n- `server-YYYY-MM-DD.log`: Server logs\n- `test-mcp-YYYY-MM-DD.log`: MCP tools test logs\n\n## Development\n\n```bash\n# Run in development mode with auto-reload\nnpm run dev\n\n# Build the project\nnpm run build\n```\n\n## API Documentation\n\nFor more information about the Dust API, see the official documentation:\n\n- [Dust API Documentation](https://docs.dust.tt/reference/openapi)\n- [Agent Configurations](https://docs.dust.tt/reference/get_api-v1-w-wid-assistant-agent-configurations-sid)\n- [Conversations](https://docs.dust.tt/reference/post_api-v1-w-wid-assistant-conversations)\n- [Messages](https://docs.dust.tt/reference/post_api-v1-w-wid-assistant-conversations-cid-messages)\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fma3u%2Fdust-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fma3u%2Fdust-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fma3u%2Fdust-mcp-server/lists"}