remote-observer-mcp

remote-observer-mcp gives ChatGPT a broad read-only view of explicitly registered local and SSH-accessible hosts and workspaces without exposing arbitrary shell execution, arbitrary hostnames, or arbitrary filesystem roots.

The repository also contains a separate Execution Bridge for exact commands and break-glass shell scripts. That bridge is intentionally not an MCP tool: every execution waits on an independent GitHub Environment approval before a self-hosted runner can invoke remote-observer-exec.

Architecture

ChatGPT
  |
  +-- read lane
  |    -> OpenAI Secure MCP Tunnel
  |    -> tunnel-client on gateway
  |    -> remote-observer-mcp (stdio child)
  |    -> logical host/workspace registry
  |    -> semantic observer
  |    -> preferred CLI / safe fallback
  |    -> local or strict SSH transport
  |    -> bounded + redacted result and metadata-only audit
  |
  +-- execution lane
       -> committed versioned execution request
       -> workflow_dispatch(request_id only)
       -> hosted validation + request digest
       -> GitHub Environment: remote-execution
       -> required reviewer approval
       -> [self-hosted, remote-observer] runner
       -> remote-observer-exec
       -> registered local or SSH target

Design and implementation records are under docs/superpowers/specs/ and docs/superpowers/plans/. Gateway deployment is in deploy/README.md; execution-runner deployment is in deploy/execution-runner.md; all remaining real-account/credential/runner operations are batched in USER_ACTIONS.md.

Safety boundary

The public MCP surface is semantic and read-only. It does not provide:

• arbitrary execute, shell, ssh, command, argv, script, hostname, URL, method, or absolute-path tools;
• arbitrary file reads outside registered workspace roots;
• tmux send-keys / run-shell or session mutation;
• fd --exec, AST rewrite/fix, yq in-place writes, Docker exec/inspect, package install/update, archive extraction, or service/process mutation;
• automatic software installation or privilege elevation.

Hosts, workspaces and resources are referenced by logical IDs in a gateway-local TOML registry. Unknown or unsafe identifiers fail closed. Local observer processes use asyncio.create_subprocess_exec; SSH uses registered aliases with BatchMode=yes, StrictHostKeyChecking=yes, and a bounded connection timeout.

Read-only does not mean secret-free. Logs, diffs and workspace files can contain sensitive material. Collection uses allowlists and secret-path denial as the primary boundary. Output is bounded and best-effort redacted before crossing MCP. Metadata-only audit records never store raw observed output or argv.

Read-only MCP tools

Every tool is annotated read-only, non-destructive, idempotent and closed-world.

Host discovery and baseline system state

• list_hosts
• host_overview
• system_status
• disk_usage
• process_status

Workspaces and files

• list_workspaces
• workspace_find
• workspace_search
• workspace_read
• workspace_tree
• file_info
• checksum

Workspace inputs use a logical workspace ID plus validated relative paths. Concrete roots stay in local configuration and are not returned by discovery tools. Common secret paths such as .env, private keys and credential files are denied before content collection.

Code and structured data

• code_search
• json_query
• structured_query

code_search uses search-only ast-grep; rewrite/fix options are not exposed. Structured selectors use a narrow dot-key / array-index grammar rather than arbitrary jq/yq programs.

tmux

• tmux_sessions
• tmux_windows
• tmux_panes
• tmux_capture

Only list/capture operations exist. tmux_capture is bounded; no key injection or tmux mutation is exposed.

Processes, network, filesystem and hardware

• process_list
• process_tree
• network_listeners
• network_interfaces
• network_routes
• dns_lookup
• filesystem_status
• disk_hotspots
• user_sessions
• hardware_info
• sensor_status

Process observation avoids environment variables and full command lines by default. Network observation is passive; there is no port scan or arbitrary socket/URL probe.

systemd and journals

• service_status
• service_logs
• service_failures
• systemd_timers
• journal_query

Log access is opt-in per registered service. journal_query accepts only fixed, bounded time/priority/line filters for registered services.

Docker and Compose

• container_list
• container_logs
• container_stats
• compose_status

Only configured containers are returned. Container logs are opt-in. Compose status is enabled only for workspaces with compose = true. No Docker exec/inspect/mutation exists in the MCP lane.

Git

• repo_status
• repo_diff
• repo_log

Git diff collection excludes common sensitive paths plus validated configured patterns. Remote URLs are not part of the observer surface.

NVIDIA GPU

• gpu_status
• gpu_processes

Both use fixed nvidia-smi query fields; no process control is exposed.

Runtime, toolchain, package and archive inspection

• tool_availability
• runtime_versions
• python_environment
• node_environment
• rust_environment
• cargo_metadata
• nix_environment
• mise_environment
• package_info
• archive_list

cargo_metadata is offline. Nix observation uses offline/read-oriented metadata queries and does not build, update profiles or write lock files. archive_list lists members without extraction.

Preferred CLI and fallback behavior

The MCP API is independent of which CLI is installed. Backends are package-owned constants; model input never chooses an executable or flags.

Current preference chains include:

Capability	Preferred	Fallback
text search	rg	grep
file discovery	fd	find
tree view	eza	find
disk hotspots	dust	du
process list	procs	ps
checksum	b3sum	sha256sum, then shasum -a 256
JSON	native parser	-
structured data	fixed yq where required	native JSON/TOML parser where supported

If no safe equivalent backend exists, the tool returns unsupported_capability. The MCP never installs missing software automatically. A fallback is rejected when it cannot preserve the requested security policy; for example, a grep fallback will not silently ignore a configured exclusion it cannot safely represent.

Runtime configuration

Runtime configuration normally lives at:

~/.config/remote-observer-mcp/config.toml

or at the path selected by REMOTE_OBSERVER_CONFIG. The gateway runbook uses /etc/remote-observer-mcp/config.toml.

Start from config.example.toml. Do not store passwords, API keys, SSH private keys or other credentials in this TOML file.

Example:

[hosts.gateway]
transport = "local"

[hosts.remote]
transport = "ssh"
ssh_alias = "example-host"
gpu = true

[hosts.remote.services.app]
unit = "app.service"
logs = false

[hosts.remote.containers.api]
name = "api"
logs = false

[hosts.remote.repos.app]
path = "/srv/app"
secret_patterns = ["private/**"]

[workspaces.app]
host = "remote"
root = "/srv/app"
secret_patterns = ["private/**"]
compose = false

The v1 identifier/path grammars are deliberately narrow. Add legitimate unsupported naming conventions through a reviewed schema change instead of bypassing validation.

Development and deterministic verification

Requirements: Python 3.12.

python -m pip install -e '.[dev]'
python -m ruff check .
python -m pytest -q
python scripts/smoke_stdio.py

The deterministic suite does not require real SSH hosts, credentials, Docker, systemd, NVIDIA hardware, modern CLI installations, Secure MCP Tunnel access, a GitHub Environment, or a self-hosted runner. Observer/backend tests use fake transports where appropriate. scripts/smoke_stdio.py performs a real MCP stdio initialize/list-tools/call exchange against a temporary local config.

Run the read-only MCP server

export REMOTE_OBSERVER_CONFIG="$HOME/.config/remote-observer-mcp/config.toml"
remote-observer-mcp

This command expects an MCP client on stdin/stdout. In production, tunnel-client spawns it as its stdio child; it is not a separate standalone daemon. See deploy/README.md.

Execution Bridge

Arbitrary or mutating work belongs to the separate approval-gated execution lane, not to MCP.

Execution requests are versioned JSON documents. mode="argv" preserves an exact argument vector and runs without a local shell. mode="shell" is break-glass, always risk R4, and uses a fixed bash -lc implementation after approval. Requests are bounded, reject secret-like literals, resolve only registered hosts/workspaces, and produce a SHA-256 request digest plus sanitized execution evidence.

The executor entry point is:

remote-observer-exec <request_id>

The GitHub workflow accepts only request_id, validates the committed request on a hosted runner, then gates the self-hosted execution job itself on Environment remote-execution. No Issue body, comment, PR title, branch text, command, script, argv, host or path is accepted as executable workflow input.

All R1-R4 executions require the independent Environment approval in v1. See execution_requests/README.md and deploy/execution-runner.md.

Gateway deployment and production acceptance

The read-lane production supervisor is tunnel-client; it owns the stdio child lifecycle and systemd owns the tunnel-client process. The deployment sequence is:

1. deterministic local MCP smoke;
2. optional short gateway/tmux Tunnel smoke;
3. managed gateway/systemd service;
4. ChatGPT read-tool acceptance.

The Execution Bridge has a separate acceptance sequence for the GitHub Environment and self-hosted runner.

No real Tunnel, SSH, Environment approval or self-hosted execution is required by repository CI. USER_ACTIONS.md contains those remaining steps, including the no-extra-cost gate before account-backed Secure MCP Tunnel traffic.

Supported target assumptions

v1 system/service/Docker/Git/GPU observation is primarily designed for Linux targets. The gateway may be a Mac during development. SSH remote command serialization assumes a POSIX-compatible remote login shell; Windows remote targets are outside v1.

Validation status semantics

• PASS: the stated command/check was actually run and passed.
• FAIL: it was run and failed.
• NOT RUN: intentionally not executed.
• BLOCKED: a required user-controlled dependency/environment is unavailable.

Real SSH, Secure MCP Tunnel, GitHub remote-execution approval, self-hosted runner, and ChatGPT production acceptance remain NOT RUN until the steps in USER_ACTIONS.md are performed. Deterministic CI success must not be presented as production connectivity.