deso-mcp

DeSo MCP Server v3.0 (HTTP)

A comprehensive Model Context Protocol (MCP) server for DeSo blockchain development, now with HTTP transport support.

Features

🛠️ 10 Comprehensive Tools:

• deso_api_explorer - Complete DeSo API documentation and examples
• deso_js_guide - deso-js SDK setup and usage guides
• generate_deso_code - Generate code examples for DeSo operations
• explain_deso_architecture - Architectural explanations and patterns
• repository_search - Search DeSo repository documentation
• read_repository_document - Read specific DeSo docs
• deso_debugging_guide - Real debugging fixes for common issues
• deso_implementation_patterns - Best practices from production apps
• deso_ui_components - Complete UI component library guide
• deso_graphql_helper - GraphQL query builder and examples

🚀 HTTP Transport:

• RESTful HTTP API instead of stdio
• CORS support for web integration
• Health check endpoint
• Easy deployment and scaling

Quick Start

Local Development

# Install dependencies
npm install

# Start the server
npm start

# Development with auto-reload
npm run dev

The server will run on http://localhost:3000 by default.

Environment Variables

PORT=3000          # Server port (default: 3000)
HOST=localhost     # Server host (default: localhost)

Docker Deployment

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or manually:
docker build -t deso-mcp-server .
docker run -p 3000:3000 -e HOST=0.0.0.0 deso-mcp-server

HTTP Endpoints

Health Check

curl http://localhost:3000/

MCP Tool Requests

Send JSON-RPC requests to the root endpoint.

Important:

• MCP requires initialization first, then you can call tools
• Always include the Accept: application/json, text/event-stream header
• The server runs in stateless mode (no session management required)

# 1. Initialize the MCP session
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "capabilities": {},
      "protocolVersion": "2024-11-05",
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    }
  }'

# 2. List available tools
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

# 3. Call a specific tool
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", 
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "deso_api_explorer",
      "arguments": {
        "category": "social",
        "includeCode": true
      }
    }
  }'

Example Usage

JavaScript Client Example

class DesoMCPClient {
  constructor(baseUrl = 'http://localhost:3000') {
    this.baseUrl = baseUrl;
    this.initialized = false;
  }

  async request(method, params = {}) {
    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream'
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method,
        params
      })
    });

    const data = await response.json();
    if (data.error) throw new Error(data.error.message);
    return data.result;
  }

  async initialize() {
    await this.request('initialize', {
      capabilities: {},
      protocolVersion: '2024-11-05',
      clientInfo: { name: 'deso-client', version: '1.0.0' }
    });
    this.initialized = true;
  }

  async callTool(name, args) {
    if (!this.initialized) await this.initialize();
    return this.request('tools/call', { name, arguments: args });
  }
}

// Usage examples:
const client = new DesoMCPClient();

// Get DeSo API Information
const apiInfo = await client.callTool('deso_api_explorer', {
  category: 'social',
  endpoint: 'submit-post',
  includeCode: true
});

// Debug DeSo Integration Issues
const debugInfo = await client.callTool('deso_debugging_guide', {
issue: 'message-decryption',
includeCode: true
});

// Generate GraphQL Queries
const query = await client.callTool('deso_graphql_helper', {
action: 'build',
question: 'How many followers does nader have?',
username: 'nader'
});

## Integration with MCP Clients

### Claude Desktop Configuration

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "deso": {
      "command": "npx",
      "args": ["deso-mcp-server"],
      "transport": "http",
      "url": "http://localhost:3000"
    }
  }
}

VS Code Integration

Use with MCP-compatible VS Code extensions by configuring the HTTP endpoint:

{
  "mcp.servers": [
    {
      "name": "deso",
      "transport": "http",
      "url": "http://localhost:3000"
    }
  ]
}

Architecture

The server uses:

• HTTP Transport: RESTful API with JSON-RPC over HTTP
• CORS Support: Cross-origin requests enabled
• Graceful Shutdown: Proper cleanup on SIGINT/SIGTERM
• Error Handling: Comprehensive error responses
• Health Checks: Built-in monitoring endpoint

Development

Project Structure

deso-mcp/
├── deso-mcp.js          # Main MCP server
├── package.json         # Dependencies and scripts  
├── Dockerfile          # Container configuration
└── README.md           # Documentation

Debugging

• Enable debug logging with DEBUG=mcp:*
• Check server health at http://localhost:3000/
• Monitor logs for request/response details

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with HTTP requests
5. Submit a pull request

Support

For issues and questions:

• GitHub Issues: deso-protocol/mcp-server
• DeSo Documentation: docs.deso.org
• Developer Discord: DeSo Developers