utility-mcp-server 0.1.0

A utility Model Context Protocol (MCP) server

Utility MCP Server

Description

A Model Context Protocol (MCP) server providing utility tools for development workflows. Built with Python and FastMCP, this server offers tools like automated release notes generation from git commits.

Features include structured logging, configuration management, multiple transport protocols (HTTP, SSE, streamable-HTTP), SSL support, and containerized deployment.

Code Structure

utility-mcp-server/
├── utility_mcp_server/           # Main package directory
│   ├── __init__.py
│   ├── src/                       # Core source code
│   │   ├── __init__.py
│   │   ├── main.py               # Application entry point & startup logic
│   │   ├── api.py                # FastAPI application & transport setup
│   │   ├── mcp.py                # MCP server implementation & tool registration
│   │   ├── settings.py           # Pydantic-based configuration management
│   │   └── tools/                # MCP tool implementations
│   │       ├── __init__.py
│   │       ├── release_notes_tool.py  # Release notes generation tool
│   │       └── assets/           # Static resource files
│   └── utils/                    # Shared utilities
│       ├── __init__.py
│       └── pylogger.py          # Structured logging with structlog
├── tests/                        # Comprehensive test suite
│   ├── conftest.py              # Pytest fixtures and configuration
│   ├── test_settings.py         # Unit tests for configuration
│   ├── test_mcp.py              # Unit tests for MCP server
│   ├── test_release_notes_tool.py # Unit tests for release notes tool
│   ├── test_api.py              # Unit tests for API endpoints
│   ├── test_main.py             # Unit tests for main module
│   └── test_integration.py      # Integration tests
├── pyproject.toml               # Project metadata & dependencies
├── Containerfile               # Red Hat UBI-based container build
├── compose.yaml                # Docker Compose orchestration
├── .env.example                # Environment configuration template
├── .gitignore                  # Version control exclusions
├── .pre-commit-config.yaml     # Code quality automation
└── README.md                   # Project documentation

Key Components

• main.py: Application entry point with configuration validation, error handling, and uvicorn server startup
• api.py: FastAPI application setup with transport protocol selection (HTTP/SSE/streamable-HTTP) and health endpoints
• mcp.py: Core MCP server class that registers tools using FastMCP decorators
• settings.py: Environment-based configuration using Pydantic BaseSettings with validation
• tools/: MCP tool implementations for utility operations
• utils/pylogger.py: Structured JSON logging using structlog

Current MCP Tools

1. generate_release_notes: Generates structured release notes from git commits and tags

Release Notes Tool

The generate_release_notes tool automatically creates comprehensive release notes from git commits, categorizing changes into features, enhancements, bug fixes, and breaking changes. See USE_CASES.md for detailed use cases and integration scenarios.

How to Run the Code Locally

Prerequisites

• Python 3.12 or higher
• uv (fast Python package installer and resolver)

Setup

1. Install uv (if not already installed):

   # On macOS/Linux:
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On MacOS using brew
   brew install uv
   
   # On Windows:
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # Or with pip:
   pip install uv
   

2. Clone the repository:

   git clone https://github.com/redhat-data-and-ai/utility-mcp-server
   cd utility-mcp-server
   

3. Create and activate a virtual environment with uv:

   uv venv
   
   # Activate the virtual environment:
   # On macOS/Linux:
   source .venv/bin/activate
   
   # On Windows:
   .venv\Scripts\activate
   

4. Install the package and dependencies:

   # Install in editable mode with all dependencies
   uv pip install -e .
   

5. Configure environment variables:

   cp .env.example .env
   # Edit .env file with your configuration
   

6. Run the server:

   # Using the installed console script
   utility-mcp-server
   
   # Or directly with Python module
   python -m utility_mcp_server.src.main
   
   # Or using uv to run directly
   uv run python -m utility_mcp_server.src.main
   

Configuration Options

The server configuration is managed through environment variables:

Variable	Default	Description
MCP_HOST	0.0.0.0	Server bind address
MCP_PORT	3000	Server port (1024-65535)
MCP_TRANSPORT_PROTOCOL	streamable-http	Transport protocol (http, sse, streamable-http)
MCP_SSL_KEYFILE	None	SSL private key file path
MCP_SSL_CERTFILE	None	SSL certificate file path
PYTHON_LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Using Podman

1. Build and run with Podman Compose:

   podman-compose up --build
   

2. Or build manually:

   podman build -t utility-mcp-server .
   podman run -p 3000:3000 --env-file .env utility-mcp-server
   

Verify Installation

1. Health check:

   curl http://localhost:3000/health
   

2. Test MCP tools:

   # List available tools via MCP endpoint
   curl -X POST "http://localhost:3000/mcp" \
        -H "Content-Type: application/json" \
        -d '{"method": "tools/list"}'
   

How to Test the Code Locally

Development Environment Setup

1. Install development dependencies:

   uv pip install -e ".[dev]"
   

2. Install pre-commit hooks:

   pre-commit install
   

Running Tests

The project includes a comprehensive test suite covering unit tests, integration tests, and various edge cases.

1. Run all tests:

   pytest
   

2. Run tests with coverage reporting:

   pytest --cov=utility_mcp_server --cov-report=html --cov-report=term
   

3. Run tests by category:

   # Unit tests only
   pytest -m unit
   
   # Integration tests only
   pytest -m integration
   
   # Slow running tests
   pytest -m slow
   
   # Tests requiring network access
   pytest -m network
   

4. Run specific test modules:

   # Test individual components
   pytest tests/test_settings.py -v
   pytest tests/test_mcp.py -v
   pytest tests/test_release_notes_tool.py -v
   
   # Run integration tests
   pytest tests/test_integration.py -v
   

5. Run tests with different output formats:

   # Verbose output with detailed test names
   pytest -v
   
   # Short traceback format
   pytest --tb=short
   
   # Quiet output (minimal)
   pytest -q
   

Code Quality Checks

1. Linting and formatting with Ruff:

   # Check for issues
   ruff check .
   
   # Auto-fix issues
   ruff check . --fix
   
   # Format code
   ruff format .
   

2. Type checking with MyPy:

   mypy utility_mcp_server/
   

3. Docstring validation:

   pydocstyle utility_mcp_server/ --convention=google
   

4. Run all pre-commit checks:

   pre-commit run --all-files
   

Test Suite Overview

Test Category	Description
Unit Tests	Individual component testing with mocking
Integration Tests	End-to-end workflow testing

Test Files:

• test_settings.py - Configuration, environment variables, validation
• test_mcp.py - Server initialization, tool registration, error handling
• test_release_notes_tool.py - Release notes generation tool functionality
• test_api.py - API endpoints and health checks
• test_main.py - Main module and server startup
• test_integration.py - Complete workflows and system integration

Manual Testing

1. Container testing:

   docker-compose up -d
   curl -f http://localhost:3000/health
   docker-compose down
   

2. SSL testing (if configured):

   curl -k https://localhost:3000/health
   

Continuous Integration

GitHub Actions runs automated CI on push and PRs:

• Multi-Python version testing (3.12, 3.13)
• Test suite execution with coverage reporting
• Ruff linting and MyPy type checking
• Bandit security scanning

Running CI Checks Locally

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

# Run tests with coverage
pytest --cov=utility_mcp_server --cov-fail-under=80

# Run security checks
bandit -r utility_mcp_server/

How to Contribute

Development Workflow

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Set up development environment:

   uv venv && source .venv/bin/activate
   uv pip install -e ".[dev]"
   pre-commit install
   

4. Make changes and run tests: pytest --cov=utility_mcp_server
5. Run pre-commit checks: pre-commit run --all-files
6. Commit and push, then create a Pull Request

Coding Standards

• Follow PEP 8 (enforced by Ruff)
• Type annotations for public functions
• Google-style docstrings
• Conventional commit format (feat:, fix:, docs:, etc.)

Adding New Tools

1. Create a tool module in utility_mcp_server/src/tools/
2. Register the tool in utility_mcp_server/src/mcp.py using self.mcp.tool()(your_function)
3. Add tests in tests/
4. Update documentation

Getting Help

Open GitHub issues for bugs or feature requests.