utility-mcp-server 0.2.0

A utility Model Context Protocol (MCP) server with remote repository support

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
   • Remote Repository Support: Fetch commits from GitHub/GitLab via API (no local clone needed)
   • Local Repository Support: Fallback to local git repositories via subprocess
   • AI Agent Integration: Returns structured data for intelligent AI-driven categorization
   • Provider Pattern: Extensible architecture for adding new git hosting services

Release Notes Tool

The generate_release_notes tool automatically creates comprehensive release notes from git commits. It supports both remote repositories (GitHub, GitLab) and local repositories, with optional AI agent integration for intelligent categorization.

Remote Repository Support

The tool can fetch commits directly from GitHub and GitLab repositories without requiring a local clone:

GitHub:

• Provide repo_url like https://github.com/owner/repo
• Optionally provide github_token (or set GITHUB_TOKEN environment variable)
• Uses PyGithub API to fetch commits and PR associations

GitLab:

• Provide repo_url like https://gitlab.com/owner/repo
• Optionally provide gitlab_token (or set GITLAB_TOKEN environment variable)
• Uses python-gitlab API to fetch commits and MR associations

Local Repository (fallback):

• Provide repo_path to a local git repository
• Uses git subprocess commands

AI Agent Integration

The tool returns structured commit data with embedded AI instructions for intelligent categorization:

• Returns raw commit list with hashes, messages, authors, dates, and PR/MR numbers
• Includes ai_instructions field with comprehensive guidance on categorization
• Instructions travel with data - ensures consistent categorization across all AI agents
• AI creates dynamic categories based on actual changes instead of predefined patterns
• Better context understanding than regex-based categorization

Example response structure:

result = await generate_release_notes(
    version="v1.0.0",
    previous_version="v0.9.0",
    repo_url="https://github.com/owner/repo"
)

# Returns:
{
    "status": "success",
    "data": {
        "commits": [...],
        "version": "v1.0.0",
        ...
    },
    "ai_instructions": {
        "role": "release_notes_categorizer",
        "task": "Analyze commits and create intelligent release notes",
        "guidelines": [
            "Create dynamic categories based on actual changes",
            "Group related commits intelligently",
            "Understand context beyond pattern matching",
            ...
        ],
        "categorization_strategy": {...},
        "suggested_sections": {...},
        "output_format": {...}
    }
}

Why instructions are embedded:

• ✅ Instructions version-controlled with tool
• ✅ Consistent categorization across all workflows
• ✅ Self-documenting - AI knows how to use the data
• ✅ No need to duplicate instructions in each workflow

See USE_CASES.md for detailed use cases and integration scenarios.

Installation

From PyPI (Recommended)

Install the package directly from PyPI:

# Using pip
pip install utility-mcp-server

# Using uv (recommended)
uv pip install utility-mcp-server

From Source

For development or to get the latest changes:

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

Using with Cursor IDE

The MCP server integrates with Cursor IDE using the STDIO transport protocol.

Quick Setup

1. Install the package:

   pip install utility-mcp-server
   

2. Configure Cursor:

   • Open Cursor Settings (Cmd+, on Mac / Ctrl+, on Windows/Linux)
   • Navigate to Tools & Integrations → MCP Tools
   • Click Add MCP Server and add the following configuration:

   {
     "mcpServers": {
       "utility-mcp-server": {
         "command": "utility-mcp-server-stdio",
         "args": []
       }
     }
   }
   

3. Restart Cursor to load the MCP server

Alternative Configuration (if command not in PATH)

If you encounter spawn utility-mcp-server-stdio ENOENT error:

{
  "mcpServers": {
    "utility-mcp-server": {
      "command": "python",
      "args": ["-m", "utility_mcp_server.src.stdio_main"]
    }
  }
}

Or with a virtual environment:

{
  "mcpServers": {
    "utility-mcp-server": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "utility_mcp_server.src.stdio_main"]
    }
  }
}

For detailed setup instructions and troubleshooting, see CURSOR_SETUP.md.

Using with Claude Desktop

The MCP server can also be used with Claude Desktop application.

Setup

1. Install the package:

   pip install utility-mcp-server
   

2. Locate the Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

3. Add the MCP server configuration:

   {
     "mcpServers": {
       "utility-mcp-server": {
         "command": "utility-mcp-server-stdio",
         "args": []
       }
     }
   }
   

   Or if the command is not in your PATH:

   {
     "mcpServers": {
       "utility-mcp-server": {
         "command": "python",
         "args": ["-m", "utility_mcp_server.src.stdio_main"]
       }
     }
   }
   

4. Restart Claude Desktop to load the MCP server

Using the Release Notes Tool

Once configured, you can use the generate_release_notes tool in your conversations:

"Generate release notes for version v1.0.0 comparing with v0.9.0 for the repository at /path/to/repo"

The tool will analyze git commits between the specified tags and generate structured release notes with categorized changes.

Usage Examples

Remote GitHub Repository

# Using with AI agent integration
result = await generate_release_notes(
    version="v1.0.0",
    previous_version="v0.9.0",
    repo_url="https://github.com/owner/repo",
    github_token=os.getenv('GITHUB_TOKEN'),  # Optional, but recommended
    return_raw_data=True  # Returns structured data for AI processing
)

# Standard formatted output
result = await generate_release_notes(
    version="v1.0.0",
    previous_version="v0.9.0",
    repo_url="https://github.com/owner/repo",
    github_token=os.getenv('GITHUB_TOKEN')
)

Remote GitLab Repository

result = await generate_release_notes(
    version="v2.0.0",
    previous_version="v1.5.0",
    repo_url="https://gitlab.com/owner/repo",
    gitlab_token=os.getenv('GITLAB_TOKEN')  # Optional for public repos
)

Local Repository

# Existing behavior - still fully supported
result = await generate_release_notes(
    version="v1.0.0",
    previous_version="v0.9.0",
    repo_path="/path/to/local/repo"
)

Running as HTTP Server

For development, testing, or integration with other tools, you can run the MCP server as an HTTP service.

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
   

HTTP Server Configuration

The HTTP 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.