Remote Demo MCP

Local MCP server that deploys a pre-built static directory to a remote host with rsync.

What It Does

• Uses fixed deployUser from MCP config
• Derives project from localDir basename
• Uploads localDir contents to:
  • /var/www/html/demo-remote/{user}/{project}/
• Uses local rsync command
• Supports OTP/interactive SSH flows by attaching rsync session to /dev/tty
• On failure, asks whether to retry until user cancels

Install

npm install
npm run build

Config

Default config path:

• ~/.config/remote-demo-mcp/config.json

Override path with:

• REMOTE_DEMO_MCP_CONFIG=/abs/path/config.json

Example:

{
  "deployUser": "demo_user-01",
  "publicBaseUrl": "https://example.com",
  "sessionLog": {
    "enabled": false,
    "path": "/tmp/remote-demo-mcp-session.log",
    "logInputValue": false
  },
  "ssh": {
    "host": "xxx.xxx.xxx.xxx",
    "port": 2222,
    "username": "alice123#ec2-user#52.76.147.44",
    "interactiveAuth": true,
    "password": "",
    "hostKeyPolicy": "accept-new",
    "autoFillPassword": true
  },
  "rsyncOptions": ["-az", "--delete"]
}

The server automatically enables resumable uploads by appending:

• --partial
• --checksum
• --progress (unless rsyncOptions already includes --progress or --info=...)

Compatibility note:

• Interactive session mode uses node-pty. If you see posix_spawnp failed on macOS/Linux, it is often caused by non-executable node-pty helper (.../node-pty/prebuilds/*/spawn-helper). This server now checks and auto-fixes helper execute permission at session start.

Remote target base path is hard-coded and cannot be overridden:

• /var/www/html/demo-remote

Tool

deploy_static

Keywords:

• EN: deploy to remote, deploy demo, publish demo, upload static site
• 中文: 部署到远程, 部署demo, 部署 demo, 发布demo, 上传静态网页

user rules:

• deployUser is app user id for remote path, not SSH username
• Allowed chars: A-Z a-z 0-9 _ -
• Not allowed: ., .., spaces, /, \\, and other special characters

Input:

{
  "localDir": "/abs/path/to/dist",
  "clientCwd": "/abs/path/on-mcp-client",
  "dryRun": false
}

localDir path resolution:

• Absolute path: used directly
• Relative path: resolved against clientCwd if provided
• Fallback for relative path: CODEX_START_DIR if set, otherwise process.cwd() (server start directory)

Project name resolution:

• If clientCwd is provided, project name uses the last path segment of clientCwd
• Otherwise, project name uses the last path segment of resolved localDir

Behavior note:

• If ssh.interactiveAuth=true and dryRun=false, deploy_static will fail fast by design.
• For OTP/password interactive deploy, use:
  1. start_deploy_session
  2. poll_deploy_session
  3. submit_deploy_input when nextAction=submit_input
• Host-key confirm (yes/no) and password prompts are auto-handled in session mode.
• OTP is still manual: call submit_deploy_input when nextAction=submit_input.

Output (structuredContent):

{
  "ok": true,
  "attempts": 1,
  "user": "alice",
  "project": "my-site",
  "remotePath": "/var/www/html/demo-remote/alice/my-site/",
  "publicUrl": "https://example.com/alice/my-site/index.html",
  "message": "Deploy succeeded after 1 attempt(s)."
}

verify_deploy

Input:

{
  "url": "https://example.com/alice/my-site/index.html",
  "timeoutMs": 8000
}

Interactive OTP Session Tools

Use these when OTP/password must be entered during deploy in non-TTY hosts:

1. start_deploy_session
2. poll_deploy_session (read output and progress; if state=waiting_input, submit code)
3. submit_deploy_input (send OTP/password)
4. repeat step 2 until state is succeeded or failed
5. optional cancel_deploy_session

poll_deploy_session supports incremental output by cursor and returns nextCursor.

Session tools return nextAction to make orchestration deterministic:

• submit_input: call submit_deploy_input
• poll: call poll_deploy_session
• done: workflow finished (succeeded / failed / cancelled)

Session logging:

• Configure in MCP config file under sessionLog.
• sessionLog.enabled default is false.
• sessionLog.path default is /tmp/remote-demo-mcp-session.log.
• sessionLog.logInputValue default is false (only input length is logged).
• Interactive session tools run rsync in a PTY, so password/OTP prompts can be detected via poll_deploy_session.

SSH host key policy:

• accept-new (default): first-time host key is auto-accepted; changed key is rejected.
• strict: never auto-accept unknown host key.
• insecure: disable host key validation (high risk; for temporary/debug use only).

Codex CLI interactive flow:

1. Call start_deploy_session
2. Loop poll_deploy_session
3. If needsInput=true or nextAction=submit_input, call submit_deploy_input with OTP/password. The tip display to user is "Please Enter MFA Code." or "Please Enter Password."
4. Continue polling until nextAction=done

Agent protocol contract (for MCP clients like Codex):

1. Call start_deploy_session once.
2. Read nextAction from response.
3. If nextAction=submit_input, call submit_deploy_input.
4. If nextAction=poll, call poll_deploy_session.
5. Repeat steps 2-4 until nextAction=done.
6. Never call deploy_static for OTP flows; use session tools only.
7. While polling, relay transfer progress from output to the end user continuously.

Output (structuredContent):

{
  "ok": true,
  "url": "https://example.com/alice/my-site/index.html",
  "status": 200,
  "statusText": "OK",
  "responseTimeMs": 123,
  "message": "URL is reachable: HTTP 200 in 123ms"
}

Run

npm run dev
# or
npm run build && npm start

Initialize config file:

remote-demo-mcp init

It creates:

• ~/.config/remote-demo-mcp/config.json
• Interactive mode shows each current field value for editing.
• Press Enter without input to keep the current value unchanged.
• If config already exists, init asks whether to modify, then asks final confirmation before overwrite.

codex 使用

安裝 npm 包

npm install -g    @jake.e-com365/remote-demo-mcp

codex 添加 mcp

codex mcp add remote-demo-mcp remote-demo-mcp  

remote-demo-mcp 的配置

remote-demo-mcp init
vi ~/.config/remote-demo-mcp/config.json

{
  "deployUser": "jake",
  "publicBaseUrl": "https://demo-remote.e-com365.com/",
  "ssh": {
    "host": "xxx.xxx.xxx.xxx",
    "username": "alice123#ec2-user#18.140.183.126",
    "interactiveAuth": true,
    "port": 2222,
    "password": "xxx",
    "hostKeyPolicy": "accept-new",
    "autoFillPassword": true
  },
  "rsyncOptions": ["-az", "--delete"]
}