68 lines
3.2 KiB
Markdown
68 lines
3.2 KiB
Markdown
---
|
||
summary: 'Reference for capturing mcporter diagnostics (daemon logs, per-server overrides, env flags).'
|
||
read_when:
|
||
- 'Need persistent daemon logs or want to trace keep-alive STDIO servers.'
|
||
---
|
||
|
||
# Logging & Diagnostics
|
||
|
||
## Daemon logging
|
||
|
||
The keep-alive daemon can tee its stdout/stderr (and per-server call traces) into a file so you can see crashes or repeated failures without rerunning it in the foreground.
|
||
|
||
### CLI flags
|
||
|
||
- `mcporter daemon start --log` — enable logging at the default path `~/.mcporter/daemon/daemon-<config-hash>.log`, or `$XDG_STATE_HOME/mcporter/daemon/daemon-<config-hash>.log` when `XDG_STATE_HOME` is set.
|
||
- `mcporter daemon start --log-file /tmp/mcporter-daemon.log` — write logs to a specific file (path is created if needed).
|
||
- `mcporter daemon start --log-servers chrome-devtools,mobile-mcp` — only emit per-call entries for the listed servers. Without this flag, `--log` records every keep-alive server’s calls.
|
||
|
||
`mcporter daemon restart` accepts the same logging flags, so you can bounce the daemon without retyping your tracing preferences.
|
||
|
||
Foreground mode (`mcporter daemon start --foreground --log`) still prints to your terminal; the log file mirrors the same content.
|
||
|
||
### Environment overrides
|
||
|
||
Set these before invoking `mcporter` (helpful for scripts/CI):
|
||
|
||
- `MCPORTER_DAEMON_LOG=1` — enable logging.
|
||
- `MCPORTER_DAEMON_LOG_PATH=/tmp/mcporter-daemon.log` — custom log file.
|
||
- `MCPORTER_DAEMON_LOG_SERVERS=chrome-devtools,playwright` — per-server call filtering.
|
||
|
||
The CLI flags take precedence; env vars are the fallback.
|
||
|
||
### Per-server opt-in
|
||
|
||
Add a logging block inside the server definition (alongside `lifecycle`) when you only want a specific STDIO transport to produce call traces, regardless of global flags:
|
||
|
||
```json
|
||
"chrome-devtools": {
|
||
"description": "Chrome DevTools protocol bridge",
|
||
"command": "npx",
|
||
"args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"],
|
||
"lifecycle": "keep-alive",
|
||
"logging": {
|
||
"daemon": { "enabled": true }
|
||
}
|
||
}
|
||
```
|
||
|
||
When combined with `--log`/`MCPORTER_DAEMON_LOG=1`, any server that has `logging.daemon.enabled` emits `callTool start/success/error` lines even if it isn’t listed in `--log-servers`.
|
||
|
||
### Inspecting logs
|
||
|
||
- `mcporter daemon status` prints both the socket path and the current log file (if logging is enabled) so you can `tail -f` the output quickly.
|
||
- Each call looks like:
|
||
```
|
||
[daemon] 2025-11-10T15:08:21.123Z callTool start server=chrome-devtools tool=take_snapshot
|
||
[daemon] 2025-11-10T15:08:22.004Z callTool success server=chrome-devtools tool=take_snapshot
|
||
```
|
||
- Shutdown events and errors are logged the same way (`callTool error … err=...`, `listTools error …`, etc.).
|
||
|
||
### Defaults & cleanup
|
||
|
||
Log files live under `~/.mcporter/daemon/` next to the socket/metadata, or under `$XDG_STATE_HOME/mcporter/daemon/` when `XDG_STATE_HOME` is set. They’re not rotated automatically yet; delete/rotate them manually if they grow large. Running `mcporter daemon stop` leaves the log intact so you can inspect it after a crash.
|
||
|
||
## Foreground debugging
|
||
|
||
When troubleshooting deeply, run `mcporter daemon start --foreground --log` in a dedicated terminal. This keeps the daemon attached (so Ctrl+C stops it) and still writes to the configured log file for later inspection.
|