2026-07-25 00:17:21 -04:00
|
|
|
# Viewer manager
|
|
|
|
|
|
|
|
|
|
DocForge graph viewers are owned by one local, per-user viewer-manager service. The MCP server
|
|
|
|
|
does not own browser workers. This prevents normal stdio MCP turnover from closing a page while it
|
|
|
|
|
is in use.
|
|
|
|
|
|
|
|
|
|
The manager listens only on `127.0.0.1` and chooses an ephemeral port. Its private state record
|
|
|
|
|
contains that port and a high-entropy capability token. The record lives in the current user's
|
|
|
|
|
runtime directory on Linux, Application Support directory on macOS, or Local AppData directory on
|
|
|
|
|
Windows. The manager starts no network listener beyond loopback.
|
|
|
|
|
|
|
|
|
|
One worker is reused per project binding and validated index snapshot. `docforge_visualize` replaces
|
|
|
|
|
the worker only after the snapshot changes. `docforge_visualization_status` reports its state, and
|
|
|
|
|
`docforge_stop_visualization` explicitly stops it.
|
|
|
|
|
|
2026-07-25 16:00:19 -04:00
|
|
|
The same lifecycle is available without an MCP client:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
docforge --project-root /absolute/path/MyProject reindex
|
|
|
|
|
docforge --project-root /absolute/path/MyProject visualize
|
|
|
|
|
docforge --project-root /absolute/path/MyProject visualization-status
|
|
|
|
|
docforge --project-root /absolute/path/MyProject visualization-stop
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`visualize` opens the default browser. Add `--no-open` to return JSON without launching it.
|
|
|
|
|
|
2026-07-25 00:17:21 -04:00
|
|
|
The default one-hour idle policy is intentional. Browser requests, including the existing visible
|
|
|
|
|
page heartbeat, renew activity. A page is never tied to the lifetime of one MCP request or host
|
|
|
|
|
process. The manager stops genuinely abandoned workers after an hour without activity. Stopping the
|
|
|
|
|
manager also stops all of its workers.
|
|
|
|
|
|
|
|
|
|
## Install the user service
|
|
|
|
|
|
|
|
|
|
Run this once in the same DocForge environment that will run the MCP server:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
docforge-viewer-manager install-user-service
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The command installs and starts the native user-level supervisor:
|
|
|
|
|
|
|
|
|
|
- Linux uses a `systemd --user` service with `Restart=on-failure` and `KillMode=control-group`.
|
|
|
|
|
- macOS uses a LaunchAgent under `~/Library/LaunchAgents`.
|
|
|
|
|
- Windows uses a per-user Task Scheduler entry named `DocForgeViewerManager`.
|
|
|
|
|
|
|
|
|
|
Use `docforge-viewer-manager uninstall-user-service` to stop and remove it. For development or a
|
|
|
|
|
nonstandard supervisor, run this foreground command instead:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
docforge-viewer-manager serve
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The service command intentionally uses the Python interpreter that installed it. After moving or
|
|
|
|
|
recreating the DocForge virtual environment, run the install command again so the native service
|
|
|
|
|
points at the new interpreter.
|
|
|
|
|
|
|
|
|
|
## Operational behavior
|
|
|
|
|
|
|
|
|
|
The manager is a small, long-lived control service. Its worker count is bounded by the number of
|
|
|
|
|
currently viewed project snapshots, not the number of MCP requests. A crashed manager is restarted
|
|
|
|
|
by the native supervisor. The supervisor stops child workers as one unit, avoiding orphan listeners.
|
|
|
|
|
|
|
|
|
|
MCP only receives a loopback URL after the manager has accepted the exact validated snapshot. If the
|
|
|
|
|
manager is unavailable, DocForge returns `visualization_manager_unavailable` with the state path so
|
|
|
|
|
the integration can be repaired without falling back to an unmanaged worker.
|
