README.md•6.3 kB
# 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
```bash
# 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
```bash
PORT=3000 # Server port (default: 3000)
HOST=localhost # Server host (default: localhost)
```
### Docker Deployment
```bash
# 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
```bash
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)
```bash
# 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
```javascript
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:
```json
{
"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](https://github.com/deso-protocol/mcp-server)
- DeSo Documentation: [docs.deso.org](https://docs.deso.org)
- Developer Discord: [DeSo Developers](https://discord.gg/deso)