### Setup Local Development Environment

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/CONTRIBUTING.md

Commands to install dependencies, configure git templates, and initialize pre-commit hooks for local development.

```shell
pip install uv

uv sync --all-groups

git config commit.template .gitmessage.txt

# UT and ruff pre-commit hooks
pre-commit install

# You can also run pre-commit checks and tests manually:
pre-commit run --all-files
uv run pytest --cov=src
```

--------------------------------

### Test Minimal mcp-jenkins Setup

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Run mcp-jenkins with the most basic configuration to test its core functionality. This example disables SSL verification for testing purposes.

```bash
mcp-jenkins \
  --jenkins-url http://localhost:8080 \
  --jenkins-username admin \
  --jenkins-password admin \
  --transport stdio \
  --no-jenkins-verify-ssl
```

--------------------------------

### Install Dependencies

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/AGENTS.md

Installs project dependencies using uv. Requires uv to be installed.

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

--------------------------------

### Bake usage examples

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Comprehensive examples for using the bake.sh script for various build and cache scenarios.

```bash
# Show help
./bake.sh --help

# Build production image
./bake.sh

# Build development image
./bake.sh mcp-jenkins-dev

# Multi-architecture build
./bake.sh mcp-jenkins-multi

# Build with registry push
./bake.sh --tag v1.0.0 --registry ghcr.io/your-org --push

# Build with caching
./bake.sh --cache-from gha --cache-to gha

# Preview build configuration
./bake.sh --print

# Build all targets
./bake.sh all
```

--------------------------------

### Install MCP Jenkins with uv

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

Install the mcp-jenkins package using uv, the recommended package installer.

```shell
pip install uv
uvx mcp-jenkins
```

--------------------------------

### Get All Installed Plugins

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieve a list of all installed plugins. Set 'depth' to 2 to include plugin dependencies.

```python
plugins = client.get_plugins(depth=2)
for plugin in plugins:
    print(f"{plugin['shortName']}: {plugin['version']}")
```

--------------------------------

### Start MCP Jenkins Server

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/README.md

Start the MCP Jenkins server with specified Jenkins URL, username, and API token. This command configures the server to connect to your Jenkins instance.

```bash
mcp-jenkins --jenkins-url https://jenkins.example.com \
  --jenkins-username admin \
  --jenkins-password api-token
```

--------------------------------

### Start MCP Server for Integration Tests

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Command to start the MCP Jenkins server for integration testing against a real Jenkins instance.

```bash
# Start MCP server
mcp-jenkins --jenkins-url https://jenkins.example.com \
  --jenkins-username admin \
  --jenkins-password token

# In another terminal, run tests
pytest tests/ -v
```

--------------------------------

### Run MCP Jenkins with streamable-http

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

Start the mcp-jenkins server using uvx with streamable-http transport.

```shell
uvx mcp-jenkins --transport streamable-http
```

--------------------------------

### Install MCP Jenkins with pip

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

Install the mcp-jenkins package using pip and run the command.

```shell
pip install mcp-jenkins
mcp-jenkins
```

--------------------------------

### VSCode Copilot Chat Server Start Command

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Command to start the MCP Jenkins server for VSCode Copilot Chat integration using the streamable HTTP transport.

```bash
mcp-jenkins --transport streamable-http
```

--------------------------------

### Show Installed Package Information

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Retrieve detailed information about the installed mcp-jenkins package using pip.

```bash
pip show mcp-jenkins
```

--------------------------------

### Get All Plugins

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of all installed plugins in Jenkins. Optionally accepts a depth parameter to include dependencies.

```python
get_all_plugins()
get_all_plugins(depth=2)
```

--------------------------------

### Start MCP Server in Read-Only Mode

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Command to start the MCP Jenkins server in read-only mode. Includes an example of attempting a write operation, which should fail.

```bash
# Start server in read-only mode
mcp-jenkins --read-only \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username admin \
  --jenkins-password token

# Try write operation - should fail
curl -X POST http://localhost:9887/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"build_item",
      "arguments":{"fullname":"test-job","build_type":"build"}
    }
  }'

# Expected: tool not found or unavailable error
```

--------------------------------

### Local Development Configuration

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/configuration.md

Example configuration for local development using stdio transport. Sets Jenkins URL, username, and password.

```bash
mcp-jenkins --jenkins-url http://localhost:8080 \
  --jenkins-username admin --jenkins-password admin123 \
  --transport stdio
```

--------------------------------

### Get Plugins with Backup Versions

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches a list of plugins that have available backup versions, indicating they can be downgraded. No parameters are required.

```python
get_plugins_with_backup()
```

--------------------------------

### Basic Tool Call via curl

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/endpoints.md

Example of executing a tool named 'get_all_items' using the /mcp endpoint with necessary authentication headers.

```bash
curl -X POST http://localhost:9887/mcp \
  -H "Content-Type: application/json" \
  -H "x-jenkins-url: https://jenkins.example.com" \
  -H "x-jenkins-username: admin" \
  -H "x-jenkins-password: token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_all_items",
      "arguments": {}
    }
  }'
```

--------------------------------

### Check mcp-jenkins Version

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Display the installed version of the mcp-jenkins tool.

```bash
mcp-jenkins --version
```

--------------------------------

### Get Plugins with Problems

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of plugins that have dependency issues or other problems. No parameters are required.

```python
get_plugins_with_problems()
```

--------------------------------

### Get Build Parameters

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieves the parameters used for a specific build. Use this to inspect the configuration of a past build.

```python
def get_build_parameters(
    self,
    *,
    fullname: str,
    number: int,
) -> dict:
```
params = client.get_build_parameters(fullname="my-job", number=42)
# {'ENV': 'production', 'BRANCH': 'main'}
```

--------------------------------

### Install MCP Jenkins with Docker

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

Pull the latest Docker image and run the container, exposing port 9887 for streamable-http transport.

```shell
docker pull ghcr.io/lanbaoshen/mcp-jenkins:latest
docker run -p 9887:9887 --rm ghcr.io/lanbaoshen/mcp-jenkins:latest --transport streamable-http
```

--------------------------------

### Get All Views

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of all top-level views configured in Jenkins. No parameters are required.

```python
get_all_views()
```

--------------------------------

### Production Configuration with SSE

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/configuration.md

Example configuration for production using SSE transport. Includes Jenkins URL, username, password (as an environment variable), timeout, SSL verification, and port.

```bash
mcp-jenkins --jenkins-url https://jenkins.example.com \
  --jenkins-username cicd --jenkins-password $JENKINS_TOKEN \
  --jenkins-timeout 30 \
  --jenkins-verify-ssl \
  --transport sse \
  --port 9887
```

--------------------------------

### Build and Run MCP Jenkins with Docker

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/README.md

Commands to build the project using Docker Bake and start the service using Docker Compose from the project root.

```bash
# Build using Docker Bake (recommended)
./bake.sh

# Run with Docker Compose (from project root - .env file automatically sets COMPOSE_FILE)
docker-compose up mcp-jenkins
```

--------------------------------

### Tool Call with Parameters via curl

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/endpoints.md

Example of executing a tool named 'get_item' with a specific parameter 'fullname' using the /mcp endpoint.

```bash
curl -X POST http://localhost:9887/mcp \
  -H "Content-Type: application/json" \
  -H "x-jenkins-url: https://jenkins.example.com" \
  -H "x-jenkins-username: admin" \
  -H "x-jenkins-password: token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_item",
      "arguments": {
        "fullname": "my-job"
      }
    }
  }'
```

--------------------------------

### Run MCP Jenkins server with SSE transport

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

Start the mcp-jenkins server using uvx with specified Jenkins credentials and SSE transport.

```shell
uvx mcp-jenkins \
  --jenkins-url xxx \
  --jenkins-username xxx  \
  --jenkins-password xxx \
  --transport sse
```

--------------------------------

### Get All Build Artifacts

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Retrieve a list of all artifacts for a given build. Requires the job name and build number.

```bash
mcp-jenkins-cli << 'EOF' {
  "method": "tools/call",
  "params": {
    "name": "get_all_build_artifacts",
    "arguments": {
      "fullname": "build-job",
      "number": 42
    }
  }
}
EOF
```

--------------------------------

### Get Plugins with Updates

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of plugins for which updates are available. Optionally accepts a depth parameter.

```python
get_plugins_with_updates()
```

--------------------------------

### Get Node Configuration

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Fetch the XML configuration for a specific node. This is useful for inspecting or backing up node settings.

```python
config = client.get_node_config(name="agent-1")
```

--------------------------------

### Get All Top-Level Views

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/mcp-server.md

Retrieves a list of all top-level views configured in Jenkins. Returns views with their names and URLs.

```python
@mcp.tool(tags=['read'])
async def get_all_views(ctx: Context) -> list[dict]:
```

--------------------------------

### Get All Node Statuses

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Fetch the status of all nodes in the Jenkins environment. This command requires no arguments.

```bash
mcp-jenkins-cli << 'EOF' {
  "method": "tools/call",
  "params": {
    "name": "get_all_nodes",
    "arguments": {}
  }
}
EOF
```

--------------------------------

### Successful Tool Execution Response Format

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/endpoints.md

Example JSON structure for a successful tool execution response, including the result data.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<response data>"
      }
    ]
  }
}
```

--------------------------------

### get_plugins()

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieves a list of all installed plugins in Jenkins. The depth parameter determines whether to include plugin dependencies in the response.

```APIDOC
## get_plugins()

### Description
Get all installed plugins.

### Method
GET (assumed, based on function name and typical SDK patterns)

### Endpoint
/plugins/api/json (assumed, based on function name and typical SDK patterns)

### Parameters
#### Query Parameters
- **depth** (int) - Optional - Depth (0=basic, 2=with dependencies). Defaults to 0.

### Response
#### Success Response (200)
- **list[dict]** - List of plugin dictionaries

### Response Example
```json
[
  {
    "shortName": "git",
    "version": "4.10.0"
  }
]
```
```

--------------------------------

### Get Plugin by Short Name

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches details for a specific plugin using its short name. Optionally accepts a depth parameter.

```python
get_plugin(short_name="git")
```

--------------------------------

### get_all_plugins

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of all installed plugins in Jenkins. The depth parameter can be used to include plugin dependencies in the response.

```APIDOC
## get_all_plugins

### Description
Get all installed plugins.

### Parameters
#### Query Parameters
- **depth** (int) - Optional - Response depth; 2 = with dependencies (default: 2)

### Request Example
```python
get_all_plugins()
get_all_plugins(depth=2)
```
```

--------------------------------

### Get Plugins with Problems

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/mcp-server.md

Retrieves a list of plugins that have dependency issues or other problems. This helps in identifying and resolving plugin conflicts.

```python
async def get_plugins_with_problems(ctx: Context) -> list[dict]:
```

--------------------------------

### Get Build Queue

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieves the current build queue, listing items waiting to be executed. Use this to monitor job scheduling.

```python
def get_queue(self, *, depth: int = 1) -> Queue:
```
queue = client.get_queue()
for item in queue.items:
    print(f"Queue {item.id}: {item.task.fullDisplayName}")
```

--------------------------------

### Get All Queue Items

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches a list of all items currently present in the Jenkins build queue. No parameters are required.

```python
get_all_queue_items()
```

--------------------------------

### Kubernetes Liveness Probe Example

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

This YAML configuration demonstrates how to set up a Kubernetes liveness probe for the MCP Jenkins health check endpoint. It specifies the path, port, and timing for the probe.

```yaml
livenessProbe:
  httpGet:
    path: /healthz
    port: 9887
  initialDelaySeconds: 5
  periodSeconds: 10
```

--------------------------------

### Get All Currently Running Builds

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of all builds that are currently in progress on the Jenkins instance. No parameters are required.

```python
builds = await get_running_builds(ctx)
```

--------------------------------

### Docker Deployment Configuration

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/configuration.md

Example configuration for deploying MCP Jenkins using Docker. Sets environment variables for Jenkins credentials and maps the port. Uses streamable-http transport.

```bash
docker run -e JENKINS_URL=https://jenkins.example.com \
  -e JENKINS_USERNAME=user \
  -e JENKINS_PASSWORD=token \
  -p 9887:9887 \
  ghcr.io/lanbaoshen/mcp-jenkins:latest \
  --transport streamable-http
```

--------------------------------

### Get View by Path

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches a specific Jenkins view using its slash-separated path. Optionally accepts a response depth parameter.

```python
get_view(view_path="frontend")
get_view(view_path="frontend/nightly")
```

--------------------------------

### Check Build Status of a Job

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Get the status of a specific job. Only the job's full name is required.

```bash
mcp-jenkins-cli << 'EOF' {
  "method": "tools/call",
  "params": {
    "name": "get_build",
    "arguments": {
      "fullname": "my-job"
    }
  }
}
EOF
```

--------------------------------

### Get Specific Build Information

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Retrieve details for a specific build number of a pipeline. The pipeline name and build number are required.

```bash
mcp-jenkins-cli << 'EOF' {
  "method": "tools/call",
  "params": {
    "name": "get_build",
    "arguments": {
      "fullname": "deploy-pipeline",
      "number": 42
    }
  }
}
EOF
```

--------------------------------

### Get Build Test Report

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Fetches the test report for a given build. Useful for analyzing test results of a specific build.

```python
def get_build_test_report(
    self,
    *,
    fullname: str,
    number: int,
    depth: int = 0,
) -> dict:
```
report = client.get_build_test_report(fullname="my-job", number=42)
print(f"Total tests: {report.get('totalCount')}")
print(f"Failures: {report.get('failCount')}")
```

--------------------------------

### Access build script help

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Display available options for the bake.sh build script.

```bash
./bake.sh --help
```

--------------------------------

### Common build use cases

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Standard commands for development, production, and multi-architecture builds.

```bash
# Development build
./bake.sh mcp-jenkins-dev

# Production build with custom tag
./bake.sh --tag v1.0.0

# Multi-architecture build for registry
./bake.sh mcp-jenkins-multi --tag v1.0.0 --push --registry your-registry.com

# Build with GitHub Actions cache
./bake.sh --cache-from gha --cache-to gha
```

--------------------------------

### Get Plugins with Backup Versions

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/mcp-server.md

Identifies plugins that can be downgraded, meaning they have backup versions available. The 'depth' parameter controls the response detail.

```python
async def get_plugins_with_backup(ctx: Context, depth: int = 0) -> list[dict]:
```

--------------------------------

### Handle Jenkins Client Errors

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/errors.md

This snippet shows how to instantiate the Jenkins client and handle potential exceptions like timeouts, connection errors, and HTTP errors during item retrieval. Ensure you have the 'requests' library installed.

```python
from requests.exceptions import HTTPError, Timeout, ConnectionError
from mcp_jenkins.jenkins import Jenkins

client = Jenkins(
    url="https://jenkins.example.com",
    username="user",
    password="token",
    timeout=10
)

try:
    items = client.get_items()
    print(f"Found {len(items)} items")
except Timeout:
    print("Connection timed out")
except ConnectionError as e:
    print(f"Cannot connect: {e}")
except HTTPError as e:
    print(f"API error: {e.response.status_code}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### Example of Triggering KeyError

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/errors.md

Illustrates a scenario that would raise a KeyError when attempting to build an endpoint URL with missing required parameters. This error is typically for internal use.

```python
# This would raise KeyError: Missing: {'depth'}
endpoint = rest_endpoint.QUEUE()  # Missing required 'depth' parameter
```

--------------------------------

### Get All Jobs via HTTP

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/README.md

Retrieve all Jenkins jobs using the HTTP transport. This example demonstrates sending a POST request to the MCP server's /mcp endpoint with necessary authentication headers and JSON payload.

```bash
curl -X POST http://localhost:9887/mcp \
  -H "x-jenkins-url: https://jenkins.example.com" \
  -H "x-jenkins-username: admin" \
  -H "x-jenkins-password: token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{"name":"get_all_items","arguments":{}}
  }'
```

--------------------------------

### Get Plugin Dependency Graph

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Generates the dependency graph for a specific plugin in Graphviz format. Requires the plugin's short name.

```python
get_plugin_dependency_graph(short_name="git")
```

--------------------------------

### Initialize Jenkins Client

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Instantiate the Jenkins client with server URL, authentication credentials, and optional timeout and SSL verification settings.

```python
from mcp_jenkins.jenkins import Jenkins

client = Jenkins(
    url="https://jenkins.example.com",
    username="admin",
    password="api_token_123",
    timeout=30,
    verify_ssl=True
)
```

--------------------------------

### Catching Network Errors with Jenkins Client

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/errors.md

Provides an example of catching various network-related exceptions like Timeout, ConnectionError, and general RequestException when interacting with the Jenkins client. It shows how to configure a timeout for requests.

```python
from requests.exceptions import RequestException, Timeout, ConnectionError
from mcp_jenkins.jenkins import Jenkins

client = Jenkins(url="https://jenkins.example.com", username="user", password="token", timeout=5)

try:
    items = client.get_items()
except Timeout:
    print("Request timed out. Consider increasing --jenkins-timeout")
except ConnectionError:
    print("Cannot connect to Jenkins server")
except RequestException as e:
    print(f"Request error: {e}")
```

--------------------------------

### Get Jenkins Build Parameters

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches the parameters that were used to run a specific Jenkins build. Returns a dictionary mapping parameter names to their values.

```python
get_build_parameters(fullname="my-job", number=42)
```

--------------------------------

### Add Read-Only MCP Tool

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/AGENTS.md

Example of adding a new read-only MCP tool. The function must accept an MCP context and keyword-only domain parameters. It should return a serialized model dictionary.

```python
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)
```

--------------------------------

### Configuration Flow Visualization

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/modules.md

Outlines the process by which configuration values are sourced and applied, from CLI arguments to environment variables and HTTP headers.

```text
CLI Arguments (--jenkins-url, etc.)
    ↓
Environment Variables (jenkins_url, etc.)
    ↓
lifespan() — Creates LifespanContext
    ↓
Tool receives Context with lifespan_context
    ↓
jenkins(ctx) — Reads from lifespan_context
    ↓
HTTP headers (x-jenkins-*) override via AuthMiddleware
    ↓
Jenkins client created with final credentials
```

--------------------------------

### Run a Groovy Script on Jenkins

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Execute a Groovy script on the Jenkins master. The script is provided as an argument. Example shows retrieving Jenkins version.

```bash
mcp-jenkins-cli << 'EOF' {
  "method": "tools/call",
  "params": {
    "name": "run_groovy_script",
    "arguments": {
      "script": "println Jenkins.instance.version"
    }
  }
}
EOF
```

--------------------------------

### Run MCP Jenkins with Stdio Transport

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Use this command for local development and IDE integration. It starts the MCP Jenkins server using the default Stdio transport.

```bash
mcp-jenkins --jenkins-url https://jenkins.example.com \
  --jenkins-username admin \
  --jenkins-password api-token-123
```

--------------------------------

### Handle Jenkins Connection Timeout

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Example of catching a Timeout exception when a Jenkins request takes too long. Suggests retrying with a longer timeout. Also catches ConnectionError for general connectivity issues.

```python
try:
    items = client.get_items()
except Timeout:
    print("Request timed out - Jenkins may be slow")
    # Retry with longer timeout
except ConnectionError:
    print("Cannot connect to Jenkins")
```

--------------------------------

### Get Build Replay Scripts

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieves the pipeline scripts from a specific build, applicable to Pipeline jobs. Use this to inspect or reconstruct pipeline logic.

```python
def get_build_replay(
    self,
    *,
    fullname: str,
    number: int,
) -> BuildReplay:
```
replay = client.get_build_replay(fullname="my-pipeline", number=42)
for script in replay.scripts:
    print(script)
```

--------------------------------

### Get All Jenkins Items

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves all items (jobs, folders, pipelines) within Jenkins. Use this to get a comprehensive list of all available items.

```python
get_all_items()
```

```python
items = await get_all_items(ctx)
```

--------------------------------

### Handle Missing Jenkins Credentials

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Example of catching a ValueError when Jenkins credentials (URL, username, password) are not provided. Solution involves providing credentials via CLI, environment variables, or headers.

```python
try:
    jenkins_client = Jenkins(url=None, username=None, password=None)
except ValueError as e:
    print(f"Configuration error: {e}")
```

--------------------------------

### Run MCP Jenkins with Streamable HTTP Transport

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

This command starts the MCP Jenkins server using the Streamable HTTP transport, ideal for scalable deployments and cloud environments. It specifies the host and port.

```bash
mcp-jenkins --transport streamable-http \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username admin \
  --jenkins-password api-token-123 \
  --host 0.0.0.0 \
  --port 9887
```

--------------------------------

### Dependency Graph Visualization

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/modules.md

Illustrates the dependency flow from the main entry point to external libraries like requests and BeautifulSoup.

```text
main() [__init__.py]
    ↓
click, loguru, asyncio
    ↓
mcp.run_async() [FastMCP]
    ↓
JenkinsMCP [server/__init__.py]
    ↓
AuthMiddleware, LifespanContext, lifespan [core/*]
    ↓
Tool functions [server/*.py]
    ↓
jenkins(ctx) [core/lifespan.py]
    ↓
Jenkins [jenkins/rest_client.py]
    ↓
requests, BeautifulSoup [external]
    ↓
Pydantic models [jenkins/model/*]
```

--------------------------------

### Get All Jobs using MCP Jenkins CLI

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

This command uses the `mcp-jenkins-cli` tool to call the `get_all_items` method, retrieving a list of all jobs configured in Jenkins.

```bash
mcp-jenkins-cli << 'EOF'
{
  "method": "tools/call",
  "params": {
    "name": "get_all_items",
    "arguments": {}
  }
}
EOF
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Commands for building and running the development environment.

```bash
./bake.sh mcp-jenkins-dev
```

```bash
docker run -it --rm \
  -v $(pwd)/src:/app/src \
  -p 9887:9887 \
  local/mcp-jenkins:dev \
  --jenkins-url https://your-jenkins.example.com \
  --jenkins-username your-username \
  --jenkins-password your-password \
  --transport sse
```

```bash
docker-compose --profile development up mcp-jenkins-dev
```

--------------------------------

### Configure cache strategies

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Commands to utilize GitHub Actions or external registry caching.

```bash
# GitHub Actions Cache
./bake.sh --cache-from gha --cache-to gha

# Registry Cache
./bake.sh --cache-from registry --cache-to registry --registry your-registry.com
```

--------------------------------

### Get All Nodes

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of all nodes (agents) connected to the Jenkins instance. No parameters are required.

```python
get_all_nodes()
```

--------------------------------

### Troubleshoot Runtime Issues

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Commands to inspect and debug running containers.

```bash
docker logs <container-id>
```

```bash
docker run -it --entrypoint /bin/bash local/mcp-jenkins:latest
```

```bash
docker inspect --format='{{.State.Health.Status}}' <container-id>
```

--------------------------------

### Run MCP Jenkins with SSE Transport

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

This command starts the MCP Jenkins server using the SSE transport, suitable for browser-based clients and persistent connections. It specifies the host and port for the server.

```bash
mcp-jenkins --transport sse \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username admin \
  --jenkins-password api-token-123 \
  --host 0.0.0.0 \
  --port 9887
```

--------------------------------

### Build Docker images with Bake

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Use the bake.sh script to build images with various configurations, tags, and cache strategies.

```bash
# Basic build
./bake.sh

# Build development image
./bake.sh mcp-jenkins-dev

# Build with custom tag
./bake.sh --tag v1.0.0

# Build for multiple architectures
./bake.sh mcp-jenkins-multi

# Build and push to registry
./bake.sh --tag v1.0.0 --push --registry your-registry.com

# Build with GitHub Actions cache
./bake.sh --cache-from gha --cache-to gha

# Print configuration without building
./bake.sh --print

# Build all targets
./bake.sh all
```

--------------------------------

### get_all_items

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Get all items (jobs, folders, pipelines) in Jenkins. This tool is tagged with 'read' and requires no parameters.

```APIDOC
## get_all_items

### Description
Get all items (jobs, folders, pipelines) in Jenkins.

### Method
GET (assumed)

### Endpoint
/jenkins/items

### Parameters
None

### Response
#### Success Response (200)
- list[dict] - A list of dictionaries, where each dictionary represents an item.
```

--------------------------------

### Troubleshoot Build Issues

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Commands to resolve common Docker build errors.

```bash
sudo systemctl start docker
```

```bash
sudo usermod -aG docker $USER
# Log out and back in
```

```bash
./bake.sh --cache-from "" --cache-to ""
```

--------------------------------

### Get a Specific Node

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieve details for a specific node by its name. The 'master' or 'Built-In Node' can be used for the controller.

```python
node = client.get_node(name="agent-1")
print(f"Offline: {node.offline}")
for executor in node.executors:
    if executor.currentExecutable:
        print(f"Running: {executor.currentExecutable.fullDisplayName}")
```

--------------------------------

### View Jenkins Log File

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/errors.md

Use the tail command to follow the Jenkins log file in real-time.

```bash
tail -f ~/.mcp_jenkins/log.log
```

--------------------------------

### Get Latest Build Status

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves the status of the latest build for a given job. This is a common pattern for monitoring.

```python
build = await get_build(ctx, fullname="my-job")
# Returns: {'number': 42, 'result': 'SUCCESS', ...}
```

--------------------------------

### get_item

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Get a specific item by its full name path. This tool is tagged with 'read' and accepts a 'fullname' parameter.

```APIDOC
## get_item

### Description
Get a specific item by its full name path.

### Method
GET (assumed)

### Endpoint
/jenkins/items/{fullname}

### Parameters
#### Path Parameters
- **fullname** (str) - Required - Full path of the item (e.g., "folder/job-name")

### Response
#### Success Response (200)
- dict - A dictionary representing the item.
```

--------------------------------

### Jenkins Client Initialization

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Initializes a Jenkins REST client with server URL, authentication credentials, and optional configuration for timeout and SSL verification.

```APIDOC
## Jenkins.__init__()

### Description
Initialize a Jenkins REST client.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| url | str | — | Jenkins server URL (e.g., https://jenkins.example.com) |
| username | str | — | Username for HTTP Basic Authentication |
| password | str | — | Password or API token for authentication |
| timeout | int | 75 | Request timeout in seconds |
| verify_ssl | bool | True | Whether to verify SSL certificates |

### Request Example
```python
from mcp_jenkins.jenkins import Jenkins

client = Jenkins(
    url="https://jenkins.example.com",
    username="admin",
    password="api_token_123",
    timeout=30,
    verify_ssl=True
)
```
```

--------------------------------

### Core Module Exports

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/modules.md

Components for server initialization and request handling within the core module.

```APIDOC
## Core Module Exports

### `AuthMiddleware`

**Type:** class

**Purpose:** ASGI middleware for header-based authentication.

### `LifespanContext`

**Type:** class

**Purpose:** Configuration context for server lifespan.

### `lifespan`

**Type:** function

**Purpose:** Async context manager for server startup.
```

--------------------------------

### Configure Local Cache

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Use local caching for build operations.

```bash
./bake.sh --cache-from local --cache-to local
```

--------------------------------

### get_plugins_with_updates

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of plugins for which updates are available. This allows users to identify and apply the latest versions of their installed plugins.

```APIDOC
## get_plugins_with_updates

### Description
Get plugins with available updates.

### Parameters
#### Query Parameters
- **depth** (int) - Optional - Response depth (default: 0)

### Request Example
```python
get_plugins_with_updates()
```
```

--------------------------------

### List Build Artifacts

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Lists all artifacts associated with a specific build. Use this to discover available files produced by a build.

```python
def get_build_artifacts(
    self,
    *,
    fullname: str,
    number: int,
) -> list[Artifact]:
```
artifacts = client.get_build_artifacts(fullname="my-job", number=42)
for artifact in artifacts:
    print(f"{artifact.fileName}: {artifact.relativePath}")
```

--------------------------------

### Implement a Safe Tool with Error Handling

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/errors.md

Implement a tool that handles potential ValueErrors, HTTP errors (404, 403), and general network request exceptions.

```python
from requests.exceptions import HTTPError, RequestException
from fastmcp import Context
from mcp_jenkins.core.lifespan import jenkins

@mcp.tool(tags=['read'])
async def safe_tool(ctx: Context, fullname: str) -> dict:
    try:
        client = jenkins(ctx)
        item = client.get_item(fullname=fullname)
        return item.model_dump()
    except ValueError as e:
        return {"error": f"Configuration error: {e}"}
    except HTTPError as e:
        if e.response.status_code == 404:
            return {"error": f"Item not found: {fullname}"}
        elif e.response.status_code == 403:
            return {"error": "Permission denied"}
        else:
            return {"error": f"HTTP error {e.response.status_code}"}
    except RequestException as e:
        return {"error": f"Network error: {e}"}
```

--------------------------------

### Get a Specific View

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieve a specific view by its path. This function supports nested views using a '/' delimiter.

```python
view = client.get_view(view_path="frontend")
view = client.get_view(view_path="frontend/nightly")
```

--------------------------------

### Configure via environment variables

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Pass Jenkins credentials and URL directly to the container using environment variables.

```bash
docker run --rm \
  -e JENKINS_URL="https://your-jenkins.example.com" \
  -e JENKINS_USERNAME="your-username" \
  -e JENKINS_PASSWORD="your-password" \
  local/mcp-jenkins:latest
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/AGENTS.md

Executes all pre-commit hooks, including tests and ruff checks, on all files.

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

--------------------------------

### Get All Nodes

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieve a list of all nodes (agents) connected to Jenkins. The 'depth' parameter can be used to fetch more details about each node.

```python
nodes = client.get_nodes()
for node in nodes:
    print(f"{node.displayName}: offline={node.offline}")
    print(f"  Executors: {len(node.executors)}")
```

--------------------------------

### Efficiently Query Multiple Jenkins Items

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Demonstrates an efficient way to retrieve multiple Jenkins items using a single request with a pattern match. This is preferred over fetching items individually in a loop.

```python
# Efficient: single request
items = query_items(fullname_pattern=".*test.*")
```

--------------------------------

### Get Node Configuration XML

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves the XML configuration for a specified Jenkins node. Requires the node's name.

```python
get_node_config(name="agent-1")
```

--------------------------------

### Run with Docker Compose

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Manage container execution using Docker Compose with environment variables or profiles.

```bash
# Set environment variables
export JENKINS_URL="https://your-jenkins.example.com"
export JENKINS_USERNAME="your-username"
export JENKINS_PASSWORD="your-password"

# Run in stdio mode (from project root)
docker-compose up mcp-jenkins

# Run in SSE mode (modify docker-compose.yml first)
docker-compose up mcp-jenkins

# Run development version (from project root)
docker-compose --profile development up mcp-jenkins-dev
```

--------------------------------

### Error Response Format

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/endpoints.md

Example JSON structure for an error response during tool execution, detailing the error code, message, and data.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "details": "Error description"
    }
  }
}
```

--------------------------------

### Tool Registration Pattern

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/modules.md

Illustrates the standard pattern for registering asynchronous tools with the MCP Jenkins server. Tools are decorated with `@mcp.tool()` and receive a context object for accessing the Jenkins client.

```python
import jenkins
from mcp_jenkins.server import Context

@mcp.tool(tags=['read'])  # or tags=['write']
async def tool_name(ctx: Context, param1: str, param2: int | None = None) -> ReturnType:
    """Tool docstring"""
    client = jenkins(ctx)
    result = client.method(...)
    return result.model_dump(exclude_none=True)
```

--------------------------------

### Configure Jetbrains Github Copilot for MCP Jenkins

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/README.md

Add MCP Jenkins server configuration to Jetbrains IDE settings for Github Copilot.

```json
{
  "servers": {
    "my-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-jenkins",
        "--jenkins-url=xxx",
        "--jenkins-username=xxx",
        "--jenkins-password=xxx"
      ]
    }
  }
}
```

--------------------------------

### Get Running Builds

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieves a list of all builds currently in progress across all Jenkins nodes. Useful for monitoring active jobs.

```python
def get_running_builds(self) -> list[Build]:
```
running = client.get_running_builds()
for build in running:
    print(f"Build {build.number}: {build.url}")
```

--------------------------------

### Build development image manually

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/docker/DOCKER.md

Build the development target specifically using the Docker CLI.

```bash
docker build -f docker/Dockerfile --target development -t mcp-jenkins:dev .
```

--------------------------------

### Get Jenkins Job Parameter Definitions

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/mcp-server.md

Retrieves the parameter definitions for a Jenkins job. This is useful for understanding what parameters a job accepts.

```python
async def get_item_parameters(ctx: Context, fullname: str) -> list[dict]:
```

--------------------------------

### get_plugins_with_backup

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches a list of plugins that have available backup versions, indicating they can be downgraded. This is useful for rolling back to a previous stable version if needed.

```APIDOC
## get_plugins_with_backup

### Description
Get plugins that can be downgraded.

### Parameters
#### Query Parameters
- **depth** (int) - Optional - Response depth (default: 0)

### Request Example
```python
get_plugins_with_backup()
```
```

--------------------------------

### Get Node Details

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches details for a specific Jenkins node, including executor information. Requires the node's name.

```python
get_node(name="agent-1")
```

--------------------------------

### Get Jenkins Job Parameters

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Fetches the parameter definitions for a specific Jenkins job. This helps in understanding what parameters a job accepts.

```python
get_item_parameters(fullname="my-job")
```

--------------------------------

### BuildReplay Model

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/types.md

Represents pipeline scripts that can be replayed from a build. Contains a list of script strings.

```python
class BuildReplay(BaseModel):
    scripts: list[str]
```

--------------------------------

### Get Jenkins Item Configuration

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves the XML configuration for a specific Jenkins item. This is useful for inspecting or backing up item configurations.

```python
get_item_config(fullname="my-job")
```

--------------------------------

### Check CLI Arguments for Jenkins Configuration

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Use `mcp-jenkins --help` to inspect available CLI arguments for Jenkins configuration.

```bash
mcp-jenkins --help | grep jenkins
```

--------------------------------

### Get a Specific Plugin

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieve details for a specific plugin using its short name. The 'depth' parameter defaults to 2, including dependencies.

```python
plugin = client.get_plugin(short_name="git")
if plugin:
    print(f"Version: {plugin['version']}")
    print(f"Dependencies: {plugin['dependencies']}")
```

--------------------------------

### Get Jenkins Item Configuration (XML)

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/mcp-server.md

Retrieve the XML configuration for a specific Jenkins item identified by its full path. This is a read-only operation.

```python
@mcp.tool(tags=['read'])
async def get_item_config(ctx: Context, fullname: str) -> str:
    # ... implementation details ...
    pass
```

--------------------------------

### Get Queue Item by ID

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves details for a specific queue item using its unique ID. Requires the item's ID.

```python
get_queue_item(id=12345)
```

--------------------------------

### Build MCP Jenkins Test Docker Image

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/testing-debugging.md

Dockerfile to build a Docker image for testing MCP Jenkins, including copying a docker-compose file and setting the entrypoint.

```dockerfile
FROM ghcr.io/lanbaoshen/mcp-jenkins:latest

# Add test Jenkins instance (for testing)
COPY docker-compose.yml .

ENTRYPOINT ["mcp-jenkins", "--transport", "streamable-http"]
```

--------------------------------

### Download a Specific Build Artifact

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/integration-guide.md

Download a particular artifact from a build. Specify the job name, build number, and the artifact's relative path.

```bash
mcp-jenkins-cli << 'EOF' {
  "method": "tools/call",
  "params": {
    "name": "get_build_artifact",
    "arguments": {
      "fullname": "build-job",
      "number": 42,
      "relative_path": "build/output.jar"
    }
  }
}
EOF
```

--------------------------------

### Get Running Jenkins Builds

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/tools-reference.md

Retrieves a list of all builds that are currently in progress across all Jenkins nodes. Useful for monitoring active jobs.

```python
get_running_builds()
```

--------------------------------

### Get CSRF Crumb Header

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/jenkins-client.md

Retrieves the CSRF crumb header required for authenticated requests. The header is cached and refreshed automatically on a 403 error.

```python
@property
def crumb_header(self) -> dict[str, str]:
    
```

--------------------------------

### Jenkins Client Helper Function

Source: https://github.com/lanbaoshen/mcp-jenkins/blob/master/_autodocs/api-reference/mcp-server.md

A helper function to obtain a Jenkins client instance from the context. It supports singleton mode and header overrides for credentials.

```python
def jenkins(ctx: Context) -> Jenkins:
```

```python
@mcp.tool(tags=['read'])
async def my_tool(ctx: Context) -> dict:
    client = jenkins(ctx)
    items = client.get_items()
    return [item.model_dump() for item in items]
```