netlinq-jenkins-mcp

Ein kleiner Python-Dienst, der Ihren privaten Jenkins-Controller umschließt und es einem Team ermöglicht, die Jobs NetLinQ EMS Release pipeline und Patch Single Repository Pipeline durch natürliche Sprache auszulösen. Eine Codebasis, zwei Ausführungsmodi:

1. MCP-Server (stdio) - in Cursor auf Ihrem Laptop einbinden und fragen: "build 7.0 release package" oder "rebuild blinq-ems-charts at tag 7.0.3".

2. FastAPI-Web-App + Chat-UI - ein Befehl docker compose up auf einem internen Server, das gesamte Team loggt sich über den Browser ein und erhält dieselben Tools.

Hosting-Hinweis: GitHub-gehostete Runner können keinen privaten Jenkins erreichen. Der Code liegt in einem privaten GitHub-Repo; die Laufzeit läuft dort, wo sie einen Netzwerkpfad zu Jenkins hat (der Laptop eines Teammitglieds mit VPN oder eine interne Linux-VM).

Inhaltsverzeichnis

• Architektur

• Schnellstart - MCP in Cursor

• Schnellstart - Team-Chat-UI (Docker)

• Lokale Entwicklung (ohne Docker)

• Konfigurationsreferenz

• Jenkins-Parameternamen entdecken

• Tipps für LLM-Anbieter

• Sicherheitshinweise

• Audit-Log

• Projektstruktur

• Roadmap / nächste Schritte

Architektur

flowchart LR
    subgraph github [Private GitHub Repo]
        repo[netlinq-jenkins-mcp]
    end

    subgraph local [Local laptop - DevOps user]
        cursor[Cursor IDE]
        mcp["FastMCP stdio server<br/>mcp_server.py"]
        cursor -->|stdio| mcp
    end

    subgraph shared [Internal VM - team]
        web["FastAPI web app<br/>web.py + Vite UI"]
        chat["Chat UI - browser"]
        chat -->|HTTPS basic auth| web
    end

    subgraph core [Shared Python core]
        tools["tools.py<br/>5 tool functions"]
        llm["llm.py<br/>LiteLLM router"]
        jc["jenkins_client.py<br/>httpx + crumb"]
    end

    repo -.git clone.-> local
    repo -.git clone.-> shared

    mcp --> tools
    web --> llm
    web --> tools
    llm -->|"tool calls"| tools
    tools --> jc
    jc -->|REST + basic auth| jenkins[(Jenkins<br/>private network)]

tools.py ist die einzige Quelle der Wahrheit. Sowohl der MCP-Server als auch der LiteLLM-Agent in der Web-App rufen dieselben fünf Funktionen auf, sodass das Verhalten zwischen Cursor und der Team-Chat-UI identisch ist.

Die fünf Tools:

Schnellstart - MCP in Cursor

Vollständige Anleitung: docs/CURSOR_MCP.md. Kurzfassung:

1. Generieren Sie ein Jenkins-API-Token unter <JENKINS_URL>/me/configure -> Add new Token.

2. Installieren Sie uv: pipx install uv

3. Bearbeiten Sie ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

   {
     "mcpServers": {
       "netlinq-jenkins": {
         "command": "uvx",
         "args": [
           "--from",
           "git+ssh://git@github.com/<your-org>/netlinq-jenkins-mcp.git@main",
           "netlinq-jenkins-mcp"
         ],
         "env": {
           "JENKINS_URL": "https://jenkins.internal.example.com",
           "JENKINS_USER": "your-user",
           "JENKINS_TOKEN": "your-api-token"
         }
       }
     }
   }

4. Starten Sie Cursor neu. Achten Sie auf den grünen Punkt neben netlinq-jenkins in Einstellungen -> MCP.

5. Versuchen Sie im Chat: "build 7.0 release package". Der Agent wird dies bestätigen, bevor er Jenkins tatsächlich auslöst.

Schnellstart - Team-Chat-UI (Docker)

git clone git@github.com:<your-org>/netlinq-jenkins-mcp.git
cd netlinq-jenkins-mcp
cp .env.example .env
# edit .env: JENKINS_*, LLM_*, WEB_USERS

# Create at least one web user. The hash MUST be bcrypt-hashed.
python -c "from passlib.hash import bcrypt; print('alice:' + bcrypt.hash('secret123'))"
# paste the line into WEB_USERS=

docker compose up -d --build
# browse http://<host>:8000 - log in with alice / secret123

Was das Team sieht:

• Chateingabe unten, Gesprächsverlauf in der Mitte.

• Live-Panels für "kürzliche Builds" für beide Pipelines auf der rechten Seite, alle 5 Sekunden aktualisiert.

• Tool-Call-Karten erweitern sich inline, sodass jeder genau sehen kann, was der Bot tut.

• Ein "Reset"-Button im Header löscht das Gedächtnis des Agenten.

Lokale Entwicklung (ohne Docker)

# Python side
python -m venv .venv
.\.venv\Scripts\Activate.ps1     # PowerShell
# or:  source .venv/bin/activate  # bash
pip install -e ".[dev]"

# Frontend side (only needed for the web mode)
cd ui
npm install
npm run build       # writes ui/dist/, which web.py auto-serves
cd ..

# Run the web app
netlinq-jenkins-web
# or, with auto-reload:
uvicorn netlinq_jenkins.web:create_app --factory --reload --port 8000

# Or run as MCP (stdio - the way Cursor will spawn it)
netlinq-jenkins-mcp

# Run tests
pytest

Konfigurationsreferenz

Alle Einstellungen stammen aus Umgebungsvariablen (oder einer .env-Datei). Siehe .env.example für die kanonische Liste.

Jenkins-Parameternamen entdecken

Wenn VERSION / REPO / TAG nicht Ihre tatsächlichen Parameternamen sind, fragen Sie Jenkins:

curl -s -u "$JENKINS_USER:$JENKINS_TOKEN" \
  "$JENKINS_URL/job/NetLinQ%20EMS%20Release%20pipeline/api/json?tree=property[parameterDefinitions[name,type,defaultParameterValue[value]]]" \
  | jq

Überschreiben Sie dann die entsprechende *_PARAM-Umgebungsvariable in .env oder in Ihrer Cursor mcp.json.

Tipps für LLM-Anbieter

Der Web-Modus verwendet LiteLLM, sodass Sie Anbieter rein über Umgebungsvariablen wechseln können. Häufige Kombinationen:

Der MCP-in-Cursor-Modus benötigt nichts davon - Cursors eigenes Modell steuert das Gespräch und ruft einfach unsere Tools auf.

Sicherheitshinweise

• .env wird von Git ignoriert - Geheimnisse verlassen niemals den Host.

• Der Web-Modus erfordert HTTP-Basic-Auth (bcrypt-gehasht in WEB_USERS).

• Ein optionales WEB_API_SHARED_SECRET fügt einen header-basierten zweiten Faktor für /api/* hinzu, gedacht für Deployments "hinter einem Reverse Proxy".

• Es ist kein eingehender Internetverkehr erforderlich - die App erreicht nur Jenkins.

• API-Token werden gegenüber Passwörtern bevorzugt: Token umgehen den CSRF-Crumb-Prozess und sind einfacher zu widerrufen.

• Eingaben werden vor jedem HTTP-Aufruf mit strengen Regexes (version, repo, tag) validiert, sodass ein gesprächiges LLM keine Shell-Metazeichen einschleusen kann.

• Jeder Tool-Aufruf wird an das Audit-Log angehängt (siehe unten).

Audit-Log

Jeder erfolgreiche Trigger schreibt eine JSONL-Zeile in ${AUDIT_LOG_PATH}:

{"ts": "2026-05-06T20:30:11+00:00", "event": "trigger",
 "pipeline": "NetLinQ EMS Release pipeline",
 "parameters": {"VERSION": "7.0"},
 "queue_url": "https://jenkins.internal.example.com/queue/item/812/"}

Im Docker-Modus ist die Datei auf dem Host unter ./logs/audit.jsonl eingebunden.

Projektstruktur

netlinq-jenkins-mcp/
├── src/netlinq_jenkins/
│   ├── config.py          # pydantic-settings
│   ├── jenkins_client.py  # async httpx wrapper, crumb handling
│   ├── tools.py           # 5 tool functions, used by both modes
│   ├── llm.py             # LiteLLM tool-calling agent (web mode only)
│   ├── mcp_server.py      # FastMCP stdio entrypoint (Cursor)
│   └── web.py             # FastAPI app + serves the bundled UI
├── ui/                    # Vite + React + Tailwind chat UI
│   ├── src/App.tsx        # main chat layout
│   └── src/components/    # ToolCard, BuildsPanel
├── tests/                 # pytest + pytest-httpx
├── docs/CURSOR_MCP.md     # detailed Cursor integration guide
├── examples/cursor-mcp.json
├── Dockerfile             # multi-stage: builds UI, then Python wheel
├── docker-compose.yml
├── .env.example
└── pyproject.toml

Roadmap / nächste Schritte

• [ ] OIDC / SSO anstelle von HTTP-Basic für die Web-UI.

• [ ] Slack-Bot-Adapter, der /build 7.0-Slash-Befehle an dieselben Tools weiterleitet.

• [ ] Optionaler Read-Only-Modus (READ_ONLY=true), der die Trigger-Tools deaktiviert.

• [ ] WebSocket-Log-Tail in der UI anstelle der abfragenden Seitenleiste.

• [ ] Benutzerbezogenes Audit-Log anstelle einer globalen Datei.