npm package: @rockymedure/vyb-mcp-server
Description: MCP Server for vyb collaboration platform
Author: vyb Team
Latest version: 1.0.2

# vyb MCP Server 🚀

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the **vyb collaboration platform**. This server provides AI agents with tools to analyze projects, browse collaboration opportunities, and manage project listings on vyb.

## 🌟 Features

### 🔧 **Tools Available**
- **`analyze_project`** - Analyze current project for tech stack, tasks, and collaboration opportunities
- **`suggest_listing`** - Get help creating project listings with natural language recommendations
- **`post_listing`** - Create project listings on vyb to find collaborators
- **`browse_opportunities`** - Find available collaboration projects on vyb
- **`suggest_update`** - Get help updating existing project listings
- **`post_update`** - Update existing project listings with new tasks or changes

### 🤝 **Collaboration Tools** (Coming Soon)
- **`list_active_collaborations`** - View your active collaboration projects
- **`get_collaboration_details`** - Get detailed information about specific collaborations
- **`start_collaboration`** - Mark collaborations as started
- **`submit_task_for_review`** - Submit completed tasks for review

## 📦 No Installation Required! 

This MCP server uses **npx** for automatic installation - no setup needed!

## ⚡ Quick Start

### 1. **Setup Environment**
Copy the example environment file and configure:
```bash
cp env.example .env
```

Edit `.env` with your preferences:
```bash
# vyb MCP Server Configuration
VYB_API_URL=https://vyb.codes
NEXT_PUBLIC_SITE_URL=https://vyb.codes
```

### 2. **Configure MCP Client**
Copy the example MCP configuration:
```bash
cp mcp-config.example.json mcp-config.json
```

For **Cursor IDE**, add to your MCP configuration:
```json
{
  "mcpServers": {
    "vyb": {
      "command": "npx",
      "args": ["@rockymedure/vyb-mcp-server"],
      "env": {
        "VYB_API_KEY": "your_hnd_api_key_here",
        "VYB_API_URL": "https://vyb.codes",
        "NEXT_PUBLIC_SITE_URL": "https://vyb.codes"
      }
    }
  }
}
```

**Get your API key:** Visit [vyb.codes](https://vyb.codes) and complete onboarding to get your personal `hnd_` API key.

### 3. **Start Using**
The MCP server will automatically connect when your AI agent starts. Try these commands with your AI assistant:

- *"Analyze my current project for collaboration opportunities"*
- *"Help me create a project listing on vyb"*
- *"Show me available projects I could collaborate on"*
- *"What collaboration opportunities are available for React developers?"*

## 🤖 AI Agent Integration

This MCP server works with AI agents that support the Model Context Protocol, including:

- **Cursor IDE** - Built-in MCP support
- **Claude Desktop** - With MCP configuration
- **Custom MCP Clients** - Using the official SDK

### Example Agent Interactions

**Project Analysis:**
```
Agent: I'll analyze your project for collaboration opportunities...
Tool: analyze_project → "This Next.js e-commerce project could benefit from..."
```

**Finding Opportunities:**
```
Agent: Let me find React projects you could collaborate on...
Tool: browse_opportunities → Shows available projects with React
```

**Creating Listings:**
```
Agent: I'll help you create a project listing...
Tool: suggest_listing → Provides natural language guidance
Tool: post_listing → Creates the listing on vyb
```

## 🔧 Configuration Options

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VYB_API_URL` | `https://vyb.codes` | vyb API endpoint |
| `NEXT_PUBLIC_SITE_URL` | `https://vyb.codes` | vyb site URL for links |
| `MCP_SERVER_NAME` | `vyb` | MCP server name |
| `MCP_SERVER_VERSION` | `1.0.0` | MCP server version |

### Advanced Configuration

For custom API endpoints or self-hosted vyb instances:
```bash
# Use custom vyb instance
VYB_API_URL=https://your-vyb-instance.com
NEXT_PUBLIC_SITE_URL=https://your-vyb-instance.com
```

## 🛠️ Development

### Running from Source
```bash
git clone https://github.com/vyb/mcp-server.git
cd mcp-server
npm install
node vyb-server.js
```

### Testing Tools
```bash
# Test analyze_project tool
echo '{"tool": "analyze_project", "args": {}}' | node vyb-server.js

# Test browse_opportunities tool  
echo '{"tool": "browse_opportunities", "args": {"your_skills": ["React", "TypeScript"]}}' | node vyb-server.js
```

## 🌐 Platform Integration

This MCP server connects to the **vyb collaboration platform** at [vyb.codes](https://vyb.codes), where developers can:

- **Find Collaborators** - Post projects and find skilled developers
- **Join Projects** - Browse opportunities and apply to collaborate
- **Manage Work** - Track tasks, communicate, and get paid
- **Build Networks** - Connect with other developers in your tech stack

## 📋 API Reference

### Core Tools

#### `analyze_project`
Analyzes the current project directory for collaboration potential.
- **Returns:** Project analysis with tech stack, potential tasks, and recommendations

#### `browse_opportunities` 
Finds available collaboration projects.
- **Parameters:** `your_skills` (array) - Your technical skills
- **Returns:** List of matching projects with details

#### `suggest_listing`
Provides guidance for creating project listings.
- **Parameters:** Project details like name, description, tech stack
- **Returns:** Natural language suggestions and recommendations

#### `post_listing`
Creates a project listing on vyb.
- **Parameters:** Complete listing data
- **Returns:** Confirmation and listing URL

## 🤝 Contributing

We welcome contributions! Please:

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

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- **vyb Platform:** [vyb.codes](https://vyb.codes)
- **MCP Documentation:** [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Issues & Support:** [GitHub Issues](https://github.com/vyb/mcp-server/issues)

---

**Built with ❤️ for the vyb collaboration platform**

*Connect. Collaborate. Create.*