# 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**:
   ```bash
   cd McpServer_Vibe
   ```

2. **Create and activate virtual environment**:
   ```bash
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   uv pip install -e ".[dev]"
   ```

### Configuration

1. **Copy environment template**:
   ```bash
   cp .env.example .env
   ```

2. **Update `.env` with your credentials**:
   ```env
   VIBE_BASE_URL=
   VIBE_ACCESS_TOKEN=
   LOG_LEVEL=INFO
   MCP_TRANSPORT=stdio
   ```

### Running the Server

#### As Python Module
```bash
python -m app.main
```

#### Using uv
```bash
uv run app/main.py
```

#### Using Entry Point
```bash
vibe-mcp
```

## Available Tools

### 1. `get_project_list`
Retrieve all projects from the Vibe system.

**Parameters**:
- `environment` (optional): Environment name (default: "production")

**Example**:
```json
{
  "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):

```json
{
  "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:

```json
{
  "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

```bash
# 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](docs/TESTING.md) for comprehensive testing documentation.

### Linting and Type Checking

```bash
# Lint with ruff
uv run ruff check app/

# Type checking with pyright
uv run pyright app/
```

### Running in Development Mode

```bash
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:

```json
{
  "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:

```bash
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**:
   ```bash
   curl -H "Authorization: Bearer $VIBE_ACCESS_TOKEN" \
     "your_url_here"
   ```

2. **Check VPN/Proxy** if required for your network

3. **Enable debug logging**:
   ```bash
   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**:
   ```bash
   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