Add timeout/logging/audit/CLI features for 0.5.0 release

MCP_TIMEOUT wasn't applied to HTTP transport, OAuth callback used a
hardcoded port range, audit logs were ephemeral in containers, and
there was no structured logging or shell completions.

Apply MCP_TIMEOUT to reqwest client builder, make OAuth callback port
configurable via MCP_OAUTH_CALLBACK_PORT (single, range, or OS-assigned),
add tracing-based structured logging with MCP_LOG_LEVEL/MCP_LOG_FORMAT,
add MCP_AUDIT_OUTPUT=stdout/stderr for container log drivers, and
introduce mcp config path/edit and mcp completions commands.

Fixes #13
Fixes #16
Fixes #76
Fixes #71
Fixes #9
Fixes #8
Fixes #5

Signed-off-by: Avelino <31996+avelino@users.noreply.github.com>

Author: avelino

Cargo.lock

@@ -39,6 +39,8 @@ chrondb = "0.2.3-dev.12298e3"
 chrono = { version = "0.4", features = ["serde"] }
 shell-words = "1"
 socket2 = { version = "0.6", features = ["all"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
 
 [dev-dependencies]
 tempfile = "3"

Cargo.toml

@@ -157,6 +157,7 @@ Add an `audit` section to `~/.config/mcp/servers.json`:
 | Field | Default | Description |
 |---|---|---|
 | `enabled` | `true` | Enable/disable audit logging |
+| `output` | `file` | Output destination: `file` (ChronDB, queryable), `stdout`, `stderr` (JSON lines), or `none` |
 | `log_arguments` | `false` | Log tool call arguments (may contain PII) |
 | `path` | `~/.config/mcp/audit/data` | ChronDB data directory |
 | `index_path` | `~/.config/mcp/audit/index` | ChronDB index directory |
@@ -216,13 +217,44 @@ MCP_AUDIT_ENABLED=false mcp serve --http 0.0.0.0:8080
 
 When disabled, the logger is a no-op and the database is not initialized — zero overhead, no files created, no filesystem writes. This is the default in the Docker image.
 
+## Streaming to stdout/stderr (containers)
+
+In containers, writing audit to ChronDB is often impractical — the filesystem may be read-only, ephemeral, or you want logs flowing to your container log driver (CloudWatch, Datadog, etc.).
+
+Set `output` to `stdout` or `stderr` to emit audit entries as newline-delimited JSON (one JSON object per line):
+
+```bash
+MCP_AUDIT_OUTPUT=stdout mcp serve --http 0.0.0.0:8080
+```
+
+Or in the config file:
+
+```json
+{
+  "audit": {
+    "output": "stdout"
+  }
+}
+```
+
+Each line is a complete `AuditEntry` JSON object:
+
+```json
+{"timestamp":"2026-04-14T12:00:00-03:00","source":"serve:http","method":"tools/call","tool_name":"search_issues","server_name":"sentry","identity":"alice","duration_ms":142,"success":true}
+```
+
+When using `stdout` or `stderr` mode, `mcp logs` queries are not available (no database to query). Use your log aggregation pipeline instead.
+
+Set `output` to `none` to disable audit entirely without touching the `enabled` flag.
+
 ## Environment variable overrides
 
 All audit settings can be overridden via environment variables, which take priority over the config file. This is useful for container deployments where editing the config JSON is impractical.
 
 | Variable | Overrides | Description |
 |---|---|---|
 | `MCP_AUDIT_ENABLED` | `audit.enabled` | Set to `false` or `0` to disable |
+| `MCP_AUDIT_OUTPUT` | `audit.output` | `file`, `stdout`, `stderr`, or `none` |
 | `MCP_AUDIT_PATH` | `audit.path` | ChronDB data directory |
 | `MCP_AUDIT_INDEX_PATH` | `audit.index_path` | ChronDB index directory |
 
@@ -237,4 +269,12 @@ docker run -d \
   ghcr.io/avelino/mcp serve --http 0.0.0.0:8080
 ```
 
+Example: stream audit to container stdout (no volume needed):
+
+```bash
+docker run -d \
+  -e MCP_AUDIT_OUTPUT=stdout \
+  ghcr.io/avelino/mcp serve --http 0.0.0.0:8080
+```
+
 See the full list of variables in the [environment variables reference](../reference/environment-variables.md).

docs/guides/audit-logging.md

@@ -36,7 +36,7 @@ Your browser opens, you authorize the app, and the token is saved. Next time, it
 3. Registers as a client using [Dynamic Client Registration](https://datatracker.ietf.org/doc/rfc7591/) if supported
 4. Generates a PKCE challenge (S256) for security
 5. Opens your browser to the authorization URL
-6. Listens on a local port (`localhost:8085-8099`) for the callback
+6. Listens on a local port for the callback (default range `localhost:8085-8099`, configurable via `MCP_OAUTH_CALLBACK_PORT`)
 7. Exchanges the authorization code for tokens
 8. Saves tokens to `~/.config/mcp/auth.json`
 

docs/guides/authentication.md

@@ -115,7 +115,21 @@ docker run -d \
 
 ### With audit logging
 
-The default image disables audit logging (`MCP_AUDIT_ENABLED=false`) because `scratch` images have no writable filesystem. To enable it, mount a volume and override:
+The default image disables audit logging (`MCP_AUDIT_ENABLED=false`) because `scratch` images have no writable filesystem. You have two options:
+
+**Option A: Stream to stdout (no volume needed)**
+
+```bash
+docker run -d \
+  -e MCP_SERVERS_CONFIG='{"mcpServers":{...}}' \
+  -e MCP_AUDIT_OUTPUT=stdout \
+  -p 8080:8080 \
+  ghcr.io/avelino/mcp serve --http 0.0.0.0:8080 --insecure
+```
+
+Audit entries are emitted as JSON lines to stdout, captured by your container log driver (CloudWatch, Datadog, etc.).
+
+**Option B: Persist to a volume**
 
 ```bash
 docker run -d \
@@ -136,7 +150,10 @@ These variables are especially useful for container deployments. See the full li
 |---|---|---|
 | `MCP_SERVERS_CONFIG` | — | Inline JSON config, no file mount needed |
 | `MCP_CONFIG_DIR` | `~/.config/mcp` | Override config directory |
+| `MCP_LOG_LEVEL` | `info` | Log verbosity: `trace`, `debug`, `info`, `warn`, `error` |
+| `MCP_LOG_FORMAT` | `text` | Log format: `text` or `json` (structured, for log drivers) |
 | `MCP_AUDIT_ENABLED` | `false` (in Docker image) | Disable audit for read-only fs |
+| `MCP_AUDIT_OUTPUT` | `file` | `stdout`/`stderr` for container log drivers, `none` to disable |
 | `MCP_AUDIT_PATH` | `~/.config/mcp/db/data` | Override audit data path |
 | `MCP_AUDIT_INDEX_PATH` | `~/.config/mcp/db/index` | Override audit index path |
 | `MCP_AUTH_PATH` | `~/.config/mcp/auth.json` | Override OAuth token storage |
@@ -194,4 +211,4 @@ docker run --rm ghcr.io/avelino/mcp:0.1.0 --help
 
 - **Stdio servers only work if the runtime is available inside the container.** The default image includes only the `mcp` binary and `ca-certificates`. Servers that require `npx`, `python`, or other runtimes won't work unless you build a custom image. HTTP servers (configured with `url`) work out of the box.
 - **OAuth browser flow doesn't work in Docker.** For HTTP servers that need OAuth, run `mcp add <server>` on your host first to complete authentication, then mount the config directory (which includes `auth.json`), or set `MCP_AUTH_PATH` to a mounted volume.
-- **Audit logging is disabled by default** in the Docker image because `scratch` images have no writable filesystem. Enable it with `MCP_AUDIT_ENABLED=true` and mount a volume for the data.
+- **Audit logging is disabled by default** in the Docker image because `scratch` images have no writable filesystem. Use `MCP_AUDIT_OUTPUT=stdout` to stream to the container log driver, or mount a volume and set `MCP_AUDIT_ENABLED=true`.

docs/howto/docker.md

@@ -124,7 +124,11 @@ The proxy exposes `GET /health` returning:
 
 By default, audit logging is disabled (`MCP_AUDIT_ENABLED=false`) because the scratch-based image has no writable filesystem.
 
-To enable:
+**Option A: Stream to stdout (no PVC needed)**
+
+Set `MCP_AUDIT_OUTPUT=stdout` in the Deployment env. Audit entries are emitted as JSON lines to stdout and captured by your cluster's log pipeline (Fluentd, Loki, CloudWatch, etc.). No persistent storage required.
+
+**Option B: Persist to a PVC**
 
 1. Set `MCP_AUDIT_ENABLED=true` in the Deployment env
 2. Mount persistent storage at `/data`:
@@ -207,6 +211,7 @@ When Kubernetes sends `SIGTERM` (during rolling updates or scale-down):
 | `MCP_SERVERS_CONFIG` | (from ConfigMap) | Inline JSON config (highest priority) |
 | `MCP_PROXY_REQUEST_TIMEOUT` | `120` (app default) | Max seconds per JSON-RPC request |
 | `MCP_AUDIT_ENABLED` | `false` | Enable audit logging |
+| `MCP_AUDIT_OUTPUT` | `file` | `stdout` for cluster log pipeline, `file` for PVC, `none` to disable |
 | `MCP_AUDIT_PATH` | `/data/audit/data` | Audit data directory (app default: `~/.config/mcp/db/data`) |
 | `MCP_AUDIT_INDEX_PATH` | `/data/audit/index` | Audit index directory (app default: `~/.config/mcp/db/index`) |
 | `MCP_CLASSIFIER_CACHE` | `/tmp/tool-classification.json` | Tool classification cache (app default: `~/.config/mcp/tool-classification.json`) |

docs/howto/kubernetes.md

@@ -262,7 +262,7 @@ mcp add filesystem
 Fails if:
 - Server not found in registry
 - Server already exists in config
-- Name is reserved (`search`, `add`, `remove`, `list`, `help`, `version`)
+- Name is reserved (`search`, `add`, `remove`, `list`, `help`, `version`, `serve`, `logs`, `config`, `completions`)
 
 ### `mcp add --url <url> <name>`
 
@@ -311,6 +311,61 @@ Fails if:
 
 > If the server changed type in the registry (stdio ↔ http), `mcp update` warns and drops type-specific fields that no longer apply.
 
+## Config commands
+
+### `mcp config path`
+
+Print the resolved path to the config file (`servers.json`).
+
+```bash
+mcp config path
+# /Users/you/.config/mcp/servers.json
+```
+
+With `--json`, includes metadata:
+
+```json
+{
+  "path": "/Users/you/.config/mcp/servers.json",
+  "exists": true,
+  "dir": "/Users/you/.config/mcp"
+}
+```
+
+### `mcp config edit`
+
+Open the config file in your editor. Uses `$EDITOR`, falls back to `$VISUAL`, then `vi` (or `notepad` on Windows).
+
+```bash
+mcp config edit
+```
+
+If the config file doesn't exist, it's created with `{}` before opening.
+
+## Shell completions
+
+### `mcp completions <shell>`
+
+Generate shell completion scripts. Supported shells: `bash`, `zsh`, `fish`.
+
+```bash
+# Fish (recommended for the current session)
+mcp completions fish | source
+
+# Fish (persistent)
+mcp completions fish > ~/.config/fish/completions/mcp.fish
+
+# Bash
+mcp completions bash >> ~/.bashrc
+source ~/.bashrc
+
+# Zsh
+mcp completions zsh > "${fpath[1]}/_mcp"
+autoload -Uz compinit && compinit
+```
+
+Completions cover all subcommands, flags, and nested subcommands (`config path|edit`, `acl classify|check`, `logs` flags, etc.).
+
 ## ACL commands
 
 ### `mcp acl classify`