jaimenbell/vllm-ops-mcp

Read-only ops/health MCP server for a local, WSL2/systemd-managed vLLM
server -- liveness vs. real-completion health tiers, GPU/VRAM status,
systemd service status, and live serve-flag introspection. Built to the same
standard as mcp-factory and
desktop-mcp, and other local
tooling in this operator's portfolio: own pyproject, own fastmcp server,
honest README, real test suite, no product code before a spec was confirmed.
This is **not** a container-lifecycle manager. It assumes vLLM already runs
as a bare-metal systemd unit inside WSL2 (this operator's actual setup --
see vllm-autostart), not inside Docker/Podman.
Quickstart
Tools (Phase 1 -- all read-only, no gating required beyond a throughput cap)
| Tool | What it does | What it can't do |
|---|---|---|
| check_health(deep: bool = False) | deep=False: GET /v1/models liveness check (same signal as llm_router.LocalLLM.is_healthy()). deep=True: additionally fires one minimal real /v1/chat/completions call (mirrors check-vllm.cmd's two-stage probe) to confirm the server actually *generates*, not just *reports a model loaded*. | Cannot fix a degraded server -- reports ground truth only. deep=True is rate-limited (default 20/min, see below). |
| list_models | /v1/models passthrough. | No detail beyond what vLLM's API itself exposes. |
| test_completion(prompt, max_tokens=16) | On-demand real completion with a caller-supplied prompt, for manual sanity checks. | Rate-limited (same bucket as check_health(deep=True)); refuses if the liveness check fails first (no point firing a completion at a server that isn't even listening). max_tokens is clamped server-side to 1024 (config.MAX_TEST_COMPLETION_TOKENS) and the prompt is capped at 8000 chars (config.MAX_TEST_COMPLETION_PROMPT_CHARS, oversized prompts are rejected, not truncated) -- the rate limiter only bounds call *frequency*, not the cost of a single call. |
| get_gpu_status | nvidia-smi wrapper: per-GPU VRAM used/total + utilization%, plus per-process VRAM via --query-compute-apps. | **Per-process VRAM attribution does not work on this operator's actual WSL2 setup** -- live-verified empty even while the vLLM process holds 13.7GB (see Limitations). Treat processes as best-effort/often-empty, not a reliable per-PID breakdown. |
| get_service_status | systemctl show -p ... (structured property output, not free-text parsing) via wsl -d from the Windows host, or native systemctl if this server itself runs inside WSL2/Linux. Returns load/active/sub state, restart count, main PID, last-active timestamp. | Read-only -- cannot start/stop/restart the unit. No computed uptime duration (deliberately -- see Limitations, clock-discipline note). |
| get_serve_config | Read-only launch-flag introspection. **Prefers the LIVE process's actual argv** (/proc/ /cmdline of the systemd unit's MainPID -- ground truth of what's running right now), falling back to the static exec script (local mirror via VLLM_OPS_MCP_SERVE_CONFIG_PATH, else a live cat of the WSL-side exec script) only when the process isn't up. | vLLM doesn't expose its own launch flags over the API, so this never queries the server itself -- it's always shelling out. Exec-script fallback parsing is best-effort shell-text parsing (less precise than the live-argv path). |
Future extension: restart_service (Phase 2, not built)
Deliberately **not implemented in this release**. Per the spec: vLLM is
shared infra other bots/tools depend on (options-bot, qwen_cli.py
callers, DeerFlow fallback), so a restart tool needs its own gating design
(off by default, VLLM_OPS_MCP_ENABLE_RESTART=1, refuse to touch a healthy
instance unless force=True, rate-capped) before it ships -- not
retrofitted onto a read-only MVP. Tracked as a v2 idea, not a current
capability. If built, it should wrap run-vllm.cmd's exact recipe (systemctl
start vllm only, never blind stop/restart) rather than reinvent it.
The differentiator: probe HTTP, not the listener