bridge

name	bridge
description	Use when the user says "bridge", "remote", "ssh tool", "run on host", "check host", "configure host", "setup bridge", or wants to manage remote servers or bridge config via CLI.
user-invocable	true
disable-model-invocation	false
argument-hint	[tool|config|status] [args...]

SSH Bridge CLI — Remote Tool Execution and Configuration

Execute MCP tools on remote hosts or manage bridge configuration via the token-efficient CLI.

Current state

Host status: !bridge-mcp status 2>/dev/null || echo "CLI binary not found — run 'make build' or 'cargo install --path .'"

Instructions

No arguments or status

Show host status (above) and available tool groups: !bridge-mcp list-tools --groups-only

Then ask the user what they want to do.

Config mode

Help the user configure the bridge. Show current config state:

1. Config file location: ~/.config/bridge-mcp/config.yaml
2. Validate current config: !bridge-mcp validate 2>&1
3. Show diff vs defaults: !bridge-mcp config-diff 2>&1

Then guide the user through configuration. The config file has these sections:

Adding a host:

hosts:
  my-server:
    hostname: 192.168.1.100
    port: 22
    user: admin
    description: "My server"
    auth:
      type: key              # key | password | agent
      path: ~/.ssh/id_ed25519
    # os_type: windows       # for Windows hosts
    # shell: powershell      # for Windows: cmd (default) or powershell
    # proxy_jump: bastion    # connect through a jump host

Security modes:

security:
  mode: standard     # strict = whitelist only | standard = whitelist for exec, blacklist for tools | permissive = blacklist only
  whitelist:
    - "^docker\\s+(ps|logs|inspect).*"   # regex patterns
  blacklist:
    - "rm\\s+(-[a-zA-Z]*r|--recursive)"  # always denied
  sanitize:
    enabled: true    # mask secrets in output (~50 builtin patterns)

Filtering tool groups (reduce MCP context):

tool_groups:
  groups:
    docker: false       # disable docker tools
    kubernetes: false   # disable k8s tools
    # Set any of the 74 groups to false to disable

SSH config auto-discovery:

ssh_config:
  enabled: true   # auto-import hosts from ~/.ssh/config

Reference: config/config.example.yaml has the full documented example.

Config validate

Validate the configuration: !bridge-mcp validate 2>&1

Config diff

Compare current config with defaults: !bridge-mcp config-diff 2>&1

Tool group name (e.g., docker, kubernetes, systemd)

List tools in that group: !bridge-mcp list-tools --group $ARGUMENTS

Search query (no "=" in args, not a known subcommand)

Search tools by keyword: !bridge-mcp list-tools --search $ARGUMENTS

Tool name with key=value pairs

Execute the tool directly: !bridge-mcp --json tool $ARGUMENTS

Token-efficient invocation

ALWAYS run describe-tool before invoking a tool you haven't used recently — its schema (with RECOMMENDED: hints) lists which reduction params apply and costs ~200 tokens:

bridge-mcp describe-tool <tool_name>

Apply the right reduction strategy based on the tool's Reduction Strategy line (shown at the top of describe-tool output):

Output kind	Strategy	Example
Tabular (docker_ps, service_list, process_list)	columns + limit	columns='["NAME","STATUS"]' limit=20
Json (k8s_get, docker_inspect, awx_*)	jq_filter + output_format=tsv	jq_filter='.items[] | [.metadata.name, .status.phase]' output_format=tsv
Yaml	yq_filter + output_format=tsv	same shape as jq
Auto	Any of the above	tool auto-detects
RawText (logs, arbitrary exec)	save_output=/tmp/out.txt	read the file locally afterwards

Ergonomic global flags (alternatives to jq_filter=, columns=, limit=):

bridge-mcp --jq '.items[] | {name, phase}' --output-format=tsv tool ssh_k8s_get host=k8s resource=pods
bridge-mcp --columns name,status --limit 10 tool ssh_docker_ps host=prod

Pagination cycle for truncated output:

1. A truncated result prints [output_id: abc123]
2. Fetch the rest: bridge-mcp tool ssh_output_fetch output_id=abc123 offset=N

Common params on every tool: host, timeout_seconds, max_output, save_output.

Prefer server-side jq_filter over piping CLI stdout through jq — the filter runs BEFORE truncation, so you don't lose data to the cap.

Workflow reminders

1. Verify connectivity with status before executing tools
2. Use --json output for structured parsing
3. Use --dry-run before destructive operations
4. Report results clearly with host name and command executed
5. Run describe-tool first on unknown tools — the schema tells you which reduction params apply and is ~200 tokens
6. Prefer output_format=tsv for list-style JSON — 60-80% fewer tokens than pretty JSON