netlinq-jenkins-mcp

비공개 Jenkins 컨트롤러를 래핑하여 팀이 자연어를 통해 NetLinQ EMS Release pipeline 및 Patch Single Repository Pipeline 작업을 트리거할 수 있도록 하는 소규모 Python 서비스입니다. 하나의 코드베이스로 두 가지 실행 모드를 지원합니다:

MCP 서버 (stdio) - 노트북의 Cursor에 연결하여 다음과 같이 요청하세요: "build 7.0 release package" 또는 "rebuild blinq-ems-charts at tag 7.0.3".
FastAPI 웹 앱 + 채팅 UI - 내부 서버에서 docker compose up 명령 한 번으로 팀 전체가 브라우저를 통해 로그인하여 동일한 도구를 사용할 수 있습니다.

호스팅 참고: GitHub 호스팅 러너는 비공개 Jenkins에 접근할 수 없습니다. 코드는 비공개 GitHub 저장소에 있지만, 런타임은 Jenkins에 대한 네트워크 경로가 있는 곳(VPN이 연결된 팀원의 노트북 또는 내부 Linux VM)에서 실행되어야 합니다.

아키텍처

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는 단일 진실 공급원(Single Source of Truth)입니다. MCP 서버와 웹 앱의 LiteLLM 에이전트 모두 동일한 5가지 함수를 호출하므로 Cursor와 팀 채팅 UI 간의 동작이 동일합니다.

5가지 도구:

도구	기능
`trigger_release_build(version)`	`7.0`과 같은 버전에 대해 `NetLinQ EMS Release pipeline`을 큐에 추가
`patch_repository(repo, tag)`	기존 태그가 있는 단일 저장소에 대해 `Patch Single Repository Pipeline`을 큐에 추가
`get_build_status(pipeline, build_number?)`	최신 또는 특정 빌드의 결과, 기간, 매개변수 확인
`list_recent_builds(pipeline, limit?)`	기록 (최신순)
`tail_build_log(pipeline, build_number, n_lines?)`	콘솔 출력의 마지막 N줄 확인

빠른 시작 - Cursor에서 MCP 사용

전체 가이드: docs/CURSOR_MCP.md. 요약:

<JENKINS_URL>/me/configure -> Add new Token에서 Jenkins API 토큰을 생성합니다.
uv 설치: pipx install uv

~/.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"
      }
    }
  }
}

Cursor를 재시작합니다. 설정 -> MCP에서 netlinq-jenkins 옆의 녹색 점을 확인하세요.
채팅에서 다음을 시도해 보세요: "build 7.0 release package". 에이전트가 Jenkins를 실제로 트리거하기 전에 확인을 요청할 것입니다.

빠른 시작 - 팀 채팅 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

팀이 보는 화면:

하단에 채팅 입력창, 중앙에 대화 기록.
우측에는 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_URL`	필수	Jenkins 컨트롤러의 기본 URL
`JENKINS_USER`	필수	서비스 계정 사용자 이름
`JENKINS_TOKEN`	필수	API 토큰(권장) 또는 비밀번호
`JENKINS_CA_BUNDLE`	비어 있음	자체 서명된 TLS를 위한 CA 번들 경로, 또는 `false`로 설정 시 검증 건너뜀
`RELEASE_PIPELINE_NAME`	`NetLinQ EMS Release pipeline`	작업 이름이 다를 경우 재정의
`RELEASE_VERSION_PARAM`	`VERSION`	작업의 버전 매개변수 이름
`PATCH_PIPELINE_NAME`	`Patch Single Repository Pipeline`	패치 파이프라인 이름
`PATCH_REPO_PARAM`	`REPO`	패치 파이프라인 저장소 매개변수 이름
`PATCH_TAG_PARAM`	`TAG`	패치 파이프라인 태그 매개변수 이름
`LLM_PROVIDER`	`openai`	정보용 - LiteLLM이 `LLM_MODEL`을 기반으로 선택
`LLM_MODEL`	`gpt-4o`	LiteLLM 지원 모델 문자열
`LLM_API_KEY`	-	제공업체 키 (웹 모드 전용)
`LLM_API_BASE`	-	Azure / Ollama / 자체 호스팅 엔드포인트용
`WEB_HOST`	`0.0.0.0`	FastAPI 바인드 호스트
`WEB_PORT`	`8000`	FastAPI 바인드 포트
`WEB_USERS`	비어 있음	웹 기본 인증을 위한 `user1:bcrypt-hash,user2:bcrypt-hash`
`WEB_API_SHARED_SECRET`	-	`/api/*`에 대한 선택적 `X-API-Secret` 헤더 값
`AUDIT_LOG_PATH`	`audit.jsonl`	모든 도구 호출이 추가되는 JSONL 파일

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

그런 다음 .env 또는 Cursor의 mcp.json에서 관련 *_PARAM 환경 변수를 재정의하세요.

LLM 제공업체 팁

웹 모드는 LiteLLM을 사용하므로 환경 변수만으로 제공업체를 변경할 수 있습니다. 일반적인 조합:

제공업체	`LLM_MODEL`	`LLM_API_KEY`	`LLM_API_BASE`
OpenAI	`gpt-4o`	`sk-...`	-
Anthropic	`claude-sonnet-4-5`	`sk-ant-...`	-
Azure OpenAI	`azure/<deployment>`	Azure 키	`https://<resource>.openai.azure.com`
Ollama (로컬)	`ollama/llama3.1`	-	`http://localhost:11434`
OpenAI 호환	`openai/<model>`	키	`https://your.host/v1`

Cursor 내 MCP 모드는 이 설정이 필요하지 않습니다 - Cursor의 자체 모델이 대화를 주도하고 도구를 호출합니다.

보안 참고 사항

.env는 git-ignored 처리되어 비밀 정보가 호스트를 벗어나지 않습니다.
웹 모드는 HTTP 기본 인증(WEB_USERS에 bcrypt 해시 사용)이 필요합니다.
선택적 WEB_API_SHARED_SECRET은 "리버스 프록시 뒤"에 배포하는 경우를 위해 /api/*에 헤더 기반의 2차 인증을 추가합니다.
인바운드 인터넷 트래픽은 필요하지 않으며, 앱은 Jenkins로만 아웃바운드 연결을 수행합니다.
비밀번호보다 API 토큰을 권장합니다. 토큰은 CSRF 크럼(crumb) 절차를 건너뛰며 취소하기가 더 쉽습니다.
모든 HTTP 호출 전 입력값은 엄격한 정규식(version, repo, tag)으로 검증되므로, LLM이 셸 메타문자를 삽입할 수 없습니다.
모든 도구 호출은 감사 로그에 추가됩니다(아래 참조).

감사 로그

성공적인 모든 트리거는 ${AUDIT_LOG_PATH}에 JSONL 라인을 기록합니다:

{"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

로드맵 / 다음 단계

[ ] 웹 UI를 위한 HTTP 기본 인증 대신 OIDC / SSO 도입.
[ ] /build 7.0 슬래시 명령을 동일한 도구로 전달하는 Slack 봇 어댑터.
[ ] 트리거 도구를 비활성화하는 선택적 읽기 전용 모드 (READ_ONLY=true).
[ ] 폴링 사이드바 대신 UI에서 WebSocket 로그 테일링.
[ ] 전역 파일 대신 사용자별 감사 로그.

netlinq-jenkins-mcp

netlinq-jenkins-mcp

목차

아키텍처

빠른 시작 - Cursor에서 MCP 사용

빠른 시작 - 팀 채팅 UI (Docker)

로컬 개발 (Docker 미사용)

구성 참조

Jenkins 매개변수 이름 확인

LLM 제공업체 팁

보안 참고 사항

감사 로그

프로젝트 레이아웃

로드맵 / 다음 단계

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API