# OpenShift LightSpeed MCP Server

A Model Context Protocol (MCP) server that integrates OpenShift LightSpeed capabilities with Claude Code, enabling AI-powered OpenShift assistance and troubleshooting.

## Overview

This MCP server provides Claude Code with access to OpenShift LightSpeed, allowing users to get expert OpenShift guidance, troubleshooting help, and best practices directly within their development workflow.

## Features

- **OpenShift Expertise**: Get answers to OpenShift-related questions and troubleshooting guidance
- **Seamless Integration**: Works directly within Claude Code for enhanced development experience
- **Configurable**: Flexible configuration for different OpenShift LightSpeed deployments
- **Error Handling**: Robust error handling and timeout management

## Installation

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- Access to an OpenShift LightSpeed API endpoint

### Setup

1. **Clone and install dependencies:**
   ```bash
   cd ols-mcp
   uv sync
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your OLS API configuration
   ```

3. **Test the server:**
   ```bash
   uv run python -m ols_mcp.server
   ```

## Configuration

### Environment Variables

Configure the server using environment variables or a `.env` file:

| Variable | Description | Default |
|----------|-------------|---------|
| `OLS_API_URL` | OpenShift LightSpeed API endpoint | `http://localhost:8080` |
| `OLS_API_TOKEN` | Bearer token for authentication | *None* (required for most deployments) |
| `OLS_TIMEOUT` | Request timeout in seconds | `30.0` |
| `OLS_VERIFY_SSL` | SSL certificate verification | `true` |

### Example `.env` file:
```bash
OLS_API_URL=https://your-ols-instance.com
OLS_API_TOKEN=your-bearer-token-here
OLS_TIMEOUT=30.0
OLS_VERIFY_SSL=true
```

## Claude Code Integration

To use this MCP server with Claude Code, add it to your Claude Code configuration:

### Configuration File Location

- **Linux/macOS**: `~/.config/claude-code/config.json`
- **Windows**: `%APPDATA%\claude-code\config.json`

### Configuration Example

Add the following to your `config.json`:

```json
{
  "mcpServers": {
    "openshift-lightspeed": {
      "command": "uv",
      "args": ["run", "python", "-m", "ols_mcp.server"],
      "cwd": "/path/to/your/ols-mcp",
      "env": {
        "OLS_API_URL": "https://your-ols-instance.com",
        "OLS_API_TOKEN": "your-token-here",
        "OLS_TIMEOUT": "30.0",
        "OLS_VERIFY_SSL": "true"
      }
    }
  }
}
```

**Important**: Update the `cwd` path to point to your actual `ols-mcp` directory.

### Verification

1. Restart Claude Code after adding the configuration
2. The `openshift-lightspeed` tool should now be available
3. Test with OpenShift-related questions

## Usage Examples

Once integrated with Claude Code, you can ask questions like:

- "Help me troubleshoot a pod that's failing to start"
- "How do I scale a deployment in OpenShift?"
- "My application is getting 503 errors, what should I check?"
- "Show me how to create a route for my service"
- "What's the best way to configure resource limits?"

Claude Code will automatically use the OpenShift LightSpeed MCP server to provide expert OpenShift guidance.

## Development

### Project Structure

```
ols-mcp/
├── pyproject.toml              # uv project configuration
├── .env.example               # Environment configuration template
├── src/ols_mcp/
│   ├── __init__.py
│   ├── models.py              # Pydantic models for requests/responses
│   ├── client.py              # HTTP client for OLS API communication
│   └── server.py              # MCP server implementation
└── README.md                  # This file
```

### Available Tools

The server provides the following MCP tool:

- **`openshift-lightspeed`**: Submit queries to OpenShift LightSpeed and receive expert guidance

### Error Handling

The server includes comprehensive error handling for:
- Network connectivity issues
- API authentication failures
- Timeout scenarios
- Invalid responses
- SSL certificate problems

## Troubleshooting

### Common Issues

1. **Connection Refused**: Check that `OLS_API_URL` is correct and the service is running
2. **Authentication Errors**: Verify your `OLS_API_TOKEN` is valid and has proper permissions
3. **SSL Errors**: For self-signed certificates, set `OLS_VERIFY_SSL=false`
4. **Timeout Issues**: Increase `OLS_TIMEOUT` for slower networks

### Debug Mode

Run the server with debug logging:
```bash
DEBUG=1 uv run python -m ols_mcp.server
```

## Contributing

This project uses:
- [uv](https://docs.astral.sh/uv/) for dependency management
- [Pydantic](https://docs.pydantic.dev/) for data validation
- [httpx](https://www.python-httpx.org/) for HTTP client functionality
- [MCP SDK](https://modelcontextprotocol.io/) for protocol implementation

## License

This project is part of the OpenShift ecosystem and follows Red Hat's open source practices.