WebSim MCP Server

A comprehensive Model Context Protocol (MCP) server for interacting with WebSim's public API. This server provides access to WebSim's ecosystem of projects, users, feeds, assets, and comments through standardized MCP tools.

🌟 Features

Project Management

• Get projects by ID or slug - Retrieve specific WebSim projects
• List all public projects - Browse the complete public project catalog
• List user projects - Access projects created by specific users
• Project revisions - View historical versions of projects
• Project statistics - Get detailed analytics for projects
• Project descendants - Find projects that are based on or derived from others

User Management

• User profiles - Retrieve comprehensive user information
• User statistics - Get user activity and engagement metrics
• User search - Find users by username or other criteria
• Social connections - Access user's following and follower lists

Feed & Discovery

• Trending feed - Discover popular and trending content
• Latest posts - Get the most recent activity
• Feed search - Search content with sorting options (trending, newest, popular)
• Trending rooms - Find popular interactive rooms and experiences

Assets & Search

• Asset search - Find specific assets and resources
• Bulk asset search - Search multiple queries simultaneously
• Relevant asset discovery - Find assets related to your interests
• Related keywords - Get keyword suggestions for searches
• Top searches - See what others are searching for
• Project assets - Access assets within specific projects

Comments & Interaction

• Project comments - Read community discussions on projects
• Comment replies - View threaded conversations and replies

System Features

• Health monitoring - Built-in health checks for API connectivity
• Error handling - Comprehensive error recovery and reporting
• Pagination support - Efficient data retrieval with limit/offset
• Input validation - Robust parameter validation using Zod schemas

🚀 Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager

Installation

1. Clone or download the server:

   # If using from source
   git clone https://github.com/minimax/websim-mcp-server.git
   cd websim-mcp-server
   

2. Install dependencies:

   npm install
   

3. Run the server:

   npm start
   

Usage with MCP Clients

Smithery Platform

The server is configured for direct deployment on Smithery. See the smithery.json file for deployment configuration.

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "websim": {
      "command": "node",
      "args": ["/path/to/websim-mcp-server/server.js"],
      "env": {}
    }
  }
}

Generic MCP Setup

Use the provided mcp.json configuration file:

# Copy mcp.json to your MCP configuration directory
cp mcp.json ~/.config/claude/mcp-servers/websim.json

📋 Available Tools

Project Management

Tool	Description	Parameters
get_project_by_id	Get project by ID	project_id: string
get_project_by_slug	Get project by user/slug	user: string, slug: string
list_all_projects	List all public projects	limit?: number, offset?: number
list_user_projects	List projects for user	user: string, limit?: number, offset?: number
get_project_revisions	Get project versions	project_id: string, limit?: number, offset?: number
get_project_stats	Get project statistics	project_id: string
get_project_descendants	Get related projects	project_id: string, limit?: number, offset?: number

User Management

Tool	Description	Parameters
get_user	Get user profile	user: string
get_user_stats	Get user statistics	user: string
search_users	Search users	query: string, limit?: number, offset?: number
get_user_following	Get user's follows	user: string, limit?: number, offset?: number
get_user_followers	Get user's followers	user: string, limit?: number, offset?: number

Feed & Discovery

Tool	Description	Parameters
get_trending_feed	Get trending projects	limit?: number, offset?: number
get_posts_feed	Get latest posts	limit?: number, offset?: number
search_feed	Search feed with sorting	sort: string, search: string, limit?: number, offset?: number
get_trending_rooms	Get trending rooms	limit?: number, offset?: number

Assets & Search

Tool	Description	Parameters
search_assets	Search for assets	query: string, limit?: number, offset?: number
bulk_asset_search	Search multiple queries	assets: Array<{query: string, limit?: number}>
search_relevant_assets	Find relevant assets	query: string, limit?: number
get_related_keywords	Get keyword suggestions	query: string, limit?: number
get_top_searches	Get top searches	limit?: number, offset?: number
get_project_assets	Get project assets	project_id: string, version?: string

Comments

Tool	Description	Parameters
get_project_comments	Get project comments	project_id: string, limit?: number, offset?: number
get_comment_replies	Get comment replies	project_id: string, comment_id: string, limit?: number, offset?: number

System

Tool	Description	Parameters
health_check	Check API connectivity	None

💡 Usage Examples

Example 1: Getting a Popular Project

// Tool call example
{
  "tool": "get_project_by_id",
  "arguments": {
    "project_id": "abc123xyz789"
  }
}

Example 2: Browsing Trending Content

// Tool call example
{
  "tool": "get_trending_feed",
  "arguments": {
    "limit": 10,
    "offset": 0
  }
}

Example 3: Searching for Developers

// Tool call example
{
  "tool": "search_users",
  "arguments": {
    "query": "developer",
    "limit": 20,
    "offset": 0
  }
}

Example 4: Finding Assets

// Tool call example
{
  "tool": "search_assets",
  "arguments": {
    "query": "game sprites",
    "limit": 15
  }
}

Example 5: Bulk Asset Search

// Tool call example
{
  "tool": "bulk_asset_search",
  "arguments": {
    "assets": [
      { "query": "game UI", "limit": 5 },
      { "query": "character sprites", "limit": 5 },
      { "query": "sound effects", "limit": 5 }
    ]
  }
}

🔧 Configuration

Environment Variables

Copy .env.example to .env and customize:

# WebSim API Configuration
WEBSIM_API_BASE_URL=https://api.websim.com
WEBSIM_API_TIMEOUT=30000

# Server Configuration
MCP_SERVER_NAME=websim-mcp-server
MCP_SERVER_VERSION=1.0.0

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

Custom API Base URL

If WebSim provides a different API endpoint, update the configuration:

// In server.js, modify the WEBSIM_API_BASE constant
const WEBSIM_API_BASE = 'https://your-custom-api-endpoint.com';

🏥 Health Monitoring

The server includes a built-in health check system:

// Health check tool call
{
  "tool": "health_check",
  "arguments": {}
}

This checks:

• WebSim API connectivity
• Response time
• Error rate monitoring

🔒 Security & Privacy

• No Authentication Required: Uses WebSim's public API endpoints
• No Data Storage: Server doesn't store any user data
• HTTPS Only: All API calls use secure connections
• Input Validation: All parameters are validated before API calls

🐛 Error Handling

The server provides comprehensive error handling:

• Network timeouts: Configurable request timeouts
• API errors: Forwarded error messages with context
• Validation errors: Clear parameter validation feedback
• Recovery mechanisms: Automatic retry logic where appropriate

Common Error Responses

{
  "success": false,
  "error": "Project not found",
  "timestamp": "2025-10-28T01:41:35.000Z"
}

📊 Rate Limiting & Performance

• Built-in timeouts: Prevents hanging requests
• Pagination support: Efficient data retrieval
• Error recovery: Graceful handling of API limits
• Connection pooling: Optimized API call handling

🤝 Contributing

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

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

📝 API Reference

This MCP server wraps the WebSim public API. For detailed API documentation, visit:

• API Base: https://api.websim.com
• Documentation: https://api.websim.com/docs

Supported Endpoints

• GET /api/v1/projects - Project listing
• GET /api/v1/projects/{id} - Project details
• GET /api/v1/users/{user} - User profiles
• GET /api/v1/feed/trending - Trending content
• GET /api/v1/search/assets - Asset search
• And many more...

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the MCP standard
• WebSim for the public API
• Smithery for MCP hosting platform

📞 Support

For issues, questions, or contributions:

• GitHub Issues: Create an issue
• Documentation: WebSim API Docs

---

Built with ❤️ by MiniMax Agent