openshift-partner-labs-mcp-server

redhat-openshift-partner-labs/openshift-partner-labs-mcp-server

3.1

If you are the rightful owner of openshift-partner-labs-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The OpenShift Partner Labs MCP Server is a backend API layer designed to facilitate AI-driven chatbot interactions for managing OpenShift clusters.

OpenShift Partner Labs MCP Server

A Model Context Protocol (MCP) server designed specifically for OpenShift Partner Labs, providing high-level conversational operations for lab managers, administrators, and developers. This server aggregates low-level database interactions into AI-friendly tools that enable natural language workflows.

CI Status Project Status License

Features

  • FastAPI-based MCP server with multiple transport protocol support (HTTP, SSE, Streamable-HTTP)
  • PostgreSQL integration with connection pooling and async operations
  • OAuth2 authentication with Red Hat SSO (optional via ENABLE_AUTH flag)
  • Container-ready deployment with Red Hat UBI and OpenShift configurations
  • Comprehensive tool system for lab management operations
  • Production-ready with health checks, logging, and monitoring

Tech Stack

  • Language: Python 3.12+
  • Framework: FastAPI with FastMCP (v2.10.4)
  • Database: PostgreSQL with asyncpg/psycopg2-binary
  • Authentication: OAuth2 with Red Hat SSO (configurable)
  • Container: Containerfile optimized for Podman/Red Hat UBI
  • Development Tools: pytest, ruff, mypy, pre-commit hooks

Purpose and Philosophy

This server is not a traditional REST API that provides a one-to-one mapping of database interactions. Instead, its core philosophy is to aggregate low-level interactions into high-level, conversational actions that can be easily used by an AI agent.

The primary goal is to address the challenges of traditional UIs, such as:

  • High development overhead: Reducing the developer "cycles" needed for UI changes.
  • Developer dependency: Empowering users to perform routine operational tasks (like changing a cluster's state) via the agent without needing a developer.
  • Complex workflows: Simplifying processes like cluster provisioning into guided, natural language conversations.

Developers contributing to this server should always consider if they are providing a tool, prompt, or resource that empowers the agent to fulfill a high-level user request, rather than simply exposing a raw backend function.

Architecture

This server functions as the critical API Layer in the AI-driven architecture, connecting conversational agents with OpenShift Partner Labs infrastructure.

[User] <--> [Chat Interface] <--> [AI Agent] <--> [MCP Server] <--> [PostgreSQL Database]
                                                       |
                                                   [OAuth2/SSO]
                                                       |
                                                [Storage Service]

Components

  • MCP Server: FastAPI-based server with multiple transport protocols
  • PostgreSQL Database: Primary data store with connection pooling
  • OAuth2/SSO: Red Hat SSO integration (configurable)
  • Storage Service: File and asset management
  • Tools System: Lab management operations exposed as MCP tools

Prerequisites

  • Python 3.12 or higher
  • uv package manager (install from here)
  • PostgreSQL (for local development)
  • Container runtime: Podman (recommended) or Docker
  • Git for version control

For Red Hat environments:

  • Access to Red Hat SSO (if using authentication)
  • Red Hat certificate bundle (automatically configured in containers)

Installation

From Source

# Clone the repository
git clone <repository-url>
cd openshift-partner-labs-mcp-server

# Create and activate virtual environment
uv venv --python 3.12
source .venv/bin/activate

# Install the package in development mode
uv pip install -e ".[dev]"

# Install Red Hat certificates (if needed)
wget https://certs.corp.redhat.com/certs/Current-IT-Root-CAs.pem \
    && cat Current-IT-Root-CAs.pem >> `python -m certifi`

Environment Configuration

Create a .env file in the project root:

# MCP Server Configuration
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_TRANSPORT_PROTOCOL=http

# Database Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=openshift_partner_labs
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password

# Authentication (optional)
ENABLE_AUTH=false
SSO_CLIENT_ID=your_client_id
SSO_CLIENT_SECRET=your_client_secret

# Logging
PYTHON_LOG_LEVEL=INFO

Configuration Options

  • ENABLE_AUTH: Set to true to enable OAuth2 authentication
  • MCP_TRANSPORT_PROTOCOL: Choose from http, streamable-http, or sse
  • POSTGRES_*: Database connection settings
  • SSO_*: Red Hat SSO integration settings (required if ENABLE_AUTH=true)

Security Considerations

⚠️ IMPORTANT: This server includes an OAuth2 compatibility mode (COMPATIBLE_WITH_CURSOR) that significantly reduces security to accommodate certain clients like Cursor.

Transport Protocol Security

The server supports multiple transport protocols that can be configured via the MCP_TRANSPORT_PROTOCOL environment variable:

  • http/streamable-http: Standard HTTP for request-response communication (both use the same implementation)
  • sse: Server-Sent Events (SSE) for event-driven communication (deprecated)

Note: Both http and streamable-http protocols use the same HTTP implementation and are functionally identical. We recommend using http or streamable-http for most use cases as they provide the best compatibility and performance. The SSE protocol is deprecated and should only be used if specifically required for legacy clients.

Usage

Running Locally

  1. Start PostgreSQL (if not already running):

    # Using the included PostgreSQL container
podman-compose up -d postgres

  2. Start the MCP server:

    # Method 1: Direct Python execution
python -m openshift_partner_labs_mcp_server.src.main

# Method 2: Using installed script (after pip install -e .)
openshift-partner-labs-mcp-server

# Method 3: Container development (recommended)
make dev

# Method 4: Direct container commands
podman-compose up --build

  3. Verify the server is running:

    curl http://localhost:8080/health

Server Endpoints

Once running, the server provides these endpoints:

HTTP Protocol (default):

  • MCP Server: http://localhost:8080/mcp
  • Health Check: http://localhost:8080/health

SSE Protocol (if configured):

  • SSE Endpoint: http://localhost:8080/sse
  • Health Check: http://localhost:8080/health

Available Tools

The server provides these MCP tools for OpenShift Partner Labs operations:

Core Tools

  • multiply_numbers: Mathematical operations and calculations

    • Performs multiplication of numeric values
    • Useful for capacity planning and resource calculations

  • generate_code_review_prompt: Code analysis assistance

    • Generates structured code review prompts
    • Helps with quality assurance workflows

  • get_redhat_logo: Red Hat branding assets

    • Retrieves Red Hat logo and branding materials
    • Supports documentation and UI development

Usage Example

# Using FastMCP client
from fastmcp import FastMCP
import asyncio

async def example():
    client = FastMCP("http://localhost:8080/mcp")
    result = await client.call_tool("multiply_numbers", {"a": 5, "b": 10})
    print(result)  # {"result": 50}

asyncio.run(example())

OpenShift Deployment

The project includes complete OpenShift deployment configurations optimized for Red Hat environments.

Quick Deployment

# Option 1: Use published container images (recommended)
# The openshift/ configurations automatically use the latest published images
oc apply -k openshift/

# Option 2: Deploy specific version
# Edit openshift/kustomization.yaml to specify image version
# images:
#   - name: openshift-partner-labs-mcp-server
#     newName: ghcr.io/mrhillsman/openshift-partner-labs-mcp-server
#     newTag: v0.2.0

# Check deployment status
oc get pods -n <your-namespace>

# View logs
oc logs -f deployment/openshift-partner-labs-mcp-server

Production Endpoints

Once deployed on OpenShift, the server will be available at:

HTTP Protocol:

  • MCP Server: https://openshift-partner-labs-mcp-server.<your-cluster>/mcp
  • Health Check: https://openshift-partner-labs-mcp-server.<your-cluster>/health

SSE Protocol:

  • SSE Endpoint: https://openshift-partner-labs-mcp-server.<your-cluster>/sse

OpenShift Configuration

  • Port: 8443 (HTTPS)
  • SSL: Configured with TLS certificates
  • Resources: 1 CPU, 1Gi memory
  • Health Checks: Liveness and readiness probes configured
  • Image: Red Hat UBI with Python 3.12

Development & Testing

Running Tests

# Using make targets (recommended)
make test                    # Run all tests
make test-cov               # Run tests with coverage (if available)

# Direct pytest commands
pytest                      # Run all tests
pytest --cov=openshift_partner_labs_mcp_server  # Run with coverage
pytest tests/test_tools.py  # Run specific test file
pytest -v                   # Verbose output

Code Quality

Run these commands after making changes:

# Lint and auto-fix issues
ruff check --fix

# Format code
ruff format

# Type checking
mypy .

# Run all pre-commit hooks
pre-commit run --all-files

Container Testing

# Test container build and execution
pytest tests/test_container.py -v

# Option 1: Use pre-built image from GitHub Container Registry
podman run -p 8080:8080 ghcr.io/mrhillsman/openshift-partner-labs-mcp-server:latest

# Option 2: Build container manually
podman build -t openshift-partner-labs-mcp-server .
podman run -p 8080:8080 openshift-partner-labs-mcp-server

Releases

Overview

This project uses automated GitHub Actions workflows for tag-based releases. When you push a version tag, the system automatically:

  • Validates quality: Runs pre-commit hooks, tests, and type checking
  • Builds artifacts: Creates Python packages and multi-platform container images
  • Creates releases: Generates GitHub releases with changelogs and downloadable assets
  • Publishes images: Pushes container images to GitHub Container Registry

Creating a Release

Follow these steps to create a new release:

  1. Update the version in pyproject.toml:

    # Edit pyproject.toml and update the version field
vim pyproject.toml
# Example: version = "0.2.0"

  2. Commit the version change:

    git add pyproject.toml
git commit -m "Bump version to 0.2.0"
git push origin main

  3. Create and push the release tag:

    git tag v0.2.0
git push origin v0.2.0

  4. Monitor the release: GitHub Actions will automatically:

    • Run quality checks and tests
    • Build Python packages and container images
    • Create a GitHub release with generated changelog
    • Publish artifacts for download

Version Guidelines

  • Follow semantic versioning: major.minor.patch (e.g., 1.2.3)
  • Tag format: Always prefix with v (e.g., v0.2.0)
  • Version consistency: The version in pyproject.toml must exactly match the git tag
  • Pre-releases: Versions < 1.0.0 are automatically marked as pre-release

Release Artifacts

Each release produces:

Python Packages:

  • Wheel distribution (.whl)
  • Source distribution (.tar.gz)
  • Available on GitHub Releases page

Container Images:

  • Multi-platform images (linux/amd64, linux/arm64)
  • Published to GitHub Container Registry
  • Tagged with version and latest

Installation Examples:

# Install specific version
pip install openshift-partner-labs-mcp-server==0.2.0

# Use container image
podman run ghcr.io/mrhillsman/openshift-partner-labs-mcp-server:v0.2.0

# Use latest container image
podman run ghcr.io/mrhillsman/openshift-partner-labs-mcp-server:latest

Release Validation

Before creating a release, ensure:

  • All tests pass: pytest
  • Code quality checks pass: ruff check --fix && ruff format
  • Type checking passes: mypy .
  • Pre-commit hooks pass: pre-commit run --all-files

The automated workflow will fail if any of these checks don't pass.

Examples

FastMCP Client

# Run the FastMCP client example
python examples/fastmcp_client.py

This example demonstrates:

  • Connecting to the MCP server
  • Using available tools (multiply_numbers, generate_code_review_prompt, get_redhat_logo)
  • Mathematical operations and code analysis
  • Asset retrieval functionality

LangGraph Integration

# Run the LangGraph client example
python examples/langgraph_client.py

This example shows:

  • LangGraph agent integration
  • Google Gemini model usage
  • Tool calls for mathematical operations
  • Conversational AI workflows

Contributing

We welcome contributions! Please follow these guidelines when contributing to the OpenShift Partner Labs MCP Server:

Development Workflow

  1. Fork and clone the repository
  2. Create a feature branch from main
  3. Install development dependencies: uv pip install -e ".[dev]"
  4. Make your changes following the project's coding standards
  5. Run tests and quality checks: 
    pytest                    # Run all tests
ruff check --fix          # Lint and auto-fix
ruff format              # Format code
mypy .                   # Type checking
pre-commit run --all-files # Run all hooks
  6. Commit your changes with clear, descriptive messages
  7. Submit a pull request with a detailed description

Code Standards

  • Python 3.12+ with type hints encouraged
  • Google docstring convention for all functions
  • Ruff for linting and formatting (enforced by pre-commit)
  • pytest for testing with good coverage
  • Conventional commits for clear change history

Release Guidelines

For maintainers creating releases:

  • Version Updates: Only update versions in pyproject.toml when preparing for release
  • Release Timing: Create releases for significant feature additions, bug fixes, or security updates
  • Version Bumping: Follow semantic versioning:
    • Patch (0.1.1): Bug fixes and minor improvements
    • Minor (0.2.0): New features that are backward compatible
    • Major (1.0.0): Breaking changes or major milestones
  • Pre-release Testing: Ensure all automated checks pass before tagging
  • Release Notes: The automated workflow generates changelogs, but consider adding manual release notes for major releases
  • Container Images: All releases automatically publish multi-platform container images
  • Coordination: For major releases, coordinate with the team and update documentation as needed

Areas for Contribution

  • New MCP tools for OpenShift Partner Labs operations
  • Database integrations and data models
  • Authentication enhancements and security improvements
  • Documentation and usage examples
  • Testing and quality assurance
  • Container and deployment optimizations

For major changes, please open an issue first to discuss the proposed changes.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.