administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages
DocForge2/docs/VIEWER_MANAGER.md

3 KiB
Raw Blame History

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.

The same lifecycle is available without an MCP client:

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.

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:

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:

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.