jenkctl

简体中文

jenkctl is a Rust-based Jenkins CLI and MCP gateway organized with a DDD-style architecture. The CLI and MCP server share the same application service layer so one core implementation can serve both terminal workflows and editor agents.

Features

• Jenkins CLI for system, job, build, pipeline, node, and monitoring operations
• MCP server powered by rmcp 0.16 over stdio
• JSON response envelope by default, with --pretty for human-readable output
• JSONL audit logging for request tracking
• Capability detection for Pipeline Linter, Pipeline WFAPI, Credentials API, and Blue Ocean
• System proxy disabled by default to reduce interference from local proxy settings
• Release workflow that prebuilds common binaries for Linux, macOS, and Windows

Project Layout

• src/domain: domain models, value objects, and ports
• src/application: use-case services and response envelopes
• src/infrastructure: Jenkins HTTP client, environment config, and audit logger
• src/interface: CLI, MCP server, and shared runtime bootstrap

Environment Variables

Required:

• JENKCTL_JENKINS_URL or JENKINS_URL
• JENKCTL_JENKINS_USER or JENKINS_USER
• JENKCTL_JENKINS_TOKEN or JENKINS_TOKEN

Optional:

• JENKCTL_SERVER_ALIAS, defaults to default
• JENKCTL_TIMEOUT_SECONDS, defaults to 30
• JENKCTL_INSECURE_TLS, defaults to false
• JENKCTL_USE_SYSTEM_PROXY, defaults to false
• JENKCTL_AUDIT_ENABLED, defaults to true
• JENKCTL_AUDIT_FILE, defaults to ~/.jenkctl/audit.log
• JENKCTL_ACTOR, defaults to <entrypoint>:$USER, for example cli:alice or mcp:stdio:alice

Example:

export JENKCTL_JENKINS_URL="https://jenkins.example.com"
export JENKCTL_JENKINS_USER="ci-bot"
export JENKCTL_JENKINS_TOKEN="xxxxx"
export JENKCTL_SERVER_ALIAS="production"

Build And Run

From the repository root:

cargo run --manifest-path ./Cargo.toml -- system ping --pretty
cargo run --manifest-path ./Cargo.toml -- job list --pretty

Build release binaries:

cargo build --manifest-path ./Cargo.toml --release
./target/release/jenkctl system ping --pretty

CLI Examples

cargo run --manifest-path ./Cargo.toml -- system ping --pretty
cargo run --manifest-path ./Cargo.toml -- system capabilities --pretty
cargo run --manifest-path ./Cargo.toml -- job list --pretty
cargo run --manifest-path ./Cargo.toml -- job info team/backend-service --pretty
cargo run --manifest-path ./Cargo.toml -- build trigger team/backend-service -p BRANCH=main -p DEPLOY_ENV=staging --pretty
cargo run --manifest-path ./Cargo.toml -- build wait team/backend-service 1024 --timeout 900 --interval 5 --pretty
cargo run --manifest-path ./Cargo.toml -- build log team/backend-service 1024 --tail 200 --pretty
cargo run --manifest-path ./Cargo.toml -- build artifacts team/backend-service 1024 --pretty
cargo run --manifest-path ./Cargo.toml -- build cause team/backend-service 1024 --pretty
cargo run --manifest-path ./Cargo.toml -- build test-report team/backend-service 1024 --pretty
cargo run --manifest-path ./Cargo.toml -- pipeline validate --file ./Jenkinsfile --pretty
cargo run --manifest-path ./Cargo.toml -- pipeline stages team/backend-service 1024 --pretty
cargo run --manifest-path ./Cargo.toml -- pipeline step-log team/backend-service 1024 8 --max-lines 100 --pretty
cargo run --manifest-path ./Cargo.toml -- node list --pretty
cargo run --manifest-path ./Cargo.toml -- node info Linux --pretty
cargo run --manifest-path ./Cargo.toml -- monitor failures --limit 10 --history-window 5 --pretty
cargo run --manifest-path ./Cargo.toml -- monitor success-rate --limit 10 --history-window 5 --pretty
cargo run --manifest-path ./Cargo.toml -- monitor long-running --limit 10 --threshold-secs 1800 --pretty

MCP Server

The stdio MCP server is exposed through the main binary and is the recommended entrypoint:

cargo run --manifest-path ./Cargo.toml -- mcp

Or use the release binary directly:

cargo build --manifest-path ./Cargo.toml --release
./target/release/jenkctl mcp

Recommended VS Code MCP configuration:

{
  "servers": {
    "jenkctl": {
      "type": "stdio",
      "command": "/absolute/path/to/jenkctl/target/release/jenkctl",
      "args": ["mcp"]
    }
  },
  "inputs": []
}

The standalone jenkctl-mcp binary is still shipped for compatibility, but jenkctl mcp is the preferred operational path for packaging, editor setup, and day-to-day MCP usage.

Current MCP surface:

• initialize
• ping
• tools/list
• tools/call

Current MCP tools:

• jenkins_system_ping
• jenkins_system_info
• jenkins_system_capabilities
• jenkins_system_queue
• jenkins_job_list
• jenkins_job_get
• jenkins_job_search
• jenkins_build_trigger
• jenkins_build_status
• jenkins_build_wait
• jenkins_build_log
• jenkins_build_history
• jenkins_build_artifacts
• jenkins_build_cause
• jenkins_build_test_report
• jenkins_pipeline_validate
• jenkins_pipeline_stages
• jenkins_pipeline_step_log
• jenkins_node_list
• jenkins_node_get
• jenkins_monitor_failures
• jenkins_monitor_success_rate
• jenkins_monitor_long_running

Agent Skill

This repository ships a project-scoped GitHub Copilot skill at .github/skills/jenkctl-cli. Load it when an agent needs to map Jenkins tasks to exact jenkctl commands, understand required environment variables, or decide whether to use the CLI or MCP entrypoint.

CI And Releases

The workflow in .github/workflows/ci.yml does the following:

• runs a cross-platform cargo test matrix on Linux, macOS, and Windows for pushes to main, pull requests targeting main, and release tags
• builds release bundles for x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, and x86_64-pc-windows-msvc
• packages both jenkctl and jenkctl-mcp in each archive
• publishes artifacts to GitHub Releases when a v* tag is pushed

Design Notes

• Authentication uses Jenkins Basic Auth with API tokens.
• Mutating requests automatically attempt crumb acquisition.
• Audit logging masks sensitive build parameter keys such as TOKEN, PASSWORD, SECRET, KEY, AUTH, and CREDENTIAL.
• Pipeline features depend on Jenkins plugins; unsupported features return explicit error codes.
• pipeline step-log depends on the Pipeline REST API or WFAPI and returns UNSUPPORTED_CAPABILITY when the server does not expose that surface.
• To avoid proxy-related TLS and connectivity issues, system proxies are disabled by default. Set JENKCTL_USE_SYSTEM_PROXY=true only when proxy routing is required.