wud-mcp
by si-essence
README.md
# wud-mcp
MCP connector for a self-hosted [What's Up Docker](https://github.com/getwud/wud) (WUD) 9.8.0 instance. It calls the REST API over stdio and over stateless Streamable HTTP on localhost.
WUD is MIT software from getwud/wud. This connector is MIT. It does not copy WUD source or the upstream OpenAPI document. It is not affiliated with getwud/wud.
`spec/api-inventory.json` is a hand-written inventory: method, path, operation id, and a short purpose in our own words. It records 9.8.0, commit `c061e6b0a7dab1905ba8e624c42c0189d88aa21b`, MIT, the sha256 of `app/api/openapi.yaml`, and `routeTreeSha256`. `scripts/gen-operations.mjs` maps that inventory onto tool actions or exclusions and writes `src/operations.ts` and `wud.routes.json`. A route that is neither mapped nor excluded fails generation. Do not edit `src/operations.ts` by hand. `npm run ci` runs the generator with `--check`.
`WUD_URL` is required. There is no default origin. Prefer a personal API token from My Profile, sent as `Authorization: Bearer wud_...`. Older instances can use HTTP Basic (`WUD_AUTH=basic`). The credential is never placed in the URL.
## Setup
```bash
npm install
npm run ci
npm start
npm run start:http
```
`npm start` speaks stdio. `npm run start:http` serves Streamable HTTP at `http://127.0.0.1:3000/mcp` and `GET /health`. HTTP mode has no authentication of its own. Keep it on localhost.
Create the token in the WUD UI under My Profile. The header is `Authorization: Bearer`, then a space, then the `wud_...` token. Docs: [Authentication](https://getwud.app/docs/configuration/authentications/).
```json
{
"mcpServers": {
"wud": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"WUD_URL": "http://127.0.0.1:3000",
"WUD_TOKEN": "...",
"WUD_ALLOW_WRITES": "false"
}
}
}
}
```
Prefer `WUD_TOKEN_FILE` (mode 0600) over `WUD_TOKEN`. The connector never prints the token.
Basic auth for an older instance:
```json
{
"env": {
"WUD_URL": "http://127.0.0.1:3000",
"WUD_AUTH": "basic",
"WUD_BASIC_USER": "admin",
"WUD_BASIC_PASSWORD": "...",
"WUD_ALLOW_WRITES": "false"
}
}
```
```bash
docker build -t wud-mcp .
docker run -p 127.0.0.1:3000:3000 \
-e WUD_URL=http://127.0.0.1:3000 \
-e WUD_TOKEN=... \
wud-mcp
```
Do not put secrets in the image. The image is the connector only. It does not run WUD or Docker.
Regenerate the registry from the committed inventory.
```bash
npm run gen:operations
node scripts/gen-operations.mjs --check
node scripts/gen-operations.mjs --source-root /path/to/wud --check
```
`--source-root` checks the pinned sha256 of `app/api/openapi.yaml`. It does not rewrite the inventory and it does not copy that file into this package.
`scripts/live-check.mjs` talks to a server over stdio. Set `WUD_URL`. Set `WUD_TOKEN` or `WUD_TOKEN_FILE`. The script unsets `DATABASE_URL`. It prints pass or fail lines only, and it redacts tokens and planted passwords. It does not run inside `npm run ci`. A missing token is a failure.
The loopback stand-in used for the recorded live check is `/workspace/tools/wud/start.sh` and `stop.sh`. See `LIVE-CHECK.md`. That stand-in is not WUD.
## Config
| Variable | Meaning |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WUD_URL` | Required. Origin only, `http` or `https`, no userinfo, query, hash, or path. Example `http://127.0.0.1:3000`. Do not append `/api`. |
| `WUD_TOKEN` | Required for Bearer auth unless `WUD_TOKEN_FILE` is set. Sent as `Authorization: Bearer`. Redacted in logs, errors, previews, and results. Minimum 8 characters. |
| `WUD_TOKEN_FILE` | Optional. chmod 600 file whose trimmed contents are the Bearer token. |
| `WUD_AUTH` | `bearer` (default) or `basic`. |
| `WUD_BASIC_USER` | Required when `WUD_AUTH=basic`. No colon. |
| `WUD_BASIC_PASSWORD` | Required for Basic unless `WUD_BASIC_PASSWORD_FILE` is set. The password may contain a colon. |
| `WUD_BASIC_PASSWORD_FILE` | Optional chmod 600 file used instead of `WUD_BASIC_PASSWORD`. |
| `WUD_ALLOW_WRITES` | Must be the literal `true` before a confirmed write is sent. |
| `WUD_PER_MINUTE` | Local request budget. Default 30. Cache hits do not spend it. Live-check sets 600. |
| `WUD_TIMEOUT_MS` | Upstream timeout. Default 20000. |
| `WUD_CACHE_TTL_SEC` | Read cache TTL. Default 60. Writes clear the cache. |
| `WUD_CONTACT` | Contact token in the User-Agent. Must not contain the credential. |
| `MCP_TRANSPORT` | `stdio` or `http`. `--http` overrides. |
| `PORT` | HTTP port. Default 3000. |
Invalid values are reported by field name and issue code. The rejected value is not included.
Calls go to paths from the operations registry. `Accept` is `application/json`. JSON writes send `Content-Type: application/json`. Redirects are refused. There are no automatic retries, including HTTP 429.
## Tools
Six action-field tools. `action` selects the operation. Unknown fields and fields that do not belong to that action are rejected before any HTTP call. The string `"true"` is not a boolean and is rejected.
| Tool | Actions |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `wud_app` | `info`, `server`, `store`, `logs` |
| `wud_container` | `list`, `get`, `triggers`, `watch_all`, `watch`, `snooze`, `unsnooze`, `run_trigger`, `delete` |
| `wud_trigger` | `list`, `get`, `run` |
| `wud_watcher` | `list`, `get` |
| `wud_registry` | `list`, `get`, `events` |
| `wud_auth` | `strategies`, `user`, `list`, `get` |
`list` on containers accepts optional `status`, `watcher`, `stack`, and `tag`. They are forwarded as query parameters. WUD applies them.
Writes (8) need `confirm: true` and `WUD_ALLOW_WRITES=true`:
| Action | Method | Notes |
| ----------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `wud_container` `watch_all` | `POST /api/containers/watch` | Checks every watched container. |
| `wud_container` `watch` | `POST /api/containers/{id}/watch` | Checks one container. |
| `wud_container` `snooze` | `POST /api/containers/{id}/snooze` | Optional `version` and `until` (epoch milliseconds). |
| `wud_container` `unsnooze` | `DELETE /api/containers/{id}/snooze` | Clears a snooze. |
| `wud_container` `run_trigger` | `POST /api/containers/{id}/triggers/{triggerType}/{triggerName}` | Optional `overrideCooldown`. Can notify or update a container. Destructive. |
| `wud_container` `delete` | `DELETE /api/containers/{id}` | Removes the WUD record. Does not delete the Docker container. Destructive. |
| `wud_trigger` `run` | `POST /api/triggers/{type}/{name}` | Optional `overrideCooldown`. Can notify or update containers. Destructive. |
| `wud_registry` `events` | `POST /api/registries/{name}/events` | Needs `document.events` (1 to 100 items) and `eventToken`. |
`eventToken` is the registry webhook bearer (`WUD_REGISTRY_<NAME>_WEBHOOK_TOKEN`). It is not the API token. The connector sends it as `Authorization: Bearer` on that one request and redacts it.
### Examples
Application info:
```json
{ "action": "info" }
```
Containers that WUD marks running, on one watcher:
```json
{ "action": "list", "status": "running", "watcher": "docker.local" }
```
Dry-run a snooze (nothing is sent):
```json
{ "action": "snooze", "id": "cafebabe0001", "version": "1.27.3" }
```
Send it only when you mean to, and only if `WUD_ALLOW_WRITES=true`:
```json
{
"action": "snooze",
"id": "cafebabe0001",
"version": "1.27.3",
"until": 1800000000000,
"confirm": true
}
```
Registry push hint:
```json
{
"action": "events",
"name": "public",
"eventToken": "wud_registry_webhook_token",
"confirm": true,
"document": { "events": [{ "action": "push" }] }
}
```
## Safety
Reads run without a write flag. A write is sent only when `confirm` is the boolean `true` and `WUD_ALLOW_WRITES=true`. That gate covers all 8 writes.
Omit `confirm`, or pass boolean `false`, and the tool returns a dry-run preview of method, path, query, and body. It sends nothing. `blocked` is false on that preview. `confirm: true` with writes disabled returns the same preview with `blocked` true and the reason `WUD_ALLOW_WRITES is not true. The write was not sent.`
API tokens, Basic passwords, the Basic credential's base64 form, registry passwords, webhook tokens, and session secrets are redacted in logs, errors, previews, and tool results. Redaction covers the exact value, the percent-encoded form, and the JSON-escaped form. URL userinfo is stripped. Values under sensitive keys (`password`, `token`, `secret`, `authorization`, `credential`, `cookie`, `session`, `webhook`, and the same family) become `[redacted]`. Usernames stay. A short credential (under 8 characters) forces a generic upstream message instead of a partial mask.
Watch and snooze change WUD state. Running a trigger can send a notification or recreate a container, depending on how that trigger is configured on the instance. Delete removes WUD's record of a container. It does not call the Docker Engine to remove the container.
Excluded on purpose:
| Route | Why |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| `POST /auth/login` | Password login creates a browser session. This connector sends Bearer or Basic on each request. |
| `POST /auth/logout` | Session logout. This connector does not keep a cookie. |
| `GET /api/events` | Server-Sent Events stream. MCP tools return one JSON result. A long-lived stream is out of scope. |
## Provenance and coverage
| | |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| Upstream | getwud/wud 9.8.0, commit `c061e6b0a7dab1905ba8e624c42c0189d88aa21b` |
| License (upstream) | MIT |
| License (this connector) | MIT |
| OpenAPI pin | `app/api/openapi.yaml` sha256 `8bef15f31d24ac3ec98788bb285d121b649e59b21ec0608a96858f9e43edb762` |
| Inventory routes | 28 |
| Mapped | 25 |
| Excluded | 3 |
| Tools | 6 |
| Actions | 25 |
| Write actions | 8, all confirm-gated |
Public docs were read at `https://getwud.app/docs/` for Bearer personal tokens (`wud_...` from My Profile) and for deprecated Basic auth. Route facts were taken from the 9.8.0 OpenAPI path list. No upstream YAML or source file is copied into this package.
A workspace copy of the OpenAPI file at `/tmp/wud-openapi.yaml` has the same 28 routes and the same version string. Its bytes differ from the tag file (extra prose). The inventory is pinned to the tag file.
## Rivals
Checked 19 Nov 2026. GitHub repository search for WUD plus MCP found one project. npm has no package named `wud-mcp`. `jcdreamjc/wudao-mcp` (11 stars) is a China A-share market server. It is not What's Up Docker.
| | [reimlima/wud-mcp](https://github.com/reimlima/wud-mcp) | this connector |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Language | Go 1.22. Last push 27 Jul 2026. 0 stars. MIT. | TypeScript. MIT. |
| Tools | 17 separate tools: app info, containers (list, get, watch all, watch one, triggers, run trigger, delete), registries (list, get), triggers (list, get, run), watchers (list, get), store, log config. | 6 action-field tools, 25 actions, including server info, logs, snooze, unsnooze, authentications, and registry webhook hints. |
| Auth | `WUD_BASE_URL` defaults to `http://localhost:3000`. Optional HTTP Basic (`WUD_API_USER` / `WUD_API_PASSWORD`). No Bearer personal token. | Origin required. Bearer `wud_...` by default. Basic is opt-in for older instances. |
| Writes | `watch_all_containers`, `watch_container`, `run_container_trigger`, `run_trigger`, and `delete_container` call the API immediately. No confirm flag and no allow-writes switch. | Dry-run unless `confirm` is boolean `true` and `WUD_ALLOW_WRITES=true`. |
| Secrets | Tool results are the raw response text. The README does not describe redaction. | Tokens, passwords, webhook tokens, and session values are redacted, including encoded forms. |
| Coverage gaps vs 9.8.0 | No snooze or unsnooze, no container list filters, no server info, no authentication reads, no registry webhook, no SSE note. `get_log_config` is described as logger configuration. | SSE, login, and logout are excluded on purpose and named in the inventory. |
## Tests
Vitest covers the write-guard matrix for every write (omit, false, true, writes off, writes on, `TRUE`, `1`), preview versus confirmed, unknown fields, spec coverage, HTTP 401, 403, 404, 422, and 429 mapping, Bearer and Basic headers, and leak regressions. `npm run ci` is typecheck, lint, test, build, and `scripts/gen-operations.mjs --check`.
The recorded live check did not run a real WUD process. See `LIVE-CHECK.md` and `BLOCKER.md`.
```bash
/workspace/tools/wud/start.sh
cd /workspace/connectors/wud
export WUD_URL=http://127.0.0.1:$(cat /workspace/tools/wud/runtime/mock.port)
export WUD_TOKEN_FILE=/workspace/tools/wud/runtime/api.token
unset WUD_TOKEN DATABASE_URL
npm run live-check
/workspace/tools/wud/stop.sh
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues