deso-protocol/deso-mcp

DeSo MCP Server for Cursor IDE v3.0

A comprehensive Model Context Protocol (MCP) server that provides complete DeSo blockchain API coverage for Cursor IDE. This server transforms Cursor's AI assistant into a DeSo development expert with extensive knowledge about all DeSo APIs, the deso-js SDK, DeSo Identity authentication, backend implementation details, production-ready code generation, and comprehensive debugging solutions.

🔥 What's New in v3.0

• 🛠️ Comprehensive Debugging Guide: Real solutions for all major DeSo integration issues
• 🏗️ Implementation Patterns: Best practices learned from building production DeSo apps
• 🎨 DeSo UI Component Library: Complete frontend component system with 40+ ready-to-use React components
• 📦 Component Installation: Automated shadcn CLI integration with installation commands and examples
• 🔍 GraphQL Query Builder: Natural language to GraphQL conversion with complete DeSo blockchain schema coverage
• 📊 Blockchain Data Access: Query user profiles, posts, followers, NFTs, and more with ready-to-use GraphQL queries
• 📱 Complete Example App: Full DeSo messaging application with Next.js, TypeScript, and Tailwind
• 🐛 Real Debugging Experience: Solutions based on actual debugging sessions and common pitfalls

What's New in v2.2-2.3

• Complete DeSo Identity Integration: Full authentication system coverage
• 9 Identity API Endpoints: iframe & window APIs for login, signing, encryption
• Advanced Authentication Guide: Access levels, derived keys, message encryption
• Complete Data API Coverage: All endpoint categories from DeSo backend documentation
• 40+ Data Endpoints: Users, Posts, NFTs, Messages, Notifications, Access Groups, and more

🚀 What This Does

This MCP server transforms Cursor's AI assistant into a DeSo development expert by providing:

• Complete DeSo API Knowledge: All endpoints from the backend with handler details
• deso-js SDK Expertise: Full SDK documentation and usage patterns
• Code Generation: Production-ready examples in JavaScript, TypeScript, React, and cURL
• Architecture Guidance: Deep understanding of DeSo's transaction flows and systems
• Backend Integration: Direct mapping to routes/transaction.go and other backend files
• 🎨 UI Component Library: 40+ professional React components for DeSo applications
• 📦 Component Installation: Automated shadcn CLI commands and dependency management
• 🔍 GraphQL Query Builder: Convert natural language questions to optimized GraphQL queries
• 📊 Blockchain Data Explorer: Complete access to DeSo's GraphQL API with 15,000+ schema lines
• 🛠️ Debugging Solutions: Real fixes for common DeSo integration problems
• 🏗️ Best Practices: Implementation patterns from production DeSo applications

📋 Available Tools Overview

Core Development Tools

1. 🔍 deso_api_explorer - Complete DeSo API reference with code examples
2. 📚 deso_js_guide - Comprehensive deso-js SDK documentation and setup
3. ⚡ generate_deso_code - Production-ready code generation for any DeSo operation
4. 🏛️ explain_deso_architecture - Deep architecture explanations and integration patterns

Knowledge Base Tools

5. 🔎 repository_search - Search across all DeSo documentation and repositories
6. 📖 read_repository_document - Read specific documentation files from DeSo repos

UI Development Tools (NEW in v3.0)

7. 🎨 deso_ui_components - Complete DeSo UI component library with installation and usage examples

Data Query Tools (NEW in v3.0)

8. 🔍 deso_graphql_helper - GraphQL query builder and blockchain data explorer

Advanced Debugging Tools (NEW in v3.0)

9. 🛠️ deso_debugging_guide - Comprehensive debugging for common DeSo issues
10. 🏗️ deso_implementation_patterns - Best practices from real DeSo application development

🛠️ Complete Tool Reference

1. deso_api_explorer - API Explorer

Comprehensive DeSo API explorer with backend implementation details and deso-js SDK integration.

Parameters:

• category (required): API category to explore
  • Options: "social", "financial", "nft", "dao", "tokens", "access", "associations", "derived-keys", "messages", "data", "notifications", "media", "admin", "blockchain", "identity", "all"
• endpoint (optional): Specific endpoint name
• includeCode (optional): Include code examples

Example Usage:

Show me all the social APIs for DeSo
Use the DeSo API explorer to show messaging endpoints with code examples
Explore the identity APIs for authentication

2. deso_js_guide - SDK Guide

Complete guide to using the deso-js SDK with setup, authentication, and transactions.

Parameters:

• topic (required): Topic to get guidance on
  • Options: "setup", "identity", "authentication", "transactions", "data", "permissions", "examples", "troubleshooting"
• framework (optional): Framework context
  • Options: "vanilla", "react", "nextjs", "node"

Example Usage:

Show me how to set up the deso-js SDK in a React app
Guide me through DeSo authentication with identity management
How do I handle transactions in Next.js with deso-js?

3. generate_deso_code - Code Generator

Generate comprehensive code examples for DeSo operations using deso-js SDK.

Parameters:

• operation (required): DeSo operation (e.g., 'follow', 'post', 'buy-creator-coin', 'send-diamonds')
• language (required): Programming language/framework
  • Options: "javascript", "typescript", "react", "curl"
• includeAuth (optional): Include authentication setup
• fullExample (optional): Generate complete working example

Example Usage:

Generate a React component for following users with authentication
Create a TypeScript function for sending diamonds with full example
Show me how to create posts using JavaScript with the deso-js SDK

4. explain_deso_architecture - Architecture Guide

Explain DeSo architecture, flows, and integration patterns.

Parameters:

• topic (required): Architecture topic to explain
• includeCode (optional): Include code examples

Example Usage:

Explain how DeSo transactions work with code examples
What's the difference between master keys and derived keys?
How does the DeSo messaging system architecture work?

5. repository_search - Repository Search

Search for documents in the DeSo repository.

Parameters:

• query (required): Search query

Example Usage:

Search the DeSo repositories for messaging documentation
Find information about NFT creation in the DeSo docs

6. read_repository_document - Document Reader

Read a specific document from the DeSo repository.

Parameters:

• path (required): Relative path to the document (e.g., 'docs/deso-tutorial-build-apps.md')
• repository (optional): Repository name
  • Options: "docs", "core", "identity", "frontend", "backend", "deso-js"

Example Usage:

Read the DeSo tutorial for building apps
Show me the content of the DeSo backend documentation for transactions

7. deso_ui_components - UI Component Library (NEW in v3.0)

Comprehensive DeSo UI component library explorer with installation commands, usage examples, and component relationships.

Parameters:

• action (required): Action to perform with the UI component library
  • Options: "explore", "install", "usage", "dependencies", "examples", "layouts", "categories", "search"
• component (optional): Specific component name (e.g., 'post-card', 'editor', 'profile-picture')
• category (optional): Component category to explore
  • Options: "social", "user", "messaging", "media", "interactive", "navigation", "layout", "all"
• framework (optional): Target framework for examples
  • Options: "react", "nextjs", "vanilla"
• query (optional): Search query for components

Example Usage:

Show me all available DeSo UI components
Install the post-card component with examples
Explore social media components for React
Generate usage examples for the message-inbox component
Show me complete layout patterns for a Twitter-like app
Search for components related to user profiles

8. deso_graphql_helper - GraphQL Query Builder (NEW in v3.0)

GraphQL query builder and schema explorer for DeSo blockchain data. Converts natural language questions into optimized GraphQL queries and provides complete blockchain data access.

Parameters:

• action (required): Action to perform with GraphQL
  • Options: "query", "schema", "examples", "build", "explain"
• queryType (optional): Type of query to build or explain
  • Options: "user", "posts", "followers", "following", "likes", "diamonds", "messages", "nfts", "custom"
• username (optional): Username to query for (e.g., 'nader')
• publicKey (optional): Public key to query for
• question (optional): Natural language question to convert to GraphQL
• customQuery (optional): Custom GraphQL query to explain or validate

Example Usage:

Convert this question to GraphQL: "How many followers does nader have?"
Generate a GraphQL query to get user posts with engagement metrics
Explain the DeSo GraphQL schema for user accounts
Build a query to find when nader last posted
Show me GraphQL examples for getting user diamonds and NFTs

9. deso_debugging_guide - Debugging Guide (NEW in v3.0)

Comprehensive debugging guide for common DeSo integration issues with real solutions.

Parameters:

• issue (required): Specific issue to debug or 'all' for complete guide
  • Options: "message-decryption", "access-groups", "infinite-loops", "api-responses", "authentication", "react-errors", "all"
• includeCode (optional): Include code examples and fixes

Example Usage:

Help me debug DeSo message decryption issues
Show me how to fix infinite loops in React DeSo components
Debug DeSo authentication problems with code examples

10. deso_implementation_patterns - Implementation Patterns (NEW in v3.0)

Best practices and implementation patterns learned from real DeSo application development.

Parameters:

• pattern (required): Implementation pattern to explore
  • Options: "messaging-flow", "error-handling", "state-management", "api-integration", "user-switching", "real-time-updates", "all"
• framework (optional): Framework context
  • Options: "react", "vanilla", "nextjs"

Example Usage:

Show me best practices for DeSo messaging flow in React
What are the recommended error handling patterns for DeSo apps?
How should I implement real-time updates in a DeSo application?

🎨 DeSo UI Component Library Integration

The MCP server now includes complete integration with the official DeSo UI component library, providing:

Component Categories:

• 🏃 Social - Post cards, feeds, engagement metrics, reactions (10 components)
• 👤 User - Profile cards, avatars, authentication, user search (8 components)
• 💬 Messaging - Chat interfaces, conversation management, message bubbles (5 components)
• 🎬 Media - Image galleries, video players, media cards, video reels (4 components)
• ⚡ Interactive - Rich text editor, search bars, action menus, dialogs (6 components)
• 🧭 Navigation - Sidebars, menus, logos (2 components)
• 🔧 Utility - Timestamps, copy buttons, verification badges (3 components)

Key Features:

• 🎯 Instant Installation: Generate exact shadcn CLI commands
• 📚 Usage Examples: React/TypeScript code examples with DeSo SDK integration
• 🔗 Dependency Management: Automatic dependency resolution and installation order
• 🏗️ Complete Layouts: Ready-to-use patterns for Twitter-like apps, messaging, profiles
• 🔍 Smart Search: Find components by name, description, or functionality
• 📱 Responsive Design: Mobile-first components with Tailwind CSS

Example Component Usage:

// Install a component
npx shadcn@latest add http://ui.deso.com/r/post-card.json

// Use in your React app
import { PostCard } from '@/components/deso-ui/post-card';

<PostCard
  publicKey="BC1YLi..."
  postContent="Hello DeSo! 🚀"
  timestamp={new Date()}
  images={["https://example.com/image.jpg"]}
  actions={{ comments: 5, likes: 25, reposts: 3 }}
/>

🔍 DeSo GraphQL Query Builder Integration

The MCP server now includes complete GraphQL integration with DeSo's blockchain data, providing:

Natural Language to GraphQL:

Convert plain English questions into optimized GraphQL queries:

Question: "How many followers does nader have?"
↓
Generated GraphQL:
query GetFollowerCount($username: String!) {
  accounts(filter: { username: { equalToInsensitive: $username } }) {
    nodes {
      username
      followers { totalCount }
    }
  }
}

Complete Schema Coverage:

• 15,574 lines of GraphQL schema fully mapped
• User profiles with follower/following counts, creator coins
• Posts with engagement metrics, timestamps, media
• Social interactions - likes, diamonds, comments, reposts
• NFT marketplace data - bids, sales, royalties
• Messaging - DMs and group conversations
• Financial data - creator coin prices, transactions

Smart Query Optimization:

• Case-insensitive lookups for usernames
• Efficient pagination with proper first parameters
• Relationship traversal through nested GraphQL fields
• Count optimization using totalCount without fetching all records
• Proper sorting with orderBy: [TIMESTAMP_DESC] for recent content

Ready-to-Use Query Templates:

// Get user profile with all metrics
const userQuery = `
  query GetUser($username: String!) {
    accounts(filter: { username: { equalToInsensitive: $username } }) {
      nodes {
        username
        description
        profilePic
        followers { totalCount }
        following { totalCount }
        posts { totalCount }
        coinPriceDesoNanos
      }
    }
  }
`;

// Execute the query
const response = await fetch('https://graphql.deso.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    query: userQuery, 
    variables: { username: "nader" } 
  })
});

Supported Data Types:

• 👤 Users: Profiles, followers, following, creator coins
• 📝 Posts: Content, engagement, timestamps, media
• 💎 Diamonds: Sent/received with levels and recipients
• ❤️ Likes: User interactions with posts
• 🖼️ NFTs: Marketplace data, bids, ownership
• 💬 Messages: DMs and group conversations
• 💰 Financial: Creator coin prices, transactions

🎯 Real-World Example: DeSo Messaging App

This repository includes a complete DeSo messaging application built with the MCP server guidance:

Built Application Features:

• ✅ Complete DeSo Identity authentication
• ✅ Real-time user search and discovery
• ✅ Actual blockchain message sending via sendDMMessage
• ✅ Professional React components with TypeScript
• ✅ Real-time message polling and status updates
• ✅ Comprehensive error handling and debugging features
• ✅ Modern UI with Tailwind CSS and responsive design

Technical Stack:

• Frontend: Next.js 14, React, TypeScript, Tailwind CSS
• DeSo Integration: deso-protocol SDK v3.4.1
• Authentication: DeSo Identity with proper permission management
• State Management: Custom React hooks with proper error handling

Example App Structure:

example-app/
├── src/
│   ├── app/                 # Next.js app directory
│   ├── components/
│   │   ├── auth/           # Authentication components
│   │   ├── chat/           # Messaging components  
│   │   └── user/           # User discovery components
│   ├── hooks/              # Custom React hooks
│   ├── lib/                # DeSo configuration and types
│   └── styles/             # Global styles
├── package.json            # Dependencies
└── README.md              # App documentation

🛠 Installation & Setup

Prerequisites

• Node.js (v18+ recommended)
• Cursor IDE
• Git (for cloning repositories)

1. Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd deso-mcp

# Install dependencies
npm install

# Verify the MCP server works
npm run test

2. Configure Cursor IDE

Create or update your Cursor MCP configuration file:

File: .cursor/mcp.json

{
  "deso-mcp": {
    "command": "node",
    "args": ["deso-mcp.js"],
    "cwd": "/absolute/path/to/your/deso-mcp",
    "type": "stdio"
  }
}

Important: Replace /absolute/path/to/your/deso-mcp with your actual project path.

💡 Quick tip: Run pwd in your project directory to get the absolute path:

cd deso-mcp
pwd
# Copy this path to use in .cursor/mcp.json

3. Enable in Cursor Settings

1. Open Cursor Settings (⌘ + , on Mac, Ctrl + , on Windows/Linux)
2. Navigate to Features → MCP
3. You should see "deso-mcp" listed
4. Ensure it shows as "Connected" ✅

4. Test the Integration

1. Start a new chat in Cursor (⌘ + L or Ctrl + L)
2. Test with this prompt:

   Use the DeSo MCP tools to show me how to follow a user with the deso-js SDK
   

3. You should see the AI use your MCP tools and provide comprehensive DeSo-specific guidance!

🎯 Usage Examples

Once configured, you can ask Cursor's AI assistant questions like:

API Exploration

• "Show me all the identity endpoints for DeSo authentication"
• "What are the iframe vs window APIs in DeSo Identity?"
• "Show me all the data endpoints available in DeSo"
• "What notification APIs can I use to get user notifications?"
• "How do I fetch DM messages using the messages API?"

Code Generation

• "Generate a React authentication component with DeSo Identity"
• "Show me how to encrypt and decrypt messages using deso-js"
• "Create a derived key manager for mobile apps"
• "Generate a React component for creating and minting NFTs"
• "Create a complete DeSo messaging interface with TypeScript"

UI Component Development

• "Show me all available DeSo UI components for social media"
• "Install the post-card component with usage examples"
• "Generate a complete Twitter-like layout using DeSo UI components"
• "Show me messaging components for building a chat interface"
• "Find components for user profiles and authentication"
• "Create a media gallery layout with DeSo UI components"

GraphQL Data Queries

• "Convert this to GraphQL: How many followers does nader have?"
• "Generate a query to get user posts with engagement metrics"
• "Show me the GraphQL schema for DeSo user accounts"
• "Build a query to find when a user last posted"
• "Get GraphQL examples for diamonds and NFT data"
• "Explain this GraphQL query and optimize it"

Debugging & Troubleshooting

• "Help me debug DeSo message decryption that's returning undefined"
• "Fix infinite loops in my React DeSo authentication component"
• "Why am I getting 400 errors when sending DeSo messages?"
• "Debug access group empty string vs undefined issues"
• "Show me the correct way to handle DeSo API responses"

Implementation Patterns

• "Show me best practices for DeSo messaging flow architecture"
• "What's the recommended error handling pattern for DeSo apps?"
• "How should I implement user switching in a DeSo application?"
• "Show me real-time polling patterns for DeSo messaging"

Setup & Configuration

• "How do I set up the deso-js SDK in a React app?"
• "What permissions do I need for posting transactions?"
• "Show me how to configure identity management"
• "What are the different access levels in DeSo Identity?"

🔧 Development Commands

# Quick tests using npm scripts
npm run test              # Test tools list
npm run test-follow       # Test follow endpoint with code

# Run the server manually
node deso-mcp.js

# Test specific tools manually
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "deso_api_explorer", "arguments": {"category": "social"}}}' | node deso-mcp.js

# Test debugging guide
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "deso_debugging_guide", "arguments": {"issue": "all", "includeCode": true}}}' | node deso-mcp.js

# Test implementation patterns
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "deso_implementation_patterns", "arguments": {"pattern": "messaging-flow", "framework": "react"}}}' | node deso-mcp.js

# Test UI components
echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "deso_ui_components", "arguments": {"action": "explore", "category": "social"}}}' | node deso-mcp.js

# Test GraphQL helper
echo '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "deso_graphql_helper", "arguments": {"action": "build", "question": "How many followers does nader have?"}}}' | node deso-mcp.js

📁 Project Structure

deso-mcp/
├── deso-mcp.js            # Main MCP server implementation (v3.0 with UI + GraphQL)
├── deso-mcp-final.js      # Legacy comprehensive server (v3.0)
├── mcp-server.js          # Legacy server (v2.3)
├── package.json           # Dependencies and scripts
├── .cursor/
│   └── mcp.json          # Cursor MCP configuration
├── repos/                 # DeSo repository clones
│   ├── docs/             # DeSo documentation
│   ├── backend/          # DeSo backend code
│   ├── deso-js/          # DeSo JavaScript SDK
│   ├── deso-ui/          # DeSo UI component library
│   └── graphql/          # DeSo GraphQL schema (15,574 lines)
├── example-app/          # Complete DeSo messaging application
│   ├── src/              # Next.js app source
│   ├── package.json      # App dependencies
│   └── README.md         # App documentation
└── schema.graphql        # DeSo GraphQL schema

🐛 Troubleshooting

MCP Server Not Connecting

1. Check the path in .cursor/mcp.json is absolute and correct
2. Update to use deso-mcp.js (latest with UI + GraphQL) instead of deso-mcp-final.js or mcp-server.js
3. Restart Cursor completely
4. Check server runs manually:

   node deso-mcp.js
   # Should output: "🚀 DeSo MCP Server v3.0 connected successfully with 10 comprehensive tools!"
   

Tools Not Available in Chat

1. Start a new chat session in Cursor (⌘ + L)
2. Explicitly mention MCP tools in your first message
3. Check MCP status in Cursor Settings → Features → MCP

Dependencies Issues

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version  # Should be v18+

Common DeSo Integration Issues

Use the debugging guide tool for specific issues:

Use the DeSo debugging guide to help me with [specific issue]

The server includes comprehensive debugging solutions for:

• Message decryption problems (DecryptedMessage vs MessageText)
• Access group handling (empty strings vs undefined)
• React infinite loops (useCallback dependencies)
• API response structure issues
• Authentication flow problems
• User switching and state management

🚀 Advanced Features

Real Debugging Experience

The v3.0 server includes solutions for actual problems encountered while building DeSo applications:

• Message Decryption Fix: Proper handling of DecryptedMessage vs MessageText properties
• Access Groups Solution: Correct empty string vs undefined handling
• React Integration: Solutions for key warnings, state management, and error boundaries
• API Response Handling: Proper response structure handling per endpoint
• Authentication Flows: Complete identity event handling and user switching

Production Patterns

Learn from real implementation patterns:

• Complete messaging flow with encryption and access groups
• Comprehensive error handling with retry logic
• Professional state management patterns
• Real-time polling and optimistic updates
• User experience best practices

Framework-Specific Examples

The server can generate examples for different frameworks:

• Vanilla JavaScript: Basic SDK usage
• React: Component patterns with hooks and TypeScript
• Next.js: Server-side integration and API routes
• React Native: Mobile-specific configuration

📚 Related Resources

• DeSo Documentation
• deso-js SDK
• DeSo Backend Repository
• React Examples
• Model Context Protocol

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add new MCP tools or enhance existing ones
4. Update this README with new features
5. Submit a pull request

✅ Quick Verification Checklist

After setup, verify everything is working:

# 1. Test MCP server is functional
npm run test

# 2. Test specific tool with code examples  
npm run test-follow

# 3. Test debugging guide
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "deso_debugging_guide", "arguments": {"issue": "authentication", "includeCode": true}}}' | node deso-mcp.js

# 4. Check Cursor MCP connection
# Open Cursor → Settings → Features → MCP → Should show "deso-mcp" as Connected ✅

# 5. Test in Cursor AI
# Start new chat (⌘ + L) and ask:
# "Use the DeSo debugging guide to help me with message decryption issues"

🎉 What You Can Do Now

With this MCP server, your Cursor AI assistant can:

✅ Explore any DeSo API with complete documentation and code examples
✅ Generate production-ready code for any DeSo operation in multiple languages
✅ Build beautiful UIs with 40+ professional React components from DeSo UI library
✅ Install components instantly with automated shadcn CLI integration
✅ Query blockchain data with natural language to GraphQL conversion
✅ Access complete DeSo data through optimized GraphQL queries (15,574 schema lines)
✅ Debug real DeSo integration problems with tested solutions
✅ Implement best practices learned from production DeSo applications
✅ Understand DeSo architecture with deep technical explanations
✅ Search and read all DeSo documentation and repositories
✅ Create complete applications following proven patterns
✅ Handle authentication flows with proper identity management

Start a new chat in Cursor and experience the power of AI-assisted DeSo development! ⚡

🚀 Ready to build amazing DeSo applications with AI assistance!