netlinq-jenkins-mcp

プライベートなJenkinsコントローラーをラップし、チームが自然言語でNetLinQ EMS Release pipelineおよびPatch Single Repository Pipelineジョブをトリガーできるようにする小さなPythonサービスです。コードベースは1つで、2つの実行モードがあります。

MCPサーバー (stdio) - ラップトップのCursorにプラグインし、"build 7.0 release package" や "rebuild blinq-ems-charts at tag 7.0.3" と尋ねることができます。
FastAPI Webアプリ + チャットUI - 社内サーバーで docker compose up を1回実行するだけで、チーム全員がブラウザ経由でログインし、同じツールを利用できます。

ホスティングに関する注意: 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 が唯一の信頼できる情報源です。MCPサーバーとWebアプリ内のLiteLLMエージェントの両方が同じ5つの関数を呼び出すため、CursorとチームチャットUIの間で動作は同一です。

5つのツール:

ツール	動作
`trigger_release_build(version)`	`7.0` のようなバージョンの `NetLinQ EMS Release pipeline` をキューに入れます
`patch_repository(repo, tag)`	既存タグの1リポジトリに対して `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 でJenkins APIトークンを生成します -> Add new Token。
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`	-	プロバイダーキー（Webモードのみ）
`LLM_API_BASE`	-	Azure / Ollama / セルフホストエンドポイント用
`WEB_HOST`	`0.0.0.0`	FastAPIのバインドホスト
`WEB_PORT`	`8000`	FastAPIのバインドポート
`WEB_USERS`	空	WebのBasic認証用 `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プロバイダーのヒント

Webモードは 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であり、シークレットがホストから流出することはありません。
WebモードはHTTP Basic認証（WEB_USERSでbcryptハッシュ化）を必要とします。
オプションの WEB_API_SHARED_SECRET は、リバースプロキシの背後でのデプロイを想定し、/api/* に対してヘッダーベースの二要素認証を追加します。
インバウンドのインターネットトラフィックは不要です。アプリはJenkinsに対してのみアウトバウンド通信を行います。
パスワードよりもAPIトークンが推奨されます。トークンはCSRFの制限を回避でき、取り消しも容易です。
入力は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

ロードマップ / 今後のステップ

[ ] Web UI用のHTTP Basic認証に代わる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