Operation logging with MCP tool and CLI access

[aniongithub]

Summary

Add structured logging of all MCP tool invocations and their results, viewable both via a new MCP tool (for agents) and directly via CLI (for humans).

Motivation

Currently devcontainer-mcp operations are fire-and-forget — there is no record of what tools were called, what arguments were passed, whether they succeeded or failed, or how long they took. This makes debugging, auditing, and post-mortem analysis difficult for both agents and users.

Proposed design

Log storage

Append-only structured log at ~/.local/share/devcontainer-mcp/logs/operations.jsonl:

{"ts":"2025-05-13T07:45:00Z","tool":"devcontainer_exec","args":{"workspace_folder":"/path","command":"cargo build"},"exit_code":0,"duration_ms":3200,"stdout_len":0,"stderr_len":450}
{"ts":"2025-05-13T07:45:04Z","tool":"devpod_ssh","args":{"workspace":"my-ws","command":"npm test"},"exit_code":1,"duration_ms":12500,"stdout_len":2048,"stderr_len":512,"error":"exit code 1"}
{"ts":"2025-05-13T07:45:17Z","tool":"codespaces_create","args":{"repo":"owner/repo","machine":"basicLinux32gb"},"exit_code":0,"duration_ms":45000}

Each entry includes:

• ts — ISO 8601 timestamp
• tool — tool name
• args — tool arguments (sanitized — no auth tokens)
• exit_code — result code
• duration_ms — execution time
• stdout_len / stderr_len — output sizes (not full content, to keep logs compact)
• error — error message if applicable

MCP tool: operation_log

A new MCP tool for agents to query the log:

operation_log(last: 20)                          # last 20 operations
operation_log(tool: "devcontainer_exec")          # filter by tool
operation_log(since: "2025-05-13T07:00:00Z")     # since timestamp
operation_log(errors_only: true)                  # only failures

Returns formatted results so the agent can understand what happened previously — useful for debugging failed sequences, retrying operations, or understanding workspace state.

CLI subcommand: devcontainer-mcp log

# Show recent operations
devcontainer-mcp log

# Show last N
devcontainer-mcp log --last 50

# Filter by tool
devcontainer-mcp log --tool devcontainer_exec

# Only errors
devcontainer-mcp log --errors

# Since timestamp
devcontainer-mcp log --since 2025-05-13T07:00:00Z

# Follow mode (tail -f style)
devcontainer-mcp log --follow

# Clear logs
devcontainer-mcp log --clear

Implementation notes

• Log rotation: rotate when file exceeds a configurable size (default 10MB), keep last N rotated files
• Logging should be non-blocking — write failures must never cause tool execution to fail
• Sensitive fields (auth tokens, file contents) must be redacted from log entries
• The operation_log MCP tool should be registered alongside existing tool routers

Open questions

• Should log verbosity be configurable (e.g. also log full stdout/stderr at a debug level)?
• Should logs be per-workspace or global?
• Should the log include hook invocations (guard script calls) as well?