netlinq-jenkins-mcp

Un pequeño servicio en Python que envuelve tu controlador Jenkins privado y permite a un equipo activar los jobs NetLinQ EMS Release pipeline y Patch Single Repository Pipeline mediante lenguaje natural. Un solo código, dos modos de ejecución:

1. Servidor MCP (stdio) - conéctalo a Cursor en tu portátil y pregunta: "build 7.0 release package" o "rebuild blinq-ems-charts at tag 7.0.3".

2. Aplicación web FastAPI + interfaz de chat - un comando docker compose up en un servidor interno, todo el equipo inicia sesión a través del navegador y obtiene las mismas herramientas.

Nota sobre el alojamiento: Los runners alojados en GitHub no pueden acceder a un Jenkins privado. El código reside en un repositorio privado de GitHub; el runtime se ejecuta donde tenga una ruta de red hacia Jenkins (el portátil de un compañero con VPN, o una máquina virtual Linux interna).

Tabla de contenidos

• Arquitectura

• Inicio rápido - MCP en Cursor

• Inicio rápido - interfaz de chat de equipo (Docker)

• Desarrollo local (sin Docker)

• Referencia de configuración

• Descubrimiento de nombres de parámetros de Jenkins

• Consejos para proveedores de LLM

• Notas de seguridad

• Registro de auditoría

• Estructura del proyecto

• Hoja de ruta / próximos pasos

Arquitectura

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 es la única fuente de verdad. Tanto el servidor MCP como el agente LiteLLM en la aplicación web llaman a las mismas cinco funciones, por lo que el comportamiento es idéntico entre Cursor y la interfaz de chat del equipo.

Las cinco herramientas:

Inicio rápido - MCP en Cursor

Guía completa: docs/CURSOR_MCP.md. Versión corta:

1. Genera un token de API de Jenkins en <JENKINS_URL>/me/configure -> Add new Token.

2. Instala uv: pipx install uv

3. Edita ~/.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. Reinicia Cursor. Busca el punto verde junto a netlinq-jenkins en Settings -> MCP.

5. En el chat, prueba: "build 7.0 release package". El agente confirmará antes de activar realmente Jenkins.

Inicio rápido - interfaz de chat de equipo (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

Lo que ve el equipo:

• Entrada de chat en la parte inferior, transcripción de la conversación en el medio.

• Paneles de "builds recientes" en vivo para ambos pipelines a la derecha, actualizados cada 5s.

• Las tarjetas de llamada a herramientas se expanden en línea para que la gente pueda ver exactamente lo que está haciendo el bot.

• Un botón "Reset" en el encabezado borra la memoria del agente.

Desarrollo local (sin 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

Referencia de configuración

Todos los ajustes provienen de variables de entorno (o un archivo .env). Consulta .env.example para ver la lista canónica.

Descubrimiento de nombres de parámetros de Jenkins

Si VERSION / REPO / TAG no son tus nombres de parámetros reales, pregúntale a 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

Luego sobrescribe la variable de entorno *_PARAM relevante en .env o en tu mcp.json de Cursor.

Consejos para proveedores de LLM

El modo web utiliza LiteLLM, por lo que puedes cambiar de proveedor solo mediante variables de entorno. Combinaciones comunes:

El modo MCP-en-Cursor no necesita nada de esto - el propio modelo de Cursor dirige la conversación y simplemente llama a nuestras herramientas.

Notas de seguridad

• .env está ignorado por git - los secretos nunca salen del host.

• El modo web requiere autenticación HTTP básica (hash bcrypt en WEB_USERS).

• WEB_API_SHARED_SECRET opcional añade un segundo factor basado en encabezado en /api/*, pensado para despliegues "detrás de un proxy inverso".

• No se requiere tráfico de internet entrante - la aplicación solo se conecta hacia fuera a Jenkins.

• Se prefieren los tokens de API sobre las contraseñas: los tokens omiten el proceso de crumb CSRF y son más fáciles de revocar.

• Las entradas se validan con expresiones regulares estrictas (version, repo, tag) antes de que se realice cualquier llamada HTTP, por lo que un LLM hablador no puede filtrar metacaracteres de shell.

• Cada invocación de herramienta se añade al registro de auditoría (ver abajo).

Registro de auditoría

Cada activación exitosa escribe una línea JSONL en ${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/"}

En modo Docker, el archivo se monta en ./logs/audit.jsonl en el host.

Estructura del proyecto

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

Hoja de ruta / próximos pasos

• [ ] OIDC / SSO en lugar de HTTP Basic para la interfaz web.

• [ ] Adaptador de bot de Slack que reenvíe comandos de barra /build 7.0 a las mismas herramientas.

• [ ] Modo de solo lectura opcional (READ_ONLY=true) que deshabilita las herramientas de activación.

• [ ] Registro de logs por WebSocket en la interfaz en lugar de la barra lateral de sondeo.

• [ ] Registro de auditoría por usuario en lugar de un archivo global.