netlinq-jenkins-mcp

Небольшой сервис на Python, который оборачивает ваш приватный контроллер Jenkins и позволяет команде запускать задания NetLinQ EMS Release pipeline и Patch Single Repository Pipeline с помощью естественного языка. Одна кодовая база, два режима работы:

1. MCP-сервер (stdio) — подключите к Cursor на своем ноутбуке и спрашивайте: "build 7.0 release package" или "rebuild blinq-ems-charts at tag 7.0.3".

2. Веб-приложение FastAPI + чат-интерфейс — одна команда docker compose up на внутреннем сервере, вся команда входит через браузер и получает те же инструменты.

Примечание по хостингу: GitHub-раннеры не могут получить доступ к приватному Jenkins. Код находится в приватном репозитории GitHub; среда выполнения запускается там, где есть сетевой путь к Jenkins (ноутбук коллеги с VPN или внутренняя виртуальная машина Linux).

Содержание

• Архитектура

• Быстрый старт - MCP в Cursor

• Быстрый старт - командный чат-интерфейс (Docker)

• Локальная разработка (без Docker)

• Справочник конфигурации

• Поиск имен параметров Jenkins

• Советы по провайдерам LLM

• Заметки по безопасности

• Журнал аудита

• Структура проекта

• Дорожная карта / следующие шаги

Архитектура

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 — единственный источник истины. И MCP-сервер, и агент LiteLLM в веб-приложении вызывают одни и те же пять функций, поэтому поведение в Cursor и в командном чат-интерфейсе идентично.

Пять инструментов:

Быстрый старт - MCP в Cursor

Полное руководство: docs/CURSOR_MCP.md. Краткая версия:

1. Создайте API-токен Jenkins в <JENKINS_URL>/me/configure -> Add new Token.

2. Установите uv: pipx install uv

3. Отредактируйте ~/.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. Перезапустите Cursor. Ищите зеленую точку рядом с netlinq-jenkins в Settings -> MCP.

5. В чате попробуйте: "build 7.0 release package". Агент подтвердит действие перед фактическим запуском Jenkins.

Быстрый старт - командный чат-интерфейс (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

Что видит команда:

• Поле ввода чата внизу, транскрипт беседы посередине.

• Панели "последних сборок" для обоих конвейеров справа, обновляются каждые 5 секунд.

• Карточки вызова инструментов разворачиваются прямо в чате, чтобы люди видели, что именно делает бот.

• Кнопка "Reset" в заголовке очищает память агента.

Локальная разработка (без 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

Справочник конфигурации

Все настройки берутся из переменных окружения (или файла .env). См. .env.example для канонического списка.

Поиск имен параметров Jenkins

Если VERSION / REPO / TAG — это не ваши реальные имена параметров, спросите 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

Затем переопределите соответствующую переменную окружения *_PARAM в .env или в вашем mcp.json для Cursor.

Советы по провайдерам LLM

Веб-режим использует LiteLLM, поэтому вы можете менять провайдеров просто через переменные окружения. Популярные комбинации:

Режим MCP-в-Cursor не требует ничего из этого — собственная модель Cursor управляет беседой и просто вызывает наши инструменты.

Заметки по безопасности

• .env игнорируется git — секреты никогда не покидают хост.

• Веб-режим требует HTTP Basic auth (bcrypt-хеши в WEB_USERS).

• Опциональный WEB_API_SHARED_SECRET добавляет второй фактор на основе заголовка для /api/*, предназначенный для развертываний "за обратным прокси".

• Входящий интернет-трафик не требуется — приложение только обращается наружу к Jenkins.

• API-токены предпочтительнее паролей: токены пропускают CSRF-проверки и их легче отозвать.

• Входные данные проверяются строгими регулярными выражениями (version, repo, tag) перед любым HTTP-вызовом, поэтому разговорчивая LLM не сможет внедрить метасимволы оболочки.

• Каждый вызов инструмента добавляется в журнал аудита (см. ниже).

Журнал аудита

Каждый успешный запуск записывает строку JSONL в ${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/"}

В режиме Docker файл монтируется как ./logs/audit.jsonl на хосте.

Структура проекта

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

Дорожная карта / следующие шаги

• [ ] OIDC / SSO вместо HTTP Basic для веб-интерфейса.

• [ ] Адаптер Slack-бота, который перенаправляет слеш-команды /build 7.0 в те же инструменты.

• [ ] Опциональный режим только для чтения (READ_ONLY=true), который отключает инструменты запуска.

• [ ] WebSocket-лог в реальном времени в интерфейсе вместо опроса боковой панели.

• [ ] Журнал аудита для каждого пользователя вместо одного глобального файла.