### Install and Start mcp-ssh-tool

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Demonstrates how to install and start the mcp-ssh-tool server in different transport modes. Use 'npx' for running without installation.

```bash
npx -y mcp-ssh-tool --version
```

```bash
npm install -g mcp-ssh-tool
```

```bash
mcp-ssh-tool
```

```bash
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000
```

```bash
printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 0.0.0.0 --port 3000 \
  --bearer-token-file .mcp-token
```

```bash
mcp-ssh-tool --transport=http --enable-legacy-sse
```

--------------------------------

### Setup Development Environment

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/development.md

Run these commands to set up the development environment, including enabling Corepack, installing npm, and preparing the project.

```bash
corepack enable
node scripts/use-ci-npm.mjs
npm ci
npm run prepare
```

--------------------------------

### Build Project from Source

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/registry/mcp-ssh-tool/README.md

Run these commands to install dependencies and build the project if you are installing from source.

```bash
npm install
npm run build
```

--------------------------------

### Start Streamable HTTP with Bearer Token

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

Example of starting the MCP SSH Tool with HTTP transport, specifying a bearer token file for authentication.

```bash
printf '%s' 'replace-me' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token
```

--------------------------------

### Install mcp-ssh-tool from Source

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Instructions for installing the mcp-ssh-tool directly from its source code repository.

```bash
git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm link
```

--------------------------------

### Install dependencies

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Install all project dependencies using npm ci for a clean and reproducible environment.

```bash
npm ci
```

--------------------------------

### Install mcp-ssh-tool Globally

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Install the tool globally using npm to use it as a command-line tool. This is the recommended installation method for general use.

```bash
npm install -g mcp-ssh-tool
```

--------------------------------

### Install Dependencies and Run Checks

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/README.md

This command sequence is used for setting up the development environment. It first installs all necessary npm packages and then runs a code check.

```bash
npm ci
npm run check
```

--------------------------------

### Clone, Install, Build, and Link MCP SSH Tool

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Follow these commands to clone the repository, install project dependencies, build the project, and link it globally for command-line use.

```bash
git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link
```

--------------------------------

### Verify mcp-ssh-tool Installation

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

After global installation, verify that the tool is installed correctly by checking its version.

```bash
mcp-ssh-tool --version
```

--------------------------------

### Verify CLI Version

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/release.md

Confirm the installed CLI version matches the expected release version.

```bash
npx -y mcp-ssh-tool@2.1.0 --version
```

--------------------------------

### Manage Package Installation with ensure_package

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Ensure a package is installed or absent using the auto-detected package manager. This operation is idempotent. Optionally provide a sudo password if required.

```json
// Install nginx
{
  "name": "ensure_package",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "nginx",
    "state": "present",
    "sudoPassword": "optionalsudopw"
  }
}

// Remove a package
{
  "name": "ensure_package",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "telnet",
    "state": "absent"
  }
}

// Response
{
  "ok": true,
  "pm": "apt",
  "code": 0,
  "stdout": "Setting up nginx (1.24.0-1) ...",
  "stderr": ""
}
```

--------------------------------

### Example Policy JSON File for mcp-ssh-tool

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

An example JSON policy file that can be used to configure fine-grained rules for mcp-ssh-tool operations.

```json
{
  "mode": "enforce",
  "allowRootLogin": false,
  "allowRawSudo": false,
  "allowDestructiveCommands": false,
  "allowDestructiveFs": false,
  "allowedHosts": ["^prod-[0-9]+\.example\.com$"],
  "commandAllow": ["^(uname|df|uptime|free|systemctl status)\b"],
  "commandDeny": ["rm\s+-rf\s+/", "shutdown", "reboot"],
  "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
  "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}
```

--------------------------------

### Client Configuration for mcp-ssh-tool

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Provides configuration examples for connecting mcp-ssh-tool with various clients like Claude Desktop, VS Code, Cursor, and MCP Inspector.

```json
// Claude Desktop / ChatGPT (mcpServers block in settings JSON)
{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}
```

```json
// VS Code / Cursor (.vscode/mcp.json or workspace settings)
{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}
```

```text
// MCP Inspector over Streamable HTTP
// 1. Start the server: mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000
// 2. Connect Inspector to: http://127.0.0.1:3000/mcp
```

--------------------------------

### MCP Configuration File (mcp.json)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Configure the mcp-ssh-tool in a dedicated 'mcp.json' file. This example uses 'stdio' transport.

```json
{
  "mcpServers": {
    "ssh-tool": {
      "command": "mcp-ssh-tool",
      "args": [],
      "transport": {
        "type": "stdio"
      }
    }
  }
}
```

--------------------------------

### MCP Client Configuration (mcpServers schema)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Example configuration for an MCP client using the 'mcpServers' schema to register mcp-ssh-tool via 'npx'.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}
```

--------------------------------

### Start mcp-ssh-tool with HTTP Transport

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/README.md

Start the mcp-ssh-tool server using the HTTP transport. This is suitable for remote MCP clients or reverse proxies. Ensure to specify the host and port.

```bash
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000
```

--------------------------------

### Register mcp-ssh-tool with Codex (npx)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

If a global install is not desired, use 'npx' to register mcp-ssh-tool with Codex. This executes the tool without a global installation.

```bash
codex mcp add ssh-mcp -- npx -y mcp-ssh-tool
```

--------------------------------

### Conventional Commits example

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for clear and consistent commit history.

```git
feat(session): add auto-reconnect capability
fix(auth): handle SSH agent timeout
docs(readme): update installation instructions
```

--------------------------------

### Example .env File for MCP SSH Tool Configuration

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/configuration.md

Sets environment variables to configure the MCP SSH Tool. This is useful for simple deployments and overrides default settings.

```dotenv
LOG_LEVEL=info
LOG_FORMAT=json
SSH_MCP_HOST_KEY_POLICY=strict
SSH_MCP_KNOWN_HOSTS_PATH=/etc/ssh/ssh_known_hosts
SSH_MCP_POLICY_FILE=/etc/mcp-ssh-tool/policy.json
SSH_MCP_MAX_SESSIONS=50
SSH_MCP_SESSION_TTL=1800000
SSH_MCP_COMMAND_TIMEOUT=45000
SSH_MCP_MAX_FILE_SIZE=10485760
SSH_MCP_HTTP_HOST=127.0.0.1
SSH_MCP_HTTP_PORT=3000
```

--------------------------------

### ensure_service

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Manages a system service lifecycle using the detected init system. Idempotent for `started`, `stopped`, `enabled`, and `disabled` states.

```APIDOC
## Tool: `ensure_service`

### Description
Manages a system service lifecycle using the detected init system (systemd, service, launchd, or Windows Service). Idempotent for `started`, `stopped`, `enabled`, and `disabled` states.

### Arguments
- **sessionId** (string) - Required - The session identifier.
- **name** (string) - Required - The name of the service.
- **state** (string) - Required - The desired state of the service (e.g., `started`, `stopped`, `restarted`, `enabled`, `disabled`).
- **sudoPassword** (string) - Optional - The password for sudo operations.

### Request Example (Restart)
```json
{
  "name": "ensure_service",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "nginx",
    "state": "restarted",
    "sudoPassword": "optionalsudopw"
  }
}
```

### Request Example (Enable)
```json
{
  "name": "ensure_service",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "postgresql",
    "state": "enabled"
  }
}
```

### Response Example
```json
{
  "ok": true
}
```
```

--------------------------------

### Connect to MCP Inspector over HTTP

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/README.md

This example demonstrates how to connect to MCP Inspector running over HTTP. It involves saving a bearer token to a file and then executing the mcp-ssh-tool with specific transport and authentication flags.

```bash
printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token
```

--------------------------------

### Check mcp-ssh-tool Version

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/README.md

Run this command using npx to check the version of mcp-ssh-tool without installing it globally.

```bash
npx -y mcp-ssh-tool --version
```

--------------------------------

### Manage Service Lifecycle with ensure_service

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Control the lifecycle of a system service using the detected init system. States like 'started', 'stopped', 'enabled', and 'disabled' are idempotent. Optionally provide a sudo password.

```json
// Restart a service and verify it is running
{
  "name": "ensure_service",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "nginx",
    "state": "restarted",
    "sudoPassword": "optionalsudopw"
  }
}

// Enable a service to start on boot
{
  "name": "ensure_service",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "postgresql",
    "state": "enabled"
  }
}

// Response
{
  "ok": true
}
```

--------------------------------

### Register mcp-ssh-tool with Strict Host Key Checking

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Register mcp-ssh-tool with Codex using an optional hardened setup that enforces strict host key checking.

```bash
codex mcp add ssh-mcp --env STRICT_HOST_KEY_CHECKING=true -- mcp-ssh-tool
```

--------------------------------

### Example MCP SSH Tool Policy Configuration

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/configuration.md

Defines security and access policies for SSH sessions. Use this JSON structure to configure allowed hosts, commands, and file operations.

```json
{
  "mode": "enforce",
  "allowRootLogin": false,
  "allowRawSudo": false,
  "allowDestructiveCommands": false,
  "allowDestructiveFs": false,
  "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
  "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
  "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
  "pathAllowPrefixes": ["/tmp", "/home/deploy"],
  "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}
```

--------------------------------

### Configure Host Key Policy (Temporary Lab)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/MIGRATION.md

Use 'accept-new' policy for host keys in temporary lab environments.

```json
{
  "hostKeyPolicy": "accept-new"
}
```

--------------------------------

### Run Integration and E2E Tests

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

Opt-in commands to run integration and end-to-end tests, requiring specific environment variables.

```bash
RUN_SSH_INTEGRATION=1 npm run test:integration
RUN_SSH_E2E=1 npm run test:e2e
```

--------------------------------

### Check if mcp-ssh-tool is Installed Globally

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Verify if the mcp-ssh-tool is installed globally by checking its location in the system's PATH.

```bash
which mcp-ssh-tool
```

--------------------------------

### Create a changeset

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Generate a changeset file to record user-visible changes for release management.

```bash
npm run changeset
```

--------------------------------

### Clone the repository

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/mcp-ssh-tool.git
cd mcp-ssh-tool
```

--------------------------------

### Get Specific MCP Server Registration

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Retrieve details about a specific registered MCP server, such as 'ssh-mcp'.

```bash
codex mcp get ssh-mcp
```

--------------------------------

### Run Optional Local Security Tools

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/development.md

Run optional best-effort local security tools. Missing tools should be noted as caveats.

```bash
task security:local
```

--------------------------------

### Run Local Gates

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/release.md

Execute local CI and security checks before proceeding with the release.

```bash
task ci
task security:local
```

--------------------------------

### ensure_package

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Ensures a software package is installed (`present`) or removed (`absent`) using the auto-detected package manager. Idempotent.

```APIDOC
## Tool: `ensure_package`

### Description
Ensures a software package is installed (`present`) or removed (`absent`) using the auto-detected package manager (apt, dnf, yum, apk, pacman, brew, etc.). Idempotent.

### Arguments
- **sessionId** (string) - Required - The session identifier.
- **name** (string) - Required - The name of the package.
- **state** (string) - Required - The desired state of the package (`present` or `absent`).
- **sudoPassword** (string) - Optional - The password for sudo operations.

### Request Example (Install)
```json
{
  "name": "ensure_package",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "nginx",
    "state": "present",
    "sudoPassword": "optionalsudopw"
  }
}
```

### Request Example (Remove)
```json
{
  "name": "ensure_package",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "name": "telnet",
    "state": "absent"
  }
}
```

### Response Example
```json
{
  "ok": true,
  "pm": "apt",
  "code": 0,
  "stdout": "Setting up nginx (1.24.0-1) ...",
  "stderr": ""
}
```
```

--------------------------------

### Run tests

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Execute the project's test suite to ensure code quality and functionality.

```bash
npm test
```

--------------------------------

### View GitHub Release

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/release.md

Inspect the release details on the canonical GitHub repository.

```bash
gh release view v2.1.0 --repo oaslananka-lab/mcp-ssh-tool
```

--------------------------------

### Build the project

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Compile the project's TypeScript code into JavaScript for execution.

```bash
npm run build
```

--------------------------------

### Get Metrics

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Retrieves runtime metrics for the MCP server, such as session counts, command statistics, and uptime. Supports JSON (default) or Prometheus text format.

```APIDOC
## Tool: `get_metrics`

Returns runtime metrics for the MCP server itself: session counts, command execution statistics, uptime, and rate-limiter state. Supports JSON (default) or Prometheus text format.

### Request Example (JSON)
```jsonc
{
  "name": "get_metrics",
  "arguments": { "format": "json" }
}
```

### Request Example (Prometheus)
```jsonc
{
  "name": "get_metrics",
  "arguments": { "format": "prometheus" }
}
```

### Response Example (JSON)
```json
{
  "uptimeMs": 3600000,
  "sessionsCreated": 12,
  "sessionsActive": 2,
  "sessionsClosed": 10,
  "commandsExecuted": 87,
  "commandsFailed": 3,
  "commandAvgDurationMs": 245
}
```

### Response Example (Prometheus)
```text
# HELP ssh_mcp_sessions_active Currently active SSH sessions
# TYPE ssh_mcp_sessions_active gauge
ssh_mcp_sessions_active 2
# HELP ssh_mcp_commands_executed_total Total number of commands executed
# TYPE ssh_mcp_commands_executed_total counter
ssh_mcp_commands_executed_total 87
```
```

--------------------------------

### Get MCP Server Metrics (JSON/Prometheus)

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Retrieve runtime metrics for the MCP server. Supports JSON format by default or Prometheus text format for scraping.

```jsonc
// JSON format (default)
{
  "name": "get_metrics",
  "arguments": { "format": "json" }
}
```

```jsonc
// Prometheus format for scraping
{
  "name": "get_metrics",
  "arguments": { "format": "prometheus" }
}
```

```jsonc
// JSON response example
{
  "uptimeMs": 3600000,
  "sessionsCreated": 12,
  "sessionsActive": 2,
  "sessionsClosed": 10,
  "commandsExecuted": 87,
  "commandsFailed": 3,
  "commandAvgDurationMs": 245
}
```

```comment
// Prometheus response excerpt
// # HELP ssh_mcp_sessions_active Currently active SSH sessions
// # TYPE ssh_mcp_sessions_active gauge
// ssh_mcp_sessions_active 2
// ssh_mcp_commands_executed_total 87
```

--------------------------------

### Configure MCP Server for Local Clients

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

Use this stdio configuration for local MCP clients when the server does not appear.

```json
{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool"
    }
  }
}
```

--------------------------------

### Verify Doppler Secrets Locally (Bash)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/doppler.md

Use this script to verify Doppler secrets locally without accessing production Doppler secrets. Ensure you have bash installed.

```bash
bash scripts/verify-doppler-secrets.sh
```

--------------------------------

### Create and Push Release Hardening Branch

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/operations.md

Use these commands to create a new hardening branch from the canonical source and push it to GitHub. Ensure you are on the correct branch before executing.

```bash
git switch -c chore/v2.1.0-hardening
git push -u github chore/v2.1.0-hardening
```

--------------------------------

### Get File or Directory Status

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Use `fs_stat` to retrieve metadata for a remote path, including size, modification time, permissions, and type (file, directory, symlink, etc.).

```jsonc
// MCP tool call
{
  "name": "fs_stat",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "path": "/var/www/html"
  }
}

// Response
{
  "path": "/var/www/html",
  "size": 4096,
  "mtime": "2024-01-10T08:32:00.000Z",
  "mode": 16877,
  "type": "directory"
}
```

--------------------------------

### Run E2E Tests with Docker Fixture

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

Command to execute end-to-end tests using a Dockerized fixture.

```bash
npm run e2e:docker
```

--------------------------------

### MCP Prompts for SSH Workflows

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

These JSONC snippets define prompt templates for guiding AI clients through secure SSH operations. They are used to request specific actions or information from the AI.

```jsonc
// safe-connect – opens a session using strict host-key verification
{
  "method": "prompts/get",
  "params": {
    "name": "safe-connect",
    "arguments": {
      "host": "prod-1.example.com",
      "username": "deploy"
    }
  }
}
// Returns a user message instructing the model to use strict hostKeyPolicy,
// verify known_hosts, and avoid root login.

// inspect-host-capabilities – lists sessions, reads effective policy, runs os_detect
{
  "method": "prompts/get",
  "params": { "name": "inspect-host-capabilities" }
}

// plan-mutation – use explain mode before any destructive change
{
  "method": "prompts/get",
  "params": {
    "name": "plan-mutation",
    "arguments": { "goal": "Upgrade PostgreSQL from 14 to 16" }
  }
}

// managed-config-change – read → diff → dry-run → apply pattern
{
  "method": "prompts/get",
  "params": {
    "name": "managed-config-change",
    "arguments": { "path": "/etc/nginx/nginx.conf" }
  }
}
```

--------------------------------

### Create and push a Git tag

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Manually create and push a Git tag for a specific release version.

```bash
git tag v2.0.0 && git push origin v2.0.0
```

--------------------------------

### Access MCP Resources

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Read static and dynamic data exposed as MCP resources. Examples include accessing active session lists, runtime metrics, SSH configurations, and policy settings.

```text
mcp-ssh-tool://sessions/active          – Active SSH session list (JSON)
mcp-ssh-tool://metrics/json             – Runtime metrics snapshot (JSON)
mcp-ssh-tool://metrics/prometheus       – Prometheus metrics export (text/plain)
mcp-ssh-tool://ssh-config/hosts         – Parsed ~/.ssh/config host aliases (JSON)
mcp-ssh-tool://policy/effective         – Current resolved policy configuration (JSON)
mcp-ssh-tool://audit/recent             – Last 100 redacted audit events (JSON)
mcp-ssh-tool://capabilities/support-matrix – Per-platform capability matrix (JSON)
```

```jsonc
// Reading the effective policy via MCP resources/read
{
  "method": "resources/read",
  "params": { "uri": "mcp-ssh-tool://policy/effective" }
}
```

```jsonc
// Response excerpt
{
  "contents": [{
    "uri": "mcp-ssh-tool://policy/effective",
    "mimeType": "application/json",
    "text": "{
  \"mode\": \"enforce\",
  \"allowRootLogin\": false,
  \"allowRawSudo\": false,
  \"pathAllowPrefixes\": [\"/tmp\", \"/home\"],
  ...\n}"
  }]
}
```

--------------------------------

### Enable Corepack Shims on Windows

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

If `corepack enable` fails with EPERM on Windows, use these commands to manually enable shims.

```powershell
node scripts/use-ci-npm.mjs
npm ci
```

--------------------------------

### Minimal MCP Client Configuration

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/REGISTRY_SUBMISSION.md

Use this JSON configuration to set up a minimal MCP client connection via stdio transport. Ensure the 'mcp-ssh-tool' command is accessible in your PATH.

```json
{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}
```

--------------------------------

### Verify Doppler Secrets Locally (PowerShell)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/doppler.md

Use this script to verify Doppler secrets locally without accessing production Doppler secrets. Ensure you have PowerShell installed and execution policy is set appropriately.

```powershell
powershell -ExecutionPolicy Bypass -File scripts/verify-doppler-secrets.ps1
```

--------------------------------

### View GitHub Release on Mirror Repo

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/release.md

Inspect the release details on the mirrored GitHub repository.

```bash
gh release view v2.1.0 --repo oaslananka/mcp-ssh-tool
```

--------------------------------

### MCP SSH Tool Policy Configuration

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/README.md

Example JSON policy file for mcp-ssh-tool. This defines security and operational rules such as allowed hosts, commands, and file path prefixes. Set the SSH_MCP_POLICY_FILE environment variable to this file's path.

```json
{
  "mode": "enforce",
  "allowRootLogin": false,
  "allowRawSudo": false,
  "allowDestructiveCommands": false,
  "allowDestructiveFs": false,
  "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
  "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
  "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
  "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
  "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}
```

--------------------------------

### Verify Package Repository URL

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

Ensure the `package.json.repository.url` matches this exact format for trusted publishing.

```text
git+https://github.com/oaslananka-lab/mcp-ssh-tool.git
```

--------------------------------

### ConfigManager for Application Settings

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

This TypeScript code illustrates the use of ConfigManager to load and manage application settings from various sources, including defaults, environment variables, and JSON policy files. It provides methods to get specific configurations, retrieve all settings, and update them at runtime.

```typescript
import { ConfigManager } from "./src/config.js";

// Load from environment + defaults
const config = new ConfigManager();

// Access specific keys
const policy = config.get("policy");
console.log(policy.allowRawSudo);     // false
console.log(policy.pathAllowPrefixes); // ["/tmp", "/var/tmp", "/home", "/Users"]

// Get a frozen snapshot of all settings
const all = config.getAll();
console.log(all.maxSessions);          // 20
console.log(all.security.hostKeyPolicy); // "strict"

// Runtime override (e.g., in tests)
config.update({
  policy: {
    ...config.get("policy"),
    allowRawSudo: true,
    commandAllow: ["^systemctl\b"],
  },
});
```

--------------------------------

### Configure Host Key Policy (Production)

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/MIGRATION.md

Set the host key policy to 'strict' and specify the path to known hosts for production environments.

```dotenv
STRICT_HOST_KEY_CHECKING=false
```

```dotenv
SSH_MCP_HOST_KEY_POLICY=strict
SSH_MCP_KNOWN_HOSTS_PATH=/etc/ssh/ssh_known_hosts
```

--------------------------------

### Run local quality gates

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/CONTRIBUTING.md

Execute the comprehensive local quality check script, equivalent to the primary CI verification path.

```bash
npm run check
```

--------------------------------

### List Registered MCP Servers

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/INSTALL.md

Verify the registration of MCP servers by listing all registered servers.

```bash
codex mcp list
```

--------------------------------

### Detect Operating System with os_detect

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Detect the remote operating system, distribution, version, architecture, default shell, package manager, and init system in a single call. Detection is cached per session.

```json
// MCP tool call
{
  "name": "os_detect",
  "arguments": {
    "sessionId": "a1b2c3d4-..."
  }
}

// Response
{
  "platform": "linux",
  "distro": "Ubuntu",
  "version": "22.04",
  "arch": "x86_64",
  "shell": "/bin/bash",
  "packageManager": "apt",
  "init": "systemd",
  "defaultShell": "bash",
  "tempDir": "/tmp"
}
```

--------------------------------

### Allow Raw Sudo with Policy

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/MIGRATION.md

Explicitly allow raw sudo operations by setting 'allowRawSudo' to true in the policy configuration. Prefer using specific commands like ensure_package, ensure_service, ensure_lines_in_file, or patch_apply instead.

```json
{
  "allowRawSudo": true
}
```

--------------------------------

### Manage Git Hooks

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/development.md

Run this task to manage Git hooks, ensuring both npm hook behavior and pre-commit behavior are active.

```bash
task hooks
```

--------------------------------

### List Configured SSH Hosts

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Reads the `~/.ssh/config` file and lists all configured host aliases with their resolved parameters. This is useful for discovering available SSH targets.

```jsonc
// MCP tool call
{
  "name": "ssh_list_configured_hosts",
  "arguments": {}
}
```

```json
// Response
{
  "count": 3,
  "hosts": [
    { "alias": "prod-1", "host": "prod-1.example.com", "user": "deploy", "port": 22 },
    { "alias": "staging", "host": "staging.example.com", "user": "ubuntu", "port": 2222 }
  ]
}
```

--------------------------------

### Create Directory Recursively

Source: https://context7.com/oaslananka/mcp-ssh-tool/llms.txt

Use `fs_mkdirp` to create a directory path recursively, similar to `mkdir -p`. This operation is idempotent and will succeed even if the directory already exists.

```jsonc
// MCP tool call
{
  "name": "fs_mkdirp",
  "arguments": {
    "sessionId": "a1b2c3d4-...",
    "path": "/home/deploy/releases/2024-01-15/config"
  }
}

// Response
{
  "ok": true,
  "path": "/home/deploy/releases/2024-01-15/config"
}
```

--------------------------------

### Check MCP Registry Version

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/troubleshooting.md

Query the MCP registry to verify the latest published version of the server.

```bash
curl https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest
```

--------------------------------

### Run Local Parity Gate

Source: https://github.com/oaslananka/mcp-ssh-tool/blob/main/docs/development.md

Execute the full local parity gate to ensure code quality before pushing. This task includes formatting, linting, type checking, and more.

```bash
task ci
```