muchiny/bridge-mcp

# Bridge MCP ## 目录 - [功能](#features) - [核心工作流](#hero-workflows) - [快速开始](#quick-start) - [架构](#architecture) - [配置](#configuration) - [工具组](#tool-groups) - [MCP Prompts 与 Resources](#mcp-prompts--resources) - [CLI 用法](#cli-usage) - [Daemon 模式](#daemon-mode) - [故障排除](#troubleshooting) - [开发](#development) - [许可证](#license) ## 功能 - **357 个工具，75 个组** —— 管理 Linux、Windows、Docker、Kubernetes、Podman、AWX、数据库、LDAP、网络设备、证书等 - **9 种协议适配器** —— SSH、WinRM、PSRP (PowerShell Remoting)、Telnet、K8s Exec、Serial、AWS SSM、Azure、GCP - **安全第一** —— 命令白名单/黑名单，62 种机密脱敏模式 + 熵检测，防篡改会话记录，针对破坏性操作可选的 MCP elicitation 确认机制 - **自动发现** —— 自动读取 `~/.ssh/config`，并与 YAML 配置合并 - **智能输出** —— 服务器端 `jq_filter` / `yq_filter` / `columns` / `limit`，TSV 模式（节省 60-80% token），通过 `ssh_output_fetch` 分页，针对每个客户端的大小限制（参见 [Token 高效输出](#token-efficient-output)） - **渐进式 MCP 发现** —— 三个元工具（`mcp_list_tool_groups`、`mcp_search_tools`、`mcp_describe_tool`）让客户端按需浏览注册表，而不是预先加载所有 357 个 schema - **MCP Tasks 支持** —— 每个工具都宣告了 `taskSupport: "optional"`，支持长时间运行操作的异步取消和进度通知 - **CLI + MCP** —— 所有工具均可作为 CLI 命令使用（节省 10-32 倍 token）或通过 MCP JSON-RPC 访问 - **Daemon 模式** —— 使用 Unix socket 传输以支持多客户端本地使用；内置 `WinRmPool`（120 秒 TTL）和 `K8sExecPool`（300 秒 TTL），在多次调用中分摊 TLS 握手开销 - **7500+ 测试** —— `#![forbid(unsafe_code)]`，Rust 2024 版本，严格的 clippy ## 核心工作流 四个端到端的示例展示了本项目存在的意义。每个命令都通过同一个 CLI 二进制文件运行；所有 357 个工具都遵循相同的标志约定（`--jq`、`--columns`、`--limit`、`--output-format`）。 ### 1. 使用 4 条命令诊断 Linux 服务 ``` bridge-mcp status # check host reachability bridge-mcp tool ssh_service_status host=web1 service=nginx bridge-mcp tool ssh_service_logs host=web1 service=nginx lines=200 bridge-mcp tool ssh_journal_query host=web1 unit=nginx priority=err since="-1h" ``` 内置验证机制会在任何 SSH 字节离开您的机器之前拒绝未知主机；输出会通过 62 种机密脱敏模式 + 熵检测进行净化。 ### 2. 节省 80% 的 token 检查 Kubernetes ``` # Dump 所有 pods → 50 KB JSON。通过服务端 jq 管道处理 → ~6 KB TSV。 bridge-mcp --jq '.items[] | [.metadata.name, .status.phase, .spec.nodeName]' \ --output-format=tsv \ tool ssh_k8s_get host=k8s resource=pods namespace=default bridge-mcp tool ssh_k8s_describe host=k8s resource=pod name=api-7d-xyz namespace=default bridge-mcp tool ssh_k8s_logs host=k8s pod=api-7d-xyz container=app tail=100 ``` 过滤发生在**服务器端，即在截断之前** —— 您绝不会因输出上限而丢失数据。同样的模式也适用于 `ssh_docker_inspect`、`ssh_helm_status`、`ssh_awx_*` 等。 ### 3. 跨平台：通过一个 CLI 同时管理 Windows + Linux ``` # Linux 主机 bridge-mcp tool ssh_service_status host=web1 service=postgres # Windows 主机（底层使用 WinRM/PSRP — 目标机器上无需安装 agent） bridge-mcp tool ssh_win_service_status host=appsrv service=W3SVC bridge-mcp tool ssh_iis_restart host=appsrv name=DefaultAppPool bridge-mcp tool ssh_win_event_query host=appsrv log=System level=Error since="-1h" ``` 13 个 Windows 工具组（服务、事件、AD、IIS、计划任务、注册表、Hyper-V……）完美映射到相同的 `ssh_*` 命名空间，您的 prompt 中无需切换协议。 ### 4. 带 elicitation 的已审计破坏性操作 ``` # config.yaml security: require_elicitation_on_destructive: true # MCP elicitation/create before any destructive_hint:true tool recording: enabled: true # tamper-proof asciinema recordings audit: log_path: /var/log/bridge-mcp/audit.jsonl ``` ``` bridge-mcp tool ssh_helm_rollback host=k8s release=api revision=7 # → MCP 客户端（Claude Code 等）在调用离开 bridge 之前会显示确认对话框。 # → Audit log 记录 prompt、args、脱敏的 stdout、exit code 和 duration。 ``` 调度器会区分每个工具的 `read_only`、`mutating`、`mutating_idempotent` 与 `destructive` 属性（通过 `tests/annotation_audit.rs` 进行审计），因此只有当状态确实发生改变时才会触发确认。 ## 快速开始 ### 1. 安装 ``` # Linux x86_64（推荐） curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-linux-x86_64.tar.gz | tar xz sudo mv bridge-mcp /usr/local/bin/ ```

其他平台与方法

``` # Linux aarch64（Raspberry Pi、ARM 服务器） curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-linux-arm64.tar.gz | tar xz sudo mv bridge-mcp /usr/local/bin/ # macOS（Apple Silicon） curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-macos-arm64.tar.gz | tar xz sudo mv bridge-mcp /usr/local/bin/ # Docker docker pull ghcr.io/muchiny/bridge-mcp:latest # 从 source git clone https://github.com/muchiny/bridge-mcp && cd bridge-mcp && make release ``` **Claude Desktop (DXT)：** 从 [Releases](https://github.com/muchiny/bridge-mcp/releases/latest) 下载 `.dxt` 文件，并将其拖拽到 Claude Desktop 中。

### 2. 配置 ``` mkdir -p ~/.config/bridge-mcp cp config/config.example.yaml ~/.config/bridge-mcp/config.yaml ``` 编辑 `~/.config/bridge-mcp/config.yaml` 并添加您的主机： ``` hosts: my-server: hostname: 192.168.1.100 port: 22 user: admin auth: type: key path: ~/.ssh/id_ed25519 description: "My server" ``` ### 3. 添加至 Claude Code 添加至 `~/.claude/settings.json`： ``` { "mcpServers": { "ssh-bridge": { "command": "bridge-mcp" } } } ``` ### 4. 验证 重启 Claude Code，然后询问：*"Check the health of my-server"* —— 或者运行： ``` bridge-mcp status ``` ## 架构 Bridge MCP 位于 Claude Code 和您的基础设施之间。它通过 9 个协议适配器路由命令，并内置了安全验证、输出净化和审计日志记录。 ``` graph LR CC[Claude Code] -->|JSON-RPC stdio or Unix socket| BR[Bridge MCP] BR --> SEC[Security
Validator · Sanitizer · Audit] SEC --> ER[Executor Router] subgraph "Air-Gapped Protocols" ER -->|SSH| P1[Linux / Windows
Docker · K8s · Network] ER -->|WinRM| P2[Windows] ER -->|PSRP| P2b[PowerShell Remoting] ER -->|Telnet| P3[Legacy Devices] end subgraph "Infrastructure Protocols" ER -->|K8s API| P6[K8s Exec] ER -->|Serial| P7[Serial Devices] end subgraph "Cloud Protocols" ER -->|SSM · Azure · GCP| P9[Cloud Instances] end ``` ## 配置 配置文件：`~/.config/bridge-mcp/config.yaml` —— 完整参考请参阅 [config.example.yaml](config/config.example.yaml)。

身份验证方法

| 方法 | 配置 | 说明 | |--------|--------|-------| | SSH Key | `type: key` + `path: ~/.ssh/id_ed25519` | 推荐。支持可选的 `passphrase`。 | | SSH Agent | `type: agent` | 使用 `SSH_AUTH_SOCK`。推荐。 | | Password | `type: password` + `password: "..."` | 尽量避免使用。 | 请先验证您的 SSH 访问权限：`ssh user@hostname "echo OK"`

安全规则

三种模式控制 Claude 可以运行哪些命令： | 模式 | 行为 | |------|----------| | `strict` | 仅允许白名单中的命令（最安全） | | `standard` | `ssh_exec` 使用白名单，内置工具仅检查黑名单（默认） | | `permissive` | 仅检查黑名单（最开放） | **黑名单始终会被优先检查** —— 匹配的命令将始终被拒绝。 ``` security: mode: standard whitelist: - "^docker\\s+(ps|logs|inspect).*" - "^kubectl\\s+(get|describe|logs).*" - "^(ls|cat|head|tail|grep|df|free)\\s*.*" blacklist: - "rm\\s+(-[a-zA-Z]*r|--(recursive|force))" - "mkfs\\." - "dd\\s+if=" - "curl.*\\|.*sh" ```

高级主机（跳板机、SOCKS 代理、Windows、sudo）

**跳板机 (bastion)：** ``` hosts: bastion: hostname: bastion.example.com user: admin auth: { type: agent } internal-db: hostname: 10.0.0.5 proxy_jump: bastion user: deploy auth: { type: key, path: ~/.ssh/id_ed25519 } ``` **SOCKS 代理：** ``` hosts: behind-proxy: hostname: 10.0.0.50 user: deploy socks_proxy: hostname: proxy.corp.com port: 1080 version: socks5 auth: { type: key, path: ~/.ssh/id_ed25519 } ``` **Windows 服务器** —— 添加 `os_type: windows` 以启用 74 个特定于 Windows 的工具： ``` hosts: windows-dc: hostname: 192.168.1.200 user: Administrator os_type: windows shell: powershell auth: { type: key, path: ~/.ssh/id_ed25519 } ``` **Sudo 支持：** ``` hosts: prod-server: hostname: 192.168.1.100 user: deploy sudo_password: "your-sudo-password" auth: { type: key, path: ~/.ssh/id_ed25519 } ``` **SSH config 自动发现** —— 来自 `~/.ssh/config` 的主机会被自动合并。要排除特定主机： ``` ssh_config: enabled: true exclude: [personal-server] ```

限制、净化与审计

**限制：** ``` limits: command_timeout_seconds: 60 connection_timeout_seconds: 10 max_concurrent_commands: 5 max_output_chars: 20000 # 0 = unlimited rate_limit_per_second: 0 # 0 = disabled retry_attempts: 3 client_overrides: # Per-client output limits - name_contains: claude max_output_chars: 80000 ``` 被截断的输出会包含一个 `output_id` —— 使用 `ssh_output_fetch` 逐页检索完整内容。 **输出净化** —— 56 个内置正则表达式模式 + 用于检测机密的 Shannon 熵检测： ``` security: sanitize: enabled: true entropy_detection: true entropy_threshold: 4.5 custom_patterns: - pattern: "INTERNAL_[A-Z0-9]{32}" replacement: "[INTERNAL_REDACTED]" ``` **破坏性操作确认** —— 可选的门控机制，在任何标记为 `destructive_hint: true` 的工具（`ssh_terraform_apply`、`ssh_k8s_delete`、`ssh_cron_remove`、`ssh_win_update_reboot`……）执行之前，要求用户通过 MCP `elicitation/create` 进行确认。需要客户端宣告支持 elicitation 能力（Claude Desktop、Claude Code）： ``` security: require_elicitation_on_destructive: true # default: false ``` **审计日志：** ``` audit: enabled: true path: ~/.local/share/bridge-mcp/audit.log max_size_mb: 100 retain_days: 30 ``` **会话记录** —— 带 HMAC-SHA256 哈希链的 asciinema v2 格式（SOC2、HIPAA、PCI-DSS）： ``` recording: enabled: true path: ~/.local/share/bridge-mcp/recordings/ hash_chain: true hash_key_env: MCP_RECORDING_KEY ```

## 工具组 357 个工具分为 75 个组 —— 默认全部启用。禁用不需要的组： ``` tool_groups: groups: sessions: false tunnels: false database: false ```

Linux 与跨平台组（41 个组）

| 组 | 工具 | |-------|-------| | `core` | ssh_exec, ssh_exec_multi (附带 `diff` / `diff_baseline` / `normalize` 用于跨主机漂移检测), ssh_status, ssh_health, ssh_history, ssh_output_fetch | | `config` | ssh_config_get, ssh_config_set | | `file_transfer` | ssh_upload, ssh_download, ssh_sync | | `file_ops` | ssh_file_read, ssh_file_write, ssh_file_chmod, ssh_file_chown, ssh_file_stat, ssh_file_diff, ssh_file_patch, ssh_file_template | | `sessions` | ssh_session_create, ssh_session_exec, ssh_session_list, ssh_session_close | | `monitoring` | ssh_metrics, ssh_metrics_multi, ssh_tail, ssh_disk_usage | | `tunnels` | ssh_tunnel_create, ssh_tunnel_list, ssh_tunnel_close | | `directory` | ssh_ls, ssh_find | | `database` | ssh_db_query, ssh_db_dump, ssh_db_restore | | `redis` | ssh_redis_info, ssh_redis_cli, ssh_redis_keys | | `postgresql` | ssh_postgresql_query, ssh_postgresql_status | | `mysql` | ssh_mysql_query, ssh_mysql_status | | `mongodb` | ssh_mongodb_status | | `backup` | ssh_backup_create, ssh_backup_list, ssh_backup_restore, ssh_backup_snapshot, ssh_backup_verify, ssh_backup_schedule | | `docker` | ssh_docker_ps, ssh_docker_logs, ssh_docker_inspect, ssh_docker_exec, ssh_docker_compose, ssh_docker_images, ssh_docker_stats, ssh_docker_volume_ls, ssh_docker_network_ls, ssh_docker_volume_inspect, ssh_docker_network_inspect | | `podman` | ssh_podman_ps, ssh_podman_logs, ssh_podman_inspect, ssh_podman_exec, ssh_podman_images, ssh_podman_compose | | `esxi` | ssh_esxi_vm_list, ssh_esxi_vm_info, ssh_esxi_vm_power, ssh_esxi_snapshot, ssh_esxi_host_info, ssh_esxi_datastore_list, ssh_esxi_network_list | | `kubernetes` | ssh_k8s_get, ssh_k8s_logs, ssh_k8s_describe, ssh_k8s_apply, ssh_k8s_delete, ssh_k8s_rollout, ssh_k8s_scale, ssh_k8s_exec, ssh_k8s_top, ssh_helm_list, ssh_helm_status, ssh_helm_upgrade, ssh_helm_install, ssh_helm_rollback, ssh_helm_history, ssh_helm_uninstall | | `git` | ssh_git_status, ssh_git_log, ssh_git_diff, ssh_git_pull, ssh_git_clone, ssh_git_branch, ssh_git_checkout | | `ansible` | ssh_ansible_playbook, ssh_ansible_inventory, ssh_ansible_adhoc | | `awx` | ssh_awx_status, ssh_awx_inventories, ssh_awx_inventory_hosts, ssh_awx_templates, ssh_awx_template_detail, ssh_awx_job_launch, ssh_awx_job_status, ssh_awx_job_summary, ssh_awx_job_stdout, ssh_awx_job_events, ssh_awx_job_follow, ssh_awx_job_cancel, ssh_awx_project_sync | | `terraform` | ssh_terraform_init, ssh_terraform_plan, ssh_terraform_apply, ssh_terraform_state, ssh_terraform_output | | `vault` | ssh_vault_status, ssh_vault_read, ssh_vault_list, ssh_vault_write | | `systemd` | ssh_service_status, ssh_service_start, ssh_service_stop, ssh_service_restart, ssh_service_list, ssh_service_logs, ssh_service_enable, ssh_service_disable, ssh_service_daemon_reload | | `systemd_timers` | ssh_timer_list, ssh_timer_info, ssh_timer_enable, ssh_timer_disable, ssh_timer_trigger | | `network` | ssh_net_connections, ssh_net_interfaces, ssh_net_routes, ssh_net_ping, ssh_net_traceroute, ssh_net_dns | | `process` | ssh_process_list, ssh_process_kill, ssh_process_top | | `package` | ssh_pkg_list, ssh_pkg_search, ssh_pkg_install, ssh_pkg_update, ssh_pkg_remove | | `firewall` | ssh_fire_status, ssh_firewall_list, ssh_firewall_allow, ssh_firewall_deny | | `cron` | ssh_cron_list, ssh_cron_add, ssh_cron_remove | | `cron_analysis` | ssh_cron_analyze, ssh_cron_history, ssh_at_jobs | | `certificates` | ssh_cert_check, ssh_cert_info, ssh_cert_expiry | | `letsencrypt` | ssh_letsencrypt_status | | `nginx` | ssh_nginx_status, ssh_nginx_test, ssh_nginx_reload, ssh_nginx_list_sites | | `apache` | ssh_apache_status, ssh_apache_vhosts | | `user_management` | ssh_user_list, ssh_user_info, ssh_user_add, ssh_user_modify, ssh_user_delete, ssh_group_list, ssh_group_add, ssh_group_delete | | `storage` | ssh_storage_lsblk, ssh_storage_df, ssh_storage_mount, ssh_storage_umount, ssh_storage_lvm, ssh_storage_fdisk, ssh_storage_fstab | | `journald` | ssh_journal_query, ssh_journal_follow, ssh_journal_boots, ssh_journal_disk_usage | | `security_modules` | ssh_selinux_status, ssh_selinux_booleans, ssh_apparmor_status, ssh_apparmor_profiles, ssh_security_audit | | `network_equipment` | ssh_net_equip_show_run, ssh_net_equip_show_interfaces, ssh_net_equip_show_routes, ssh_net_equip_show_arp, ssh_net_equip_show_version, ssh_net_equip_show_vlans, ssh_net_equip_config, ssh_net_equip_save | | `ldap` | ssh_ldap_search, ssh_ldap_user_info, ssh_ldap_group_members, ssh_ldap_add, ssh_ldap_modify |

Windows 组（13 个组）

| 组 | 工具 | |-------|-------| | `windows_services` | ssh_win_service_list, ssh_win_service_status, ssh_win_service_start, ssh_win_service_stop, ssh_win_service_restart, ssh_win_service_enable, ssh_win_service_disable, ssh_win_service_config | | `windows_events` | ssh_win_event_query, ssh_win_event_logs, ssh_win_event_sources, ssh_win_event_tail, ssh_win_event_export | | `active_directory` | ssh_ad_user_list, ssh_ad_user_info, ssh_ad_group_list, ssh_ad_group_members, ssh_ad_computer_list, ssh_ad_domain_info | | `scheduled_tasks` | ssh_schtask_list, ssh_schtask_info, ssh_schtask_run, ssh_schtask_enable, ssh_schtask_disable | | `windows_firewall` | ssh_win_firewall_status, ssh_win_firewall_list, ssh_win_firewall_allow, ssh_win_firewall_deny, ssh_win_firewall_remove | | `iis` | ssh_iis_list_sites, ssh_iis_list_pools, ssh_iis_status, ssh_iis_start, ssh_iis_stop, ssh_iis_restart | | `windows_updates` | ssh_win_update_list, ssh_win_update_search, ssh_win_update_install, ssh_win_update_history, ssh_win_update_reboot | | `windows_perf` | ssh_win_perf_overview, ssh_win_perf_cpu, ssh_win_perf_memory, ssh_win_perf_disk, ssh_win_perf_network, ssh_win_disk_usage | | `hyperv` | ssh_hyperv_vm_list, ssh_hyperv_vm_info, ssh_hyperv_vm_start, ssh_hyperv_vm_stop, ssh_hyperv_host_info, ssh_hyperv_switch_list, ssh_hyperv_snapshot_list, ssh_hyperv_snapshot_create | | `windows_registry` | ssh_reg_query, ssh_reg_list, ssh_reg_set, ssh_reg_delete, ssh_reg_export | | `windows_features` | ssh_win_feature_list, ssh_win_feature_info, ssh_win_feature_install, ssh_win_feature_remove | | `windows_network` | ssh_win_net_ip, ssh_win_net_adapters, ssh_win_net_connections, ssh_win_net_routes, ssh_win_net_ping, ssh_win_net_dns | | `windows_process` | ssh_win_process_list, ssh_win_process_top, ssh_win_process_info, ssh_win_process_by_name, ssh_win_process_kill |

高级组（21 个组）

| 组 | 工具 | 说明 | |-------|-------|-------------| | `diagnostics` | ssh_diagnose, ssh_incident_triage, ssh_compare_state | 智能单次调用诊断与基于症状的分诊 | | `runbooks` | ssh_runbook_list, ssh_runbook_execute, ssh_runbook_validate | YAML 定义的多步骤操作程序 ([文档](config/runbooks/README.md)) | | `orchestration` | ssh_canary_exec, ssh_rolling_exec, ssh_fleet_diff | Canary 部署、滚动更新、全集群比较 | | `recording` | ssh_recording_start, ssh_recording_stop, ssh_recording_list, ssh_recording_replay, ssh_recording_verify | 防篡改会话记录 (SOC2/HIPAA/PCI-DSS) | | `drift` | ssh_env_snapshot, ssh_env_diff, ssh_env_drift | 环境状态捕获与漂移检测 | | `security_scan` | ssh_sbom_generate, ssh_vuln_scan, ssh_compliance_check | SBOM、漏洞扫描、CIS 合规性检查 | | `performance` | ssh_perf_trace, ssh_io_trace, ssh_latency_test, ssh_benchmark | 性能分析、I/O 跟踪、基准测试 | | `container_logs` | ssh_container_log_search, ssh_container_log_stats, ssh_container_events, ssh_container_health_history | 容器日志分析与健康追踪 | | `network_security` | ssh_port_scan, ssh_ssl_audit, ssh_network_capture, ssh_fail2ban_status | 端口扫描、SSL 审计、流量捕获、fail2ban | | `compliance` | ssh_cis_benchmark, ssh_stig_check, ssh_compliance_score, ssh_compliance_report | CIS/STIG 基准与合规性报告 | | `cloud` | ssh_aws_cli, ssh_cloud_metadata, ssh_cloud_tags, ssh_cloud_cost | 云服务提供商交互 | | `inventory` | ssh_discover_hosts, ssh_inventory_sync, ssh_host_tags | 主机发现与 CMDB 同步 | | `multicloud` | ssh_multicloud_list, ssh_multicloud_sync, ssh_multicloud_compare | 多云资源管理 | | `alerting` | ssh_alert_check, ssh_alert_list, ssh_alert_set | 指标监控、阈值检查、告警规则 | | `capacity` | ssh_capacity_collect, ssh_capacity_trend, ssh_capacity_predict | 容量数据收集、趋势分析、预测 | | `incident` | ssh_incident_timeline, ssh_incident_correlate | 事件响应时间线与日志关联 | | `log_aggregation` | ssh_log_aggregate, ssh_log_search_multi, ssh_log_tail_multi | 跨主机日志聚合、搜索、追踪 | | `key_management` | ssh_key_generate, ssh_key_distribute, ssh_key_audit | SSH 密钥生成、分发、审计 | | `chatops` | ssh_webhook_send, ssh_notify | Slack/Teams/webhook 通知 | | `templates` | ssh_template_list, ssh_template_show, ssh_template_apply, ssh_template_validate, ssh_template_diff | 配置模板管理 | | `pty` | ssh_pty_exec, ssh_pty_interact, ssh_pty_resize | 交互式 PTY 会话 |

## MCP Prompts 与 Resources

预构建 prompts

| Prompt | 说明 | 必需参数 | |--------|-------------|---------------| | `system-health` | 完整系统健康检查 (CPU、内存、磁盘、服务) | `host` | | `deploy` | 逐步骤部署工作流 | `host`, `service` | | `security-audit` | 安全状况评估 | `host` | | `troubleshoot` | 系统性故障排除指南 | `host`, `symptom` | | `docker-health` | Docker/容器健康评估 | `host` | | `k8s-overview` | Kubernetes 集群状态概览 | `host` | | `backup-verify` | 备份完整性验证 | `host` |

直接数据 resources

| URI 模式 | 说明 | |-------------|-------------| | `metrics://{host}` | 以 JSON 格式输出系统指标 (CPU、内存、磁盘、网络、负载) | | `file://{host}/{path}` | 远程文件内容 | | `log://{host}/{path}` | 日志文件的最后几行 | | `health://{host}` | 主机的健康检查摘要 (连通性、负载、关键服务) | | `history://{host}` | 桥接器为该主机捕获的最近命令历史 | | `services://{host}` | 该主机上活动 systemd 服务的快照 |

## CLI 用法 二进制文件可独立运行（在 MCP 模式之外），为 AI Agent 工作流**节省 10-32 倍的 token**。 ### 基本命令 ``` bridge-mcp status # Show configured hosts & security bridge-mcp exec "" # Execute a command directly bridge-mcp history [--limit 20] # Show command history bridge-mcp upload # SFTP upload bridge-mcp download # SFTP download bridge-mcp validate # Validate config file bridge-mcp config-diff # Compare config vs defaults ``` ### 工具调用（全部 357 个 MCP 工具） ``` # 使用 key=value 对调用任何 tool bridge-mcp tool ssh_docker_ps host=prod bridge-mcp tool ssh_exec host=prod command="df -h" # 或者使用 JSON 参数 bridge-mcp tool ssh_k8s_get --json-args '{"host":"k8s","resource":"pods","namespace":"default"}' # JSON 输出（用于 scripting/parsing） bridge-mcp --json tool ssh_docker_ps host=prod ``` ### 渐进式发现 通过 CLI： ``` bridge-mcp list-tools --groups-only # 75 groups (~2K tokens) bridge-mcp list-tools --group docker # Tools in a group (~500 tokens) bridge-mcp list-tools --search kubernetes # Keyword search bridge-mcp describe-tool ssh_docker_ps # Full schema for 1 tool (~200 tokens) ``` 从 MCP 客户端（Claude Desktop / Claude Code）中，同样的渐进式发现模式作为三个顶层工具提供，使得模型无需预先加载所有 357 个 schema 即可遍历注册表： | 工具 | 用途 | 典型开销 | |---|---|---| | `mcp_list_tool_groups` | 列出 75 个组及其计数 | ~2 K tokens | | `mcp_search_tools` | 关键字搜索 (`query`, `group?`, `limit=20`) | ~3 K tokens / 页 | | `mcp_describe_tool` | 单个工具的完整 schema + 缩减策略 | ~500 tokens | ### Token 高效输出 每个工具都会根据其输出类型自动公开缩减参数。服务器端过滤在截断**之前**运行，因此您绝不会因输出上限而丢失数据。使用 `describe-tool ` —— 其输出顶部的 **Reduction Strategy** 行会准确告诉您哪些参数适用。 | 输出类型 | 可用参数 | 策略 | 示例工具 | |---|---|---|---| | **表格** | `columns`, `limit` | 选择列 + 限制行数 | `docker_ps`, `service_list`, `process_list` | | **Json** | `jq_filter`, `output_format`, `limit` | jq + TSV 节省 60-80% | `docker_inspect`, `k8s_get`, `ansible_facts` | | **Yaml** | `yq_filter`, `output_format`, `limit` | yq + TSV | kubectl/helm YAML 输出 | | **自动** | 以上所有 | 工具自动检测 JSON 或表格 | `vault_status`，混合输出 | | **原始文本** | — | `save_output=/path` 然后在本地读取文件 | `ssh_exec`，日志，任意命令 | **通用参数**适用于每个工具：`host`、`timeout_seconds`、`max_output`、`save_output`。 ``` # 使用 jq 过滤 JSON + TSV 输出（在列表数据上节省 60-80% 的 token） bridge-mcp tool ssh_k8s_get host=k8s resource=pods \ jq_filter='.items[] | [.metadata.name, .status.phase]' output_format=tsv # 从表格输出中选择列 bridge-mcp tool ssh_docker_ps host=prod columns='["NAMES","STATUS","IMAGE"]' limit=20 # 或者使用符合人体工学的全局 flags（等效） bridge-mcp --jq '.items[] | {name, phase}' --output-format=tsv tool ssh_k8s_get host=k8s resource=pods bridge-mcp --columns NAMES,STATUS,IMAGE --limit 20 tool ssh_docker_ps host=prod # 将完整未截断的输出持久化到文件 bridge-mcp tool ssh_docker_logs host=prod container=nginx save_output=/tmp/nginx.log ``` **分页。** 被截断的结果会输出 `[output_id: abc123]`。使用以下命令获取剩余内容： ``` bridge-mcp tool ssh_output_fetch output_id=abc123 offset=40000 ``` ### 全局标志 | 标志 | 说明 | |------|-------------| | `--config` / `-c` | 配置文件路径 | | `--json` | 所有命令均输出 JSON | | `--dry-run` | 预览而不执行 | ### 退出代码 | 代码 | 含义 | |------|---------| | 0 | 成功 | | 1 | 工具/命令执行错误 | | 2 | CLI 使用错误（未知工具，参数错误） | | 3 | SSH 连接错误 | | 4 | 安全拒绝 | | 5 | 配置错误 | ### Shell 自动补全 ``` bridge-mcp completions bash > ~/.bash_completion.d/bridge-mcp bridge-mcp completions zsh > ~/.zfunc/_bridge-mcp bridge-mcp completions fish > ~/.config/fish/completions/bridge-mcp.fish ``` ### Claude Code 集成（可选） 如果您使用 [Claude Code](https://claude.com/claude-code)，请复制提供的规则和技能以获得支持 CLI 的辅助： ``` # 复制 CLI rule（告知 Claude 为了 token 效率优先使用 CLI 而非 MCP） mkdir -p .claude/rules cp config/claude-code/rules/cli-bridge.md .claude/rules/ # 复制 /bridge skill（交互式 CLI 工作流和 config 帮助） mkdir -p .claude/skills/bridge cp config/claude-code/skills/bridge/SKILL.md .claude/skills/bridge/ ``` 此功能启用后： - Claude 将自动通过 Bash 使用 CLI，而不是 MCP 工具 - `/bridge` 命令用于交互式工具发现和配置管理 - `/bridge config` 用于引导式配置设置 - `/bridge docker` 用于探索组中的工具 ## Daemon 模式 除了默认的 stdio 传输外，Bridge 还可以作为长期运行的 Daemon 在 Unix socket 上监听。多个本地客户端（Claude Code、Claude Desktop、脚本）可以并发连接到同一个 Daemon，每个客户端获得一个独立的 MCP 会话，共享相同的审计日志、输出缓存和连接池。 ``` # 启动 daemon（前台） bridge-mcp --daemon /tmp/bridge-mcp.sock # 通过标准的 MCP `--transport unix` flag 将客户端连接到 socket， # 或者使用任何通过 Unix socket 进行 JSON-RPC 通信的 tool。 ``` **内置连接池**会在您使用相应的 feature flag 进行编译时自动启动： | 连接池 | 默认 TTL | 效果 | |---|---|---| | `WinRmPool` (`--features winrm`) | 120 s | 复用每个主机的 `reqwest::Client`，使连续的 WinRM 调用跳过 TLS 握手。 | | `K8sExecPool` (`--features k8s-exec`) | 300 s | `ssh_k8s_*` 调用之间缓存 `kube::Client`（包括 kubeconfig 遍历 + auth-plugin 刷新）。 | 这两个连接池都会自动清理空闲条目；除了编译相关 feature 外，无需任何其他操作即可启用它们。 ## 故障排除

常见问题

**"Unknown host: xxx"** —— 该主机别名不在您的配置中。运行 `ssh_status` 或 `bridge-mcp status` 以查看已配置的主机。 **"Command denied"** —— 该命令不匹配白名单模式（strict/standard 模式）或匹配了黑名单模式。请检查您的 `security` 配置。 **"SSH connection failed"** —— 验证：(1) 主机可达 (`ping hostname`)，(2) SSH 手动连接正常 (`ssh user@host`)，(3) 密钥权限正确 (`chmod 600 ~/.ssh/id_*`)。 **"Unknown host key"** —— 添加它：`ssh-keyscan hostname >> ~/.ssh/known_hosts` **主机密钥验证模式：** | 模式 | 行为 | |------|----------| | `Strict`（默认） | 拒绝未知和已更改的主机密钥 | | `AcceptNew` | 接受新密钥，拒绝已更改的密钥 | | `Off` | 接受所有密钥（仅用于测试） | 按主机设置：`host_key_verification: AcceptNew`

## 开发 ``` make build # Debug build make release # Optimized release with LTO make test # Run tests (uses nextest if available) make lint # Clippy with strict warnings make ci # Quick CI (fmt-check, lint, test, audit, typos) make ci-full # Full CI (ci + hack + geiger) make dxt # Build DXT package for Claude Desktop ``` Rust edition 2024，MSRV 1.94+。`#![forbid(unsafe_code)]`。7500+ 测试。 **添加新工具 —— 3 个步骤：** 使用 `#[mcp_tool]`（或 `#[mcp_standard_tool]`）注释结构体，添加 `mod` + `pub use` 行，以及（仅在引入新组时）更新 `ToolGroupsConfig`。`inventory` crate 会在编译时自动注册处理程序 —— 无需更新测试数量断言。 版本历史请参见 [CHANGELOG.md](CHANGELOG.md)，安全设计请参见 [THREAT_MODEL.md](docs/THREAT_MODEL.md)。 ## 许可证 [MIT](LICENSE)

标签：Docker, MCP服务器, Rust, SSH, 内存分配, 可视化界面, 子域名突变, 安全防御评估, 网络流量审计, 请求拦截, 运维管理, 远程管理, 通知系统