Vibe MCP Server

Enterprise-grade Model Context Protocol (MCP) server for the Vibe APIs, enabling seamless AI agent integration with production-ready architecture.

Features

• Enterprise Architecture: Modular, scalable, and maintainable codebase
• Production-Ready: Comprehensive error handling, logging, and monitoring
• Async/Await: Full async implementation for high performance
• Type Safety: Pydantic models for all request/response validation
• Retry Logic: Automatic exponential backoff for transient failures
• Observability: Structured JSON logging for debugging and monitoring
• Connection Pooling: Efficient HTTP client with connection reuse
• Token Management: Secure Bearer token authentication

Architecture

app/
├── config/              # Configuration management
│   └── settings.py      # Environment-based settings
├── core/                # Core infrastructure
│   ├── constants.py     # Centralized constants
│   ├── exceptions.py    # Application exception hierarchy
│   ├── http_client.py   # Reusable HTTP client with retries
│   ├── lifecycle.py     # Application startup/shutdown
│   └── logging.py       # Structured logging configuration
├── models/              # Pydantic request/response models
│   ├── activity.py
│   ├── bucket.py
│   ├── code.py
│   ├── project.py
│   └── repository.py
├── services/            # Business logic layer
│   └── vibe_api.py      # High-level Vibe API client
├── tools/               # MCP tool implementations
│   └── vibe_tools.py    # Tool wrappers for MCP
└── main.py              # MCP server entry point

Quick Start

Prerequisites

• Python 3.12+
• uv package manager
• .env file with configuration

Installation

1. Clone and navigate to the project:

   cd McpServer_Vibe

2. Create and activate virtual environment:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   uv pip install -e ".[dev]"

Configuration

1. Copy environment template:

   cp .env.example .env

2. Update .env with your credentials:

   VIBE_BASE_URL=
   VIBE_ACCESS_TOKEN=
   LOG_LEVEL=INFO
   MCP_TRANSPORT=stdio

Running the Server

As Python Module

python -m app.main

Using uv

uv run app/main.py

Using Entry Point

vibe-mcp

Available Tools

1. get_project_list

Retrieve all projects from the Vibe system.

Parameters:

• environment (optional): Environment name (default: "production")

Example:

{
  "environment": "production"
}

2. create_repo

Create a new repository in the Vibe system.

Parameters:

• repo_id (required): Unique repository ID
• project_id (required): Associated project ID
• repo_name (required): Repository name
• repo_description (optional): Repository description
• functional_area (optional): Functional area
• allow_ui_execution (optional): UI execution flag (0 or 1)
• sync_status (optional): Sync status
• comments (optional): Additional comments
• version_id (optional): Version ID

3. create_bucket

Create a bucket for test execution organization.

Parameters:

• bucket_id (required): Unique bucket ID
• execution_order (required): Execution order
• bucket_name (required): Bucket name
• bucket_description (optional): Description
• functional_area (optional): Functional area
• bucket_type (optional): Bucket type
• version_id (optional): Version ID
• repo_id (optional): Repository ID
• environment (optional): Environment name

4. get_activity

Retrieve activity details by bucket ID.

Parameters:

• bucket_id (required): Bucket ID
• version_id (required): Version ID
• environment (optional): Environment name

5. get_code

Retrieve code/script by query ID.

Parameters:

• query_id (required): Query/Code ID
• version_id (required): Version ID

6. health_check

Verify Vibe API server health and accessibility.

Parameters: None

Integration with AI Clients

Claude Desktop

1. Create/update Claude config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "vibe": {
      "command": "python",
      "args": ["-m", "app.main"],
      "env": {
        "VIBE_BASE_URL": "your_url_here",
        "VIBE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

2. Restart Claude Desktop to load the MCP server.

Cursor

Similar configuration as Claude Desktop, update your Cursor MCP settings.

VS Code with MCP Extension

Install the MCP Client extension and add to your settings:

{
  "mcp.servers": {
    "vibe": {
      "command": "python",
      "args": ["-m", "app.main"],
      "env": {
        "VIBE_BASE_URL": "your_url_here",
        "VIBE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Environment Configuration

All configuration is managed through environment variables in .env file:

Variable	Default	Description
VIBE_BASE_URL	your_url_here	Vibe API base URL
VIBE_ACCESS_TOKEN	Required	Bearer token for authentication
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
VIBE_MAX_RETRIES	3	Max retry attempts for failed requests
VIBE_RETRY_BACKOFF_SECONDS	0.5	Initial backoff time (exponential)
MCP_TRANSPORT	stdio	MCP transport (stdio, sse)
MCP_HOST	0.0.0.0	MCP server host
MCP_PORT	9000	MCP server port
ENABLE_HEALTH_CHECK	true	Enable health check tool
ENABLE_METRICS	true	Enable metrics collection

Development

Running Tests

# Install dev dependencies
uv sync --extra dev

# Run all tests
uv run pytest tests/ -v

# Run with coverage report
uv run pytest tests/ --cov=app --cov-report=html

# Run specific test
uv run pytest tests/test_vibe_server.py::TestHttpClient -v

See TESTING.md for comprehensive testing documentation.

Linting and Type Checking

# Lint with ruff
uv run ruff check app/

# Type checking with pyright
uv run pyright app/

Running in Development Mode

LOG_LEVEL=DEBUG uv run app/main.py

Error Handling

The server implements enterprise-grade error handling:

• VibeAuthenticationError: Invalid or expired token (HTTP 401)
• VibeNotFoundError: Resource not found (HTTP 404)
• VibeValidationError: Request validation failure
• VibeTimeoutError: Request timeout
• VibeConnectionError: Network connectivity issues

All errors are automatically logged with structured context for debugging.

Retry Mechanism

Failed requests are automatically retried with exponential backoff:

• Max retries: Configurable (default: 3)
• Backoff multiplier: Exponential (1, 2, 4, 8 seconds)
• Retryable errors: Timeouts, connection errors, server errors
• Non-retryable: Authentication errors (401), validation errors

Logging

Structured JSON logging provides detailed observability:

{
  "event": "HTTP request successful",
  "timestamp": "2024-05-19T10:30:45.123456Z",
  "level": "info",
  "logger": "http_client",
  "method": "GET",
  "endpoint": "/api/Project/GetProjectList",
  "status_code": 200
}

Enable debug logging for detailed request/response traces:

LOG_LEVEL=DEBUG python -m app.main

Performance Considerations

• Connection Pooling: HTTP client maintains persistent connections (10 max)
• Timeout Configuration: 30-second request timeout, 10-second connect timeout
• Async Processing: All operations are async for concurrent execution
• Memory Efficiency: Structured streaming responses for large datasets

Security

• Token Handling: Bearer tokens are stored securely in SecretStr and never logged
• HTTPS: All connections use HTTPS by default
• Input Validation: All inputs validated against Pydantic models
• Output Sanitization: Responses are validated before returning to clients

Troubleshooting

Connection Issues

1. Verify network connectivity:

   curl -H "Authorization: Bearer $VIBE_ACCESS_TOKEN" \
     "your_url_here"

2. Check VPN/Proxy if required for your network

3. Enable debug logging:

   LOG_LEVEL=DEBUG python -m app.main

Authentication Errors

1. Verify token is valid and not expired
2. Check token format: Should be Bearer <token>
3. Ensure .env file is loaded:

   cat .env | grep VIBE_ACCESS_TOKEN

Timeout Issues

1. Increase timeout in production (edit http_client.py)
2. Check network latency to Vibe API
3. Reduce concurrent requests if hitting rate limits

Contributing

For contributing to this project:

1. Follow PEP 8 style guide
2. Add type annotations to all functions
3. Write tests for new features
4. Update documentation
5. Run linting and type checks before submitting

License

This project is proprietary and maintained by the engineering team.

Support

For issues or questions:

1. Check the troubleshooting section
2. Review structured logs for error context
3. Contact the engineering team with:
   • Error message and stack trace
   • Relevant log output
   • Steps to reproduce the issue