mcp-jenkins: Instructions file for Codex

mcp-jenkins

Bridges Jenkins CI with AI language models via Anthropic's Model Context Protocol (MCP). Jenkins operations are exposed as MCP tools that LLM clients invoke.

Build and Test

# Install (requires uv)
uv sync --group dev

# Run tests with coverage
uv run pytest --cov=src

# Lint and format
uv run ruff check .
uv run ruff format .

# Pre-commit (runs tests + ruff)
pre-commit run --all-files

Architecture

src/mcp_jenkins/
├── __init__.py          # CLI entry point (click)
├── core/                # Lifespan context + ASGI auth middleware
├── jenkins/             # Jenkins REST client + URL templates + Pydantic models
└── server/              # MCP tool definitions (@mcp.tool decorators)

Credential resolution (in core/lifespan.py): session singleton cache → HTTP request headers (x-jenkins-url, x-jenkins-username, x-jenkins-password) → env vars set from CLI args. Always call jenkins(ctx) inside tool functions to obtain the client; never instantiate Jenkins directly.

Read-only mode: Tools that mutate Jenkins state must carry tags=['write']. Tools tagged 'read' remain available when --read-only is passed. Every new tool must have exactly one of these two tags.

Conventions

Adding a new MCP tool

1. Add the function in the appropriate server/*.py module (or create a new module and import it in server/__init__.py).
2. Decorate with @mcp.tool(tags=['read']) or @mcp.tool(tags=['write']).
3. First argument must be ctx: Context; all subsequent arguments are keyword-only domain params.
4. Return model.model_dump(exclude_none=True) (or a list / dict of such).
5. Use jenkins(ctx) to get the Jenkins client — never store it in module-level state.

from mcp_jenkins.server import mcp
from mcp_jenkins.core import jenkins

@mcp.tool(tags=['read'])
async def get_something(ctx: Context, fullname: str) -> dict:
    """Short description.

    Args:
        ctx: MCP context.
        fullname: Full job name, e.g. "folder/job".

    Returns:
        Serialised model dict.
    """
    return jenkins(ctx).get_something(fullname=fullname).model_dump(exclude_none=True)