Add remote workspace tools

MehediHossain95 · MehediHossain95 · commit 9667b0b6af39 · 2026-04-26T19:49:57.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0
+
+- Added remote workspace bootstrap checks for OS, shell, user, workspace path, and common development tools.
+- Added remote workspace tree, text search, and git status tools.
+- Added exact-text replacement for allowlisted writable files.
+- Added optional `workspaceRoot` to saved SSH connection profiles.
+
 ## 0.3.1
 
 - Fixed stdio lifecycle handling so async SSH tool calls return results reliably when stdin closes.
diff --git a/plugins/remote-ssh/.codex-plugin/plugin.json b/plugins/remote-ssh/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "remote-ssh",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Enterprise-grade Remote SSH tools for Codex with host policies, audit logging, and safe file operations.",
   "author": {
     "name": "Zain Technologies LTD",
@@ -22,7 +22,7 @@
   "interface": {
     "displayName": "Remote SSH",
     "shortDescription": "Enterprise Remote SSH operations for Codex",
-    "longDescription": "Remote SSH by Zain Technologies LTD connects Codex to trusted servers, devboxes, and private infrastructure through a local MCP bridge. It supports conversational connection setup, saved host aliases, path allowlists, write opt-in controls, blocked command policies, timeouts, output limits, and JSONL audit logs for professional remote development and operations workflows.",
+    "longDescription": "Remote SSH by Zain Technologies LTD connects Codex to trusted servers, devboxes, and private infrastructure through a local MCP bridge. It supports conversational connection setup, saved host aliases, remote workspace bootstrap checks, tree/search/git tools, path allowlists, write opt-in controls, blocked command policies, timeouts, output limits, and JSONL audit logs for professional remote development and operations workflows.",
     "developerName": "Zain Technologies LTD",
     "category": "Development",
     "capabilities": [
diff --git a/plugins/remote-ssh/CHANGELOG.md b/plugins/remote-ssh/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0
+
+- Added remote workspace bootstrap checks for OS, shell, user, workspace path, and common development tools.
+- Added remote workspace tree, text search, and git status tools.
+- Added exact-text replacement for allowlisted writable files.
+- Added optional `workspaceRoot` to saved SSH connection profiles.
+
 ## 0.3.1
 
 - Fixed stdio lifecycle handling so async SSH tool calls return results reliably when stdin closes.
diff --git a/plugins/remote-ssh/CONFIGURATION.md b/plugins/remote-ssh/CONFIGURATION.md
@@ -24,6 +24,7 @@ Advanced users can override this with `REMOTE_SSH_CONFIG_FILE` or provide epheme
 | SSH Host | `sshHost` | `user@hostname` or a host from `~/.ssh/config`. |
 | SSH Port | `port` | Defaults to `22`. |
 | Identity File | `identityFile` | Optional. Leave empty to use default SSH behavior. |
+| Workspace Root | `workspaceRoot` | Optional default remote project root. |
 | Allowed Paths | `allowedPaths` | Optional safety policy for file tools. |
 | Allow Writes | `allowWrites` | Defaults to `false`. |
 
@@ -38,6 +39,7 @@ Set this environment variable to a JSON object keyed by host alias.
     "host": "10.0.10.20",
     "port": 22,
     "identityFile": "~/.ssh/id_ed25519_prod",
+    "workspaceRoot": "/srv/app",
     "allowedPaths": ["/srv/app", "/var/log/app"],
     "allowWrites": false,
     "allowCommandExecution": true,
@@ -78,6 +80,7 @@ Set this environment variable to a JSON file path. The file can contain the host
 | `sshConfigHost` | string | optional | Existing host alias from `~/.ssh/config`. |
 | `port` | number | `22` | SSH port. |
 | `identityFile` | string | optional | Private key path. Supports `~`. |
+| `workspaceRoot` | string | optional | Default remote project root for workspace tools. |
 | `knownHostsFile` | string | optional | Custom known hosts file. |
 | `proxyJump` | string | optional | SSH jump host value passed through `-J`. |
 | `strictHostKeyChecking` | boolean | `true` | Keep host key verification enabled by default. |
diff --git a/plugins/remote-ssh/README.md b/plugins/remote-ssh/README.md
@@ -11,6 +11,10 @@ Modern teams often keep source code, logs, services, and deployment tools on rem
 This plugin exposes clear tools for common remote work:
 
 - add and save SSH connections conversationally
+- inspect whether a remote host is ready for development
+- browse bounded remote workspace trees
+- search text inside remote workspaces
+- check remote Git status
 - discover configured host aliases
 - run non-interactive remote commands
 - list directories
@@ -108,10 +112,15 @@ Use Remote SSH to tail the last 100 lines of /var/log/nginx/error.log on hms.
 | `remote_test_connection` | Validates a saved SSH connection. |
 | `remote_hosts` | Lists configured host aliases and non-secret policy metadata. |
 | `remote_run` | Runs a non-interactive command on a configured host. |
+| `remote_workspace_bootstrap` | Checks remote OS, user, shell, workspace path, and dev tools. |
+| `remote_tree` | Shows a bounded remote workspace tree. |
+| `remote_search_text` | Searches text inside a remote workspace. |
+| `remote_git_status` | Runs Git status in a remote workspace. |
 | `remote_list_dir` | Lists an allowlisted directory. |
 | `remote_stat` | Returns metadata for an allowlisted path. |
 | `remote_read_file` | Reads an allowlisted UTF-8 text file. |
 | `remote_tail_file` | Reads the last lines of an allowlisted text/log file. |
+| `remote_replace_in_file` | Replaces exact text in an allowlisted writable file. |
 | `remote_write_file` | Writes UTF-8 text when `allowWrites=true`. |
 
 ## Security
diff --git a/plugins/remote-ssh/package.json b/plugins/remote-ssh/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@zaintechnologiesltd/codex-remote-ssh",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Enterprise-grade Remote SSH MCP tools for OpenAI Codex.",
   "license": "MIT",
   "author": {
diff --git a/plugins/remote-ssh/scripts/remote-ssh-mcp.js b/plugins/remote-ssh/scripts/remote-ssh-mcp.js
@@ -7,7 +7,7 @@ const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline");
 
-const SERVER_VERSION = "0.3.1";
+const SERVER_VERSION = "0.4.0";
 const PROTOCOL_VERSION = "2024-11-05";
 const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
 const DEFAULT_CONNECT_TIMEOUT_SECONDS = 15;
@@ -121,11 +121,13 @@ function parseSshHost(input) {
 
 function cleanHostProfile(args) {
   const parsed = parseSshHost(args.sshHost);
+  const allowedPaths = Array.isArray(args.allowedPaths) ? args.allowedPaths : [];
   const profile = {
     ...parsed,
     port: args.port || 22,
     identityFile: args.identityFile || undefined,
-    allowedPaths: Array.isArray(args.allowedPaths) ? args.allowedPaths : [],
+    workspaceRoot: args.workspaceRoot || undefined,
+    allowedPaths: allowedPaths.length > 0 ? allowedPaths : args.workspaceRoot ? [args.workspaceRoot] : [],
     allowWrites: Boolean(args.allowWrites),
     strictHostKeyChecking: args.strictHostKeyChecking !== false,
     connectTimeoutSeconds: args.connectTimeoutSeconds || DEFAULT_CONNECT_TIMEOUT_SECONDS,
@@ -193,6 +195,10 @@ function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+function base64Text(value) {
+  return Buffer.from(String(value), "utf8").toString("base64");
+}
+
 function normalizeRemotePath(remotePath) {
   if (!remotePath || typeof remotePath !== "string") {
     throw new Error("Remote path must be a non-empty string.");
@@ -221,6 +227,23 @@ function assertPathAllowed(config, remotePath, operation) {
   return normalized;
 }
 
+function resolveRemoteWorkspacePath(config, root, relativePath, operation) {
+  const workspaceRoot = normalizeRemotePath(root || config.workspaceRoot || "/");
+  assertPathAllowed(config, workspaceRoot, operation);
+
+  const requested = relativePath ? String(relativePath) : ".";
+  if (requested.startsWith("/")) {
+    return assertPathAllowed(config, requested, operation);
+  }
+
+  const resolved = path.posix.normalize(path.posix.join(workspaceRoot, requested));
+  if (resolved !== workspaceRoot && !resolved.startsWith(`${workspaceRoot}/`)) {
+    throw new Error(`${operation} denied because path escapes workspace root: ${requested}`);
+  }
+
+  return assertPathAllowed(config, resolved, operation);
+}
+
 function assertCommandAllowed(config, command) {
   if (!config.allowCommandExecution) {
     throw new Error(`Command execution is disabled for host alias ${config.alias}.`);
@@ -341,6 +364,7 @@ const tools = [
         sshHost: { type: "string", description: "user@hostname or a host alias from ~/.ssh/config." },
         port: { type: "integer", minimum: 1, maximum: 65535, default: 22 },
         identityFile: { type: "string", description: "Optional private key path. Supports ~." },
+        workspaceRoot: { type: "string", description: "Optional default remote project/workspace root." },
         allowedPaths: {
           type: "array",
           items: { type: "string" },
@@ -404,6 +428,82 @@ const tools = [
       additionalProperties: false,
     },
   },
+  {
+    name: "remote_workspace_bootstrap",
+    description: "Inspect remote OS, user, shell, workspace path, and common development tools.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: { type: "string" },
+        root: { type: "string", description: "Optional absolute remote workspace root." },
+      },
+      required: ["host"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "remote_tree",
+    description: "Show a bounded remote workspace tree using find.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: { type: "string" },
+        root: { type: "string", description: "Optional absolute remote workspace root." },
+        path: { type: "string", description: "Relative path inside the workspace root.", default: "." },
+        maxDepth: { type: "integer", minimum: 1, maximum: 8, default: 3 },
+        limit: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+      },
+      required: ["host"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "remote_search_text",
+    description: "Search for text inside a remote workspace. Uses rg when available, with grep fallback.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: { type: "string" },
+        root: { type: "string", description: "Optional absolute remote workspace root." },
+        path: { type: "string", description: "Relative path inside the workspace root.", default: "." },
+        query: { type: "string", description: "Literal text or regex to search for." },
+        regex: { type: "boolean", default: false },
+        limit: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+      },
+      required: ["host", "query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "remote_git_status",
+    description: "Run git status in a remote workspace.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: { type: "string" },
+        root: { type: "string", description: "Optional absolute remote workspace root." },
+      },
+      required: ["host"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "remote_replace_in_file",
+    description: "Replace exact UTF-8 text in an allowlisted remote file. Requires allowWrites=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: { type: "string" },
+        root: { type: "string", description: "Optional absolute remote workspace root." },
+        path: { type: "string", description: "Absolute path or relative path inside the workspace root." },
+        oldText: { type: "string", description: "Exact text to replace." },
+        newText: { type: "string", description: "Replacement text." },
+        expectedReplacements: { type: "integer", minimum: 1, default: 1 },
+      },
+      required: ["host", "path", "oldText", "newText"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "remote_read_file",
     description: "Read a UTF-8 text file from a configured SSH host.",
@@ -524,6 +624,70 @@ async function callTool(name, args) {
     assertCommandAllowed(config, args.command);
     return textResult(await runSsh(config, args.command, name));
   }
+  if (name === "remote_workspace_bootstrap") {
+    const root = args.root || config.workspaceRoot || "~";
+    const rootTarget = root === "~" ? "~" : shellQuote(root);
+    const command = [
+      "printf 'user='; whoami",
+      "printf 'host='; hostname",
+      "printf 'os='; uname -a",
+      "printf 'shell='; printf %s \"$SHELL\"; printf '\\n'",
+      `printf 'workspace='; cd ${rootTarget} 2>/dev/null && pwd || printf 'unavailable'`,
+      "p=$(command -v node 2>/dev/null || true); printf 'node=%s\\n' \"${p:-missing}\"",
+      "p=$(command -v npm 2>/dev/null || true); printf 'npm=%s\\n' \"${p:-missing}\"",
+      "p=$(command -v git 2>/dev/null || true); printf 'git=%s\\n' \"${p:-missing}\"",
+      "p=$(command -v rg 2>/dev/null || true); printf 'rg=%s\\n' \"${p:-missing}\"",
+      "p=$(command -v python3 2>/dev/null || true); printf 'python3=%s\\n' \"${p:-missing}\"",
+    ].join("; ");
+    return textResult(await runSsh(config, command, name));
+  }
+  if (name === "remote_tree") {
+    const target = resolveRemoteWorkspacePath(config, args.root, args.path || ".", "tree");
+    const maxDepth = Math.max(1, Math.min(Number(args.maxDepth || 3), 8));
+    const limit = Math.max(1, Math.min(Number(args.limit || 200), 1000));
+    const command = `find ${shellQuote(target)} -maxdepth ${maxDepth} -mindepth 1 -not -path '*/.git/*' -print | sort | head -n ${limit}`;
+    return textResult(await runSsh(config, command, name));
+  }
+  if (name === "remote_search_text") {
+    const target = resolveRemoteWorkspacePath(config, args.root, args.path || ".", "search");
+    const limit = Math.max(1, Math.min(Number(args.limit || 200), 1000));
+    const fixed = args.regex ? "" : "-F";
+    const grepMode = args.regex ? "-E" : "-F";
+    const command = [
+      "if command -v rg >/dev/null 2>&1; then",
+      `rg --line-number --hidden --glob '!.git' ${fixed} ${shellQuote(args.query)} ${shellQuote(target)} | head -n ${limit};`,
+      "else",
+      `grep -RIn ${grepMode} --exclude-dir=.git ${shellQuote(args.query)} ${shellQuote(target)} | head -n ${limit};`,
+      "fi",
+    ].join(" ");
+    return textResult(await runSsh(config, command, name));
+  }
+  if (name === "remote_git_status") {
+    const root = resolveRemoteWorkspacePath(config, args.root, ".", "git status");
+    return textResult(await runSsh(config, `cd ${shellQuote(root)} && git status --short --branch`, name));
+  }
+  if (name === "remote_replace_in_file") {
+    if (!config.allowWrites) {
+      throw new Error(`Writes are disabled for host alias ${config.alias}. Set allowWrites=true to enable.`);
+    }
+    const remotePath = resolveRemoteWorkspacePath(config, args.root, args.path, "replace");
+    const expected = Math.max(1, Number(args.expectedReplacements || 1));
+    const script = [
+      "import base64, pathlib",
+      `p = pathlib.Path(${JSON.stringify(remotePath)})`,
+      `old = base64.b64decode(${JSON.stringify(base64Text(args.oldText))}).decode('utf-8')`,
+      `new = base64.b64decode(${JSON.stringify(base64Text(args.newText))}).decode('utf-8')`,
+      "text = p.read_text(encoding='utf-8')",
+      "count = text.count(old)",
+      `expected = ${expected}`,
+      "if count != expected:",
+      "    raise SystemExit(f'expected {expected} replacement(s), found {count}')",
+      "p.write_text(text.replace(old, new), encoding='utf-8')",
+      "print(f'replaced {count} occurrence(s)')",
+    ].join("\n");
+    const command = `python3 -c ${shellQuote(script)}`;
+    return textResult(await runSsh(config, command, name));
+  }
   if (name === "remote_read_file") {
     const remotePath = assertPathAllowed(config, args.path, "read");
     return textResult(await runSsh(config, `cat -- ${shellQuote(remotePath)}`, name));
@@ -617,12 +781,14 @@ if (require.main === module) {
 module.exports = {
   assertCommandAllowed,
   assertPathAllowed,
+  base64Text,
   cleanHostProfile,
   defaultConfigFile,
   expandHome,
   handle,
   loadHostConfig,
   normalizeRemotePath,
+  resolveRemoteWorkspacePath,
   shellQuote,
   startServer,
   tools,
diff --git a/plugins/remote-ssh/skills/remote-ssh/SKILL.md b/plugins/remote-ssh/skills/remote-ssh/SKILL.md
@@ -15,16 +15,23 @@ Use this skill when the user asks Codex to inspect or operate a configured remot
    - SSH host as `user@hostname` or a `~/.ssh/config` host
    - optional port
    - optional identity file
+   - optional workspace root
    - optional allowed remote paths
    Then use `remote_add_host` and test with `remote_test_connection`.
-3. Prefer narrow tools over broad shell access:
+3. When the user wants to work in a remote project, prefer workspace tools:
+   - use `remote_workspace_bootstrap` to check environment readiness
+   - use `remote_tree` to inspect project structure
+   - use `remote_search_text` to locate code
+   - use `remote_git_status` before and after edits
+   - use `remote_replace_in_file` for narrow exact edits when writes are enabled
+4. Prefer narrow tools over broad shell access:
    - use `remote_list_dir` before reading unknown paths
    - use `remote_read_file` for file inspection
    - use `remote_write_file` only when the user clearly wants a remote edit
    - use `remote_run` for tests, service status, logs, and other explicit commands
-4. Keep remote commands non-interactive.
-5. Do not request or echo private key material. Only ask for the identity file path.
-6. Summarize remote command output clearly when the user cannot see the tool output.
+5. Keep remote commands non-interactive.
+6. Do not request or echo private key material. Only ask for the identity file path.
+7. Summarize remote command output clearly when the user cannot see the tool output.
 
 ## Safety
 
diff --git a/plugins/remote-ssh/test/remote-ssh-mcp.test.js b/plugins/remote-ssh/test/remote-ssh-mcp.test.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zaintechnologiesltd/codex-remote-ssh",`
`3`		`- "version": "0.3.1",`
	`3`	`+ "version": "0.4.0",`
`4`	`4`	`"description": "Enterprise-grade Remote SSH MCP tools for OpenAI Codex.",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"author": {`