enterprise-ssh-mcp-server 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.3.3 - 2026-10-25
+
+- Add an explicit, optional one-shot InstaBox `ephemeralToken` credential source for `ssh_run_openssh_temporary` and `ssh_run_openssh`; no prior per-token setup script is needed.
+- Preserve local CA fingerprint pinning or native OpenSSH known_hosts verification; an untrusted host is still rejected before sending credentials.
+- Do not expose a one-shot token in native SSH process arguments or returned output; isolate transient config files and clean them up.
+- Keep `usernameEnvVar` as the preferred option when avoiding potentially logged MCP tool arguments, and document the privacy tradeoffs.
+- Add integration coverage for one-shot tokens, response redaction, temporary file cleanup, input validation, and missing CA trust.
+
+## 0.3.2 - 2026-10-25
+
+- Refactor MCP tool registration into domain-focused modules while preserving the stdio entry point and existing tool names.
+- Add one-shot native OpenSSH execution and temporary host-CA trust for OpenSSH host-certificate endpoints, with fail-closed local fingerprint pinning and cleanup of temporary trust files.
+- Add host-key/CA probing and an explicit CA trust workflow that checks against a locally configured pin.
+- Add atomic .env hot reload for runtime defaults and SSH profiles; invalid or partial edits keep the last valid snapshot.
+- Redact InstaBox bearer-token usernames from public profile/session results and SSH debug output.
+- Add regression coverage for target validation, host CA parsing, temporary OpenSSH execution/cleanup, and configuration reload.
+- Add a local PowerShell MCP end-to-end test harness. It is maintained in the source repository and is intentionally excluded from the npm package.

package/README.md

@@ -100,10 +100,21 @@ npm run build
 }
 ```
 
+修改 TypeScript 源码后自动重启开发进程：
+
+```powershell
+npm run dev:watch
+```
+
+`dev:watch` 是监视文件后重启进程，不是在运行中的 MCP 进程内替换模块；重启会断开现有 SSH 会话，不应当作生产环境的无中断代码热更新。
+
 ## 能力范围
 
 - Profile：`ssh_list_profiles`、`ssh_reload_profiles`、`ssh_connect_profile`、`ssh_check_profile`、`ssh_run_profile`
+- 主机信任：`ssh_probe_host_key`、`ssh_trust_host_ca`
+- 临时 OpenSSH 连接：`ssh_run_openssh_temporary`（独立临时 `known_hosts` 文件，命令结束后删除，不修改用户永久信任文件）
 - 会话：`ssh_connect`、`ssh_list_sessions`、`ssh_disconnect`、`ssh_disconnect_all`、`ssh_rekey`
+- 原生 OpenSSH 单次命令：`ssh_run_openssh`（适用于需要 OpenSSH 主机证书算法的端点；不创建持久会话）
 - 命令：`ssh_exec`，支持 env、stdin、PTY、超时、stdout/stderr 最大字节限制、UTF-8/base64 输出
 - 远程项目编辑：`ssh_project_open`、`ssh_project_tree`、`ssh_project_search`、`ssh_project_stat`、`ssh_file_read`、`ssh_file_patch`、`ssh_project_validate_patch`、`ssh_project_apply_patch`、`ssh_project_diff`、`ssh_project_run_checks`、`ssh_edit_history`、`ssh_edit_rollback`
 - 交互 shell：`ssh_shell_open`、`ssh_shell_write`、`ssh_shell_read`、`ssh_shell_resize`、`ssh_shell_close`、`ssh_shell_list`
@@ -111,6 +122,105 @@ npm run build
 - 大文件传输：`sftp_upload_start`、`sftp_upload_profile`、`sftp_download_start`、`sftp_download_profile`、`sftp_transfer_status`、`sftp_transfer_list`、`sftp_transfer_cancel`
 - 端口转发：`ssh_tunnel_local_start`、`ssh_tunnel_remote_start`、`ssh_tunnel_list`、`ssh_tunnel_stop`
 
+## 临时直连未配置的 SSH 设备
+
+不需要先把设备写入 `.env` Profile。调用 `ssh_connect` 时可以直接提供主机、端口和认证信息；会话只保存在当前 MCP server 进程中，连接不会自动写入配置文件。
+
+`host` 支持两种形式：
+
+1. 主机和用户名分开：`host="ssh.example.com"`、`username="deploy"`。
+2. 使用常见的 SSH 目标格式：`host="deploy@ssh.example.com"`，此时可以省略 `username`。
+
+例如，针对平台给出的 `Hostname user@ssh.example.com` 和 `Port 2222`，把 `user@ssh.example.com` 作为 `host`，把 `2222` 作为 `port` 即可。根据服务器的认证配置，可能需要提供 `privateKeyPath`、`privateKey`、`password` 或 `agent`；部分平台会将临时访问令牌直接编码在 SSH 用户名中。
+
+连接示例（建议优先使用本地私钥文件路径，而不是把私钥内容直接放进工具参数）：
+
+```json
+{
+  "host": "deploy@ssh.example.com",
+  "port": 2222,
+  "privateKeyPath": "C:/Users/yourname/.ssh/id_ed25519",
+  "name": "temporary-lab"
+}
+```
+
+使用 `ssh_probe_host_key` 可以在不进行用户认证的情况下查看主机指纹；该工具不会自动信任探测到的密钥。兼容的 `ssh2` 连接仍可显式提供 `hostHash` 和 `expectedHostHash`。对于原生 OpenSSH 主机证书，可选择永久登记经过独立核验的 CA，或使用下文的临时信任模式。不要把首次连接成功等同于已完成主机身份验证。需要长期复用的设备，再单独维护为 Profile。
+
+### InstaBox SSH token
+
+InstaBox 官方的 Connect → Create token 会生成形如 `ssh ibssh_…@<host>` 的 SSH 命令；token 本身就是 SSH 用户名，不需要额外的 SSH 私钥或密码。token 在被撤销或到期前有效，详见 [InstaBox SSH 文档](https://instabox.sh/docs/ssh)。
+
+为了避免把 bearer token 发送给伪装的 SSH 网关，`ssh_probe_host_key` 可以在不进行认证的情况下检查主机证书和签名 CA 指纹；它不会自动信任探测结果。需要通过可信渠道核验 CA 指纹，不要只因为网络探测成功就自动信任。
+
+**当前兼容性限制：** InstaBox 网关提供 `ssh-ed25519-cert-v01@openssh.com` OpenSSH 主机证书，而当前持久会话后端 `ssh2` 不支持这种主机证书算法。程序会在发送 token 前拒绝通过 `ssh_connect` 建立持久会话。可以使用 `ssh_run_openssh` 通过系统 OpenSSH 执行单次命令；它强制 `StrictHostKeyChecking=yes`，要求默认或指定的 `known_hosts` 中已有可信的 CA/主机条目。若只想临时连接，推荐使用 `ssh_run_openssh_temporary`：它读取本地 MCP 进程配置中的 host-specific CA 指纹 pin，重新探测 CA，并要求实时指纹严格匹配，然后使用独立临时 `known_hosts` 文件执行命令，并在结束后删除该文件，不改动用户永久的 `known_hosts`。工具参数不能设置或覆盖这个信任锚；未配置 pin 时会在发起网络探测前拒绝执行。当前 OpenSSH 适配器还不提供持久 Shell、SFTP、后台传输或隧道；这些需要后续统一会话抽象。
+
+本地 CA pin 配置：通过独立可信渠道核验 CA 指纹后，在 MCP 客户端的服务器 `env` 配置中设置 `SSH_MCP_TRUSTED_HOST_CA_FINGERPRINTS`。值是 JSON 对象，键为 `host:port`，值为完整 `SHA256:` 指纹；例如：
+
+```json
+{
+  "mcpServers": {
+    "enterprise-ssh": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "enterprise-ssh-mcp-server"],
+      "env": {
+        "SSH_MCP_TRUSTED_HOST_CA_FINGERPRINTS": "{\"ssh.instabox.sh:2222\":\"SHA256:替换为从可信来源独立核验的完整指纹\"}"
+      }
+    }
+  }
+}
+```
+
+请把示例指纹替换成通过独立可信渠道核验的真实值；不能把 `ssh_probe_host_key` 当前返回值直接复制进配置并将其视为已验证。该环境变量是本地信任锚，工具调用参数不能覆盖它。未配置、JSON 格式错误或指纹格式不正确时，连接和永久信任操作都会失败关闭。
+
+永久信任流程：先按上面步骤配置可信 CA pin，再调用 `ssh_probe_host_key` 检查证书，并在确认需要写入永久信任后调用 `ssh_trust_host_ca`，将探测得到的 `certificateAuthority.knownHostsEntry` 登记到本机 `~/.ssh/known_hosts`。该工具会再次校验 CA 公钥与本地 pin 完全一致；它不会自行建立新的信任锚，也不会覆盖同一主机已存在的冲突 CA。
+
+临时信任流程：无需修改永久 `known_hosts`。在 MCP 客户端环境中配置经过独立核验的 CA pin 后，调用 `ssh_run_openssh_temporary`。可以使用环境变量名 `usernameEnvVar`，或明确选择一次性的 `ephemeralToken`；两者不能同时传入。工具会重新探测实时 CA，并要求其指纹与本地 pin 完全匹配；验证失败时不会运行命令。验证通过后才会创建临时 trust store，命令结束即清理。工具调用不接受 `expectedHostCaFingerprint` 或 `confirmedHostCaFingerprint` 参数，防止模型把未验证的探测结果自我确认。
+
+**认证有两种选择。** 默认推荐将 InstaBox Token 存在 MCP 子进程环境，通过 `usernameEnvVar` 引用；新增可选 `ephemeralToken` 允许在某一次 MCP 请求中直接传入凭据，不需要运行预保存脚本，执行后 MCP server 不持久化该 Token。**注意：MCP 客户端、模型平台、工具传输层及调用日志仍可能记录参数；“单次使用”不意味着聊天或工具日志不会保留秘密。** 不要在不可信或有广泛日志留存的聊天/工具链里使用该参数。对于高权限、长期有效的 Token，推荐本机安全凭据存储。直接把 `ibssh_…` token 放进 `host` 或 `username` 参数仍会被拒绝。
+
+两种方式均通过隔离的临时 OpenSSH 配置传入 SSH 用户名，使 Token 不出现在原生 `ssh.exe` 的命令行参数。程序会将 Token 短暂写入系统临时目录中的 OpenSSH 配置文件，并在子进程结束（包括启动失败）后清理；POSIX 系统会以 `0600` 创建文件，Windows 访问保护取决于临时目录 ACL。不要在共享或权限宽松的 Windows 账户环境中使用此方式，也不要把真实 token 写进仓库或共享配置。
+
+示例（仅在已核验并明确确认 InstaBox 主机 CA 指纹后使用；临时信任，不写永久 `known_hosts`）：
+
+```json
+{
+  "host": "ssh.instabox.sh",
+  "usernameEnvVar": "SSH_MCP_INSTABOX_TOKEN",
+  "port": 2222,
+  "command": "uname -a"
+}
+```
+
+`ephemeralToken` 示例（**演示占位值，不是真实凭据**；仍需事先在本机核验并固定 CA pin）：
+
+```json
+{
+  "host": "ssh.instabox.sh",
+  "port": 2222,
+  "ephemeralToken": "ibssh_test_fixture_replace_for_one_request",
+  "command": "uname -a"
+}
+```
+
+其他普通 SSH 主机可以直接调用 `ssh_connect` 并提供 `host`、`port`、`username`、`password` 或私钥信息，获得 `sessionId` 后执行命令/SFTP，再 `ssh_disconnect`。不需要新建 Profile、运行本机脚本或者重新启动 MCP。仅 InstaBox 等使用 OpenSSH 主机证书而不被 `ssh2` 支持的网关，需要用一次性原生 OpenSSH 命令工具；它目前不支持持久交互 Shell/SFTP。
+
+`ssh_probe_host_key` 的返回值包含 `certificateAuthority.fingerprint` 和 `certificateAuthority.knownHostsEntry`。前者必须通过可信渠道独立核验后写入本地 pin 配置，后者只有在 CA 身份与 pin 匹配后才应加入 OpenSSH `known_hosts`；探测结果本身不等于信任。
+
+InstaBox token 用户名会在 Profile/会话结果和调试日志中脱敏。不要把 token 写入仓库或共享 `.env`；如果 token 已经暴露在聊天、日志或其他不可信位置，请在 InstaBox 中撤销并重新创建。
+
+### 本机真实 MCP 端到端测试
+
+如果要验证的不只是系统 `ssh.exe`，而是 MCP server 本身是否能读取本地 token、检查 CA pin、调用临时 OpenSSH 后端并清理信任文件，可以在**源码仓库根目录**的 Windows PowerShell 中运行（该测试脚本仅随源码仓库维护，不包含在 npm 发布包中）：
+
+```powershell
+npm run build
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-instabox-mcp.ps1
+```
+
+脚本会在终端中隐藏式读取 `ibssh_` token，将其仅放入本次 MCP 子进程环境，不写入项目文件；然后通过真实 MCP stdio JSON-RPC 调用 `ssh_run_openssh_temporary` 执行只读 `uname -a`，并检查退出码与 `trustStoreDeleted`。结束后会关闭 MCP 子进程并清理本次进程中的凭据引用。
+
+脚本会要求输入 CA 指纹。如果输入独立可信渠道核验后的 `SHA256:...` 指纹，会按该 pin 进行验证；输入 `USE-OBSERVED-ONCE` 则仅用于功能测试，使用此前网络探测到的指纹。**后者不构成 CA 来源的独立身份验证，不应复制到永久配置或 `known_hosts`。** 不要把 Token 输出或粘贴到聊天记录、终端命令参数或仓库中。
+
 ## Agent 使用建议
 
 - 远端健康检查、环境确认、服务器巡检：优先使用 `ssh_check_profile`。
@@ -152,6 +262,8 @@ npm run build
 
 MCP server 启动时会读取项目根目录的 `.env`。如果你的 MCP client 从其他目录启动，也可以用 `SSH_MCP_ENV_FILE` 指定绝对路径。
 
+默认会监视 `.env` 文件：保存后约 1 秒内会尝试重新加载运行默认值和所有 Profile，解析成功后作为一个完整快照应用；编辑器保存过程中的半成品或非法配置会被拒绝，上一份有效配置继续生效。也可以调用 `ssh_reload_config` 或 `ssh_reload_profiles` 立即触发同样的原子重载。修改 `SSH_MCP_TOOLSET` 或 `SSH_MCP_ENABLE_DANGEROUS_TOOLS` 后仍需重启 MCP server，因为工具暴露集合在启动时注册。
+
 运行时默认策略：
 
 ```dotenv

package/dist/app/create-app.d.ts

@@ -0,0 +1,4 @@
+export declare function createApp(): {
+    server: import("@modelcontextprotocol/sdk/server/mcp").McpServer;
+    shutdown: () => Promise<void>;
+};

package/dist/app/create-app.js

@@ -0,0 +1,38 @@
+import { toolContext } from "./tool-context.js";
+import { startEnvHotReload } from "../env-reload.js";
+import { registerConfigProfileTools } from "../tools/register-config-profile-tools.js";
+import { registerProjectTools } from "../tools/register-project-tools.js";
+import { registerSessionTools } from "../tools/register-session-tools.js";
+import { registerSftpTools } from "../tools/register-sftp-tools.js";
+import { registerTransferTools } from "../tools/register-transfer-tools.js";
+import { registerTunnelTools } from "../tools/register-tunnel-tools.js";
+export function createApp() {
+    registerConfigProfileTools(toolContext);
+    registerProjectTools(toolContext);
+    registerSessionTools(toolContext);
+    registerSftpTools(toolContext);
+    registerTransferTools(toolContext);
+    registerTunnelTools(toolContext);
+    const stopEnvHotReload = startEnvHotReload({
+        envPath: toolContext.envPath,
+        reload: toolContext.reloadEnvState,
+        onReload: (snapshot) => {
+            const restartNote = snapshot.restartRequiredForToolVisibility
+                ? "; tool visibility settings differ from startup and require an MCP restart"
+                : "";
+            process.stderr.write(`[ssh-mcp] .env hot-reloaded (${snapshot.profiles.length} profile(s))${restartNote}\n`);
+        },
+        onError: (error) => {
+            const message = error instanceof Error ? error.message : "unknown configuration error";
+            process.stderr.write(`[ssh-mcp] .env hot reload rejected; previous settings remain active (${message})\n`);
+        },
+    });
+    return {
+        server: toolContext.server,
+        shutdown: async () => {
+            stopEnvHotReload();
+            await toolContext.sessions.disconnectAll();
+        },
+    };
+}
+//# sourceMappingURL=create-app.js.map

package/dist/app/create-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.js","sourceRoot":"","sources":["../../src/app/create-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAExE,MAAM,UAAU,SAAS;IACvB,0BAA0B,CAAC,WAAW,CAAC,CAAC;IACxC,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAClC,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAClC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC/B,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACnC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEjC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;QACzC,OAAO,EAAE,WAAW,CAAC,OAAO;QAC5B,MAAM,EAAE,WAAW,CAAC,cAAc;QAClC,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE;YACrB,MAAM,WAAW,GAAG,QAAQ,CAAC,gCAAgC;gBAC3D,CAAC,CAAC,2EAA2E;gBAC7E,CAAC,CAAC,EAAE,CAAC;YACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,QAAQ,CAAC,QAAQ,CAAC,MAAM,eAAe,WAAW,IAAI,CACvF,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACjB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,CAAC;YACvF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wEAAwE,OAAO,KAAK,CAAC,CAAC;QAC7G,CAAC;KACF,CAAC,CAAC;IAEH,OAAO;QACL,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,QAAQ,EAAE,KAAK,IAAmB,EAAE;YAClC,gBAAgB,EAAE,CAAC;YACnB,MAAM,WAAW,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/app/tool-context.d.ts

@@ -0,0 +1,258 @@
+import { McpServer, type RegisteredTool, type ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import type { PseudoTtyOptions } from "ssh2";
+import { ProfileRegistry, type SshServerProfile } from "../env-profiles.js";
+import { RuntimeConfigRegistry } from "../runtime-config.js";
+import { SessionRegistry } from "../session-registry.js";
+import type { ExecResult, SessionSummary, SshSession } from "../ssh-session.js";
+import { entryToJson, sftpChmod, sftpChown, sftpMkdir, sftpMkdirRecursive, sftpReadFileLimited, sftpReadDir, sftpReadlink, sftpRealpath, sftpRemove, sftpRename, sftpStat, sftpSymlink, sftpUtimes, sftpWriteFile, statsToJson } from "../sftp-ops.js";
+import { TransferManager } from "../transfer-manager.js";
+import { assertNonEmpty, McpToolError, setCompactJsonResponse, toToolResult } from "../tool-result.js";
+import { defaultTreeOptions, maxEditFileBytes, parseUnifiedPatch, publicSnapshot, readRemoteFileSnapshot, readRemoteTree, resolveSafeRemotePath, sha256, type BackupRecord } from "../remote-edit.js";
+declare const ptySchema: z.ZodObject<{
+    rows: z.ZodOptional<z.ZodNumber>;
+    cols: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    term: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    rows?: number | undefined;
+    cols?: number | undefined;
+    height?: number | undefined;
+    width?: number | undefined;
+    term?: string | undefined;
+}, {
+    rows?: number | undefined;
+    cols?: number | undefined;
+    height?: number | undefined;
+    width?: number | undefined;
+    term?: string | undefined;
+}>;
+declare const expectedFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodUnion<[z.ZodString, z.ZodLiteral<"absent">]>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    sha256: string;
+}, {
+    path: string;
+    sha256: string;
+}>;
+type ToolConfig<OutputArgs extends ZodRawShapeCompat | AnySchema, InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined> = {
+    title?: string;
+    description?: string;
+    inputSchema?: InputArgs;
+    outputSchema?: OutputArgs;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+};
+declare const remoteCheckNameSchema: z.ZodEnum<["identity", "pwd", "os", "uptime", "disk", "memory", "processes"]>;
+type RemoteCheckName = z.infer<typeof remoteCheckNameSchema>;
+declare function registerTool<OutputArgs extends ZodRawShapeCompat | AnySchema, InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined>(name: string, config: ToolConfig<OutputArgs, InputArgs>, cb: ToolCallback<InputArgs>): RegisteredTool | undefined;
+type ExpectedFile = z.infer<typeof expectedFileSchema>;
+interface ProjectWorkspace {
+    profile: SshServerProfile;
+    sessionId: string;
+    session: SshSession;
+    sftp: Awaited<ReturnType<SshSession["getSftp"]>>;
+    rootPath: string;
+}
+type EditOperation = "create" | "modify" | "delete" | "move";
+interface EditFileChange {
+    path: string;
+    remotePath: string;
+    operation: EditOperation;
+    oldSha256?: string | undefined;
+    newSha256?: string | undefined;
+    bytes?: number | undefined;
+    backup?: BackupRecord | undefined;
+    movedToPath?: string | undefined;
+    movedToRemotePath?: string | undefined;
+}
+interface EditRecord {
+    editId: string;
+    profileName: string;
+    projectRoot: string;
+    createdAt: string;
+    rolledBackAt?: string;
+    changes: EditFileChange[];
+}
+declare function connectProjectWorkspace(profileName: string, projectRoot: string | undefined, requireEdit: boolean): Promise<ProjectWorkspace>;
+declare function inspectRemoteProject(session: SshSession, rootPath: string): Promise<object>;
+declare function projectProfileSummary(profile: SshServerProfile): object;
+declare function writeProjectFile(workspace: ProjectWorkspace, path: string, data: Buffer, expectedSha256: string | "absent" | undefined, createDirs: boolean, mode: number | undefined): Promise<EditRecord>;
+declare function applySinglePatchFile(workspace: ProjectWorkspace, path: string, patchFile: ReturnType<typeof parseUnifiedPatch>[number], expectedSha256: string | "absent", createDirs: boolean): Promise<EditRecord>;
+declare function validateProjectPatch(workspace: ProjectWorkspace, patchFiles: ReturnType<typeof parseUnifiedPatch>, expectedFiles: ExpectedFile[]): Promise<object>;
+declare function applyProjectPatch(workspace: ProjectWorkspace, patchFiles: ReturnType<typeof parseUnifiedPatch>, expectedFiles: ExpectedFile[], createDirs: boolean): Promise<EditRecord>;
+declare function deleteProjectFile(workspace: ProjectWorkspace, path: string, expectedSha256: string): Promise<EditRecord>;
+declare function moveProjectFile(workspace: ProjectWorkspace, fromPath: string, toPath: string, expectedSha256: string, createDirs: boolean): Promise<EditRecord>;
+declare function rollbackEdit(workspace: ProjectWorkspace, edit: EditRecord): Promise<EditRecord>;
+declare function resolveProjectPathArgs(workspace: ProjectWorkspace, paths: string[], mustExist: boolean): Promise<string[]>;
+declare function assertPatchSize(patch: string): void;
+declare function compactTreeOptions(maxDepth: number | undefined, maxEntries: number | undefined, includeHidden: boolean | undefined, ignoreNames: string[] | undefined): Parameters<typeof defaultTreeOptions>[0];
+declare function buildProjectSearchCommand(rootPath: string, query: string, paths: string[], literal: boolean, maxResults: number, contextLines: number): string;
+declare function buildProjectDiffCommand(rootPath: string, paths: string[]): string;
+declare function parseSearchMatches(output: string): Array<{
+    path: string;
+    line?: number;
+    text: string;
+}>;
+declare function normalizeProfileNameForHistory(profileName: string): string;
+interface ProfileConnectionInput {
+    profileName: string;
+    keyboardResponses: string[];
+    strictVendor: boolean;
+    debug: boolean;
+    sessionName?: string | undefined;
+    agentForward?: boolean | undefined;
+    tryKeyboard?: boolean | undefined;
+    keepaliveIntervalMs?: number | undefined;
+    keepaliveCountMax?: number | undefined;
+    readyTimeoutMs?: number | undefined;
+    connectionTimeoutMs?: number | undefined;
+    hostHash?: "md5" | "sha1" | "sha256" | undefined;
+    expectedHostHash?: string | undefined;
+}
+interface ConnectedProfileSession {
+    profile: {
+        name: string;
+        aliases: string[];
+        host: string;
+        port: number;
+        username: string;
+        displayName?: string;
+        defaultDir?: string;
+        description?: string;
+        platform?: string;
+    };
+    session: SessionSummary;
+}
+declare function connectProfileSession(input: ProfileConnectionInput): Promise<ConnectedProfileSession>;
+declare function buildRemoteCommand(command: string, workingDirectory: string | undefined): string;
+interface RemoteCheckInput {
+    name: RemoteCheckName;
+    title: string;
+    command: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    execute: (command: string) => Promise<ExecResult>;
+}
+declare function runRemoteCheck(input: RemoteCheckInput): Promise<{
+    name: RemoteCheckName;
+    title: string;
+    command: string;
+    ok: boolean;
+    result?: ExecResult;
+    error?: string;
+}>;
+declare function compactExecPty(input: boolean | z.infer<typeof ptySchema> | undefined): PseudoTtyOptions | boolean | undefined;
+declare function compactPty(input: z.infer<typeof ptySchema> | undefined): PseudoTtyOptions | undefined;
+export declare const toolContext: {
+    server: McpServer;
+    envPath: string;
+    sessions: SessionRegistry;
+    z: typeof z;
+    setCompactJsonResponse: typeof setCompactJsonResponse;
+    toToolResult: typeof toToolResult;
+    profiles: ProfileRegistry;
+    runtimeConfig: RuntimeConfigRegistry;
+    reloadEnvState: () => import("../env-reload.js").EnvReloadSnapshot;
+    wireEncodingSchema: z.ZodDefault<z.ZodEnum<["utf8", "base64"]>>;
+    remoteCheckNameSchema: z.ZodEnum<["identity", "pwd", "os", "uptime", "disk", "memory", "processes"]>;
+    DEFAULT_REMOTE_CHECKS: ("identity" | "pwd" | "os" | "uptime" | "disk" | "memory" | "processes")[];
+    REMOTE_CHECK_COMMANDS: Record<"identity" | "pwd" | "os" | "uptime" | "disk" | "memory" | "processes", {
+        title: string;
+        command: string;
+    }>;
+    registerTool: typeof registerTool;
+    connectProfileSession: typeof connectProfileSession;
+    buildRemoteCommand: typeof buildRemoteCommand;
+    runRemoteCheck: typeof runRemoteCheck;
+    sftpStat: typeof sftpStat;
+    statsToJson: typeof statsToJson;
+    McpToolError: typeof McpToolError;
+    defaultTreeOptions: typeof defaultTreeOptions;
+    maxEditFileBytes: typeof maxEditFileBytes;
+    parseUnifiedPatch: typeof parseUnifiedPatch;
+    publicSnapshot: typeof publicSnapshot;
+    readRemoteFileSnapshot: typeof readRemoteFileSnapshot;
+    readRemoteTree: typeof readRemoteTree;
+    resolveSafeRemotePath: typeof resolveSafeRemotePath;
+    sha256: typeof sha256;
+    editHistory: Map<string, EditRecord>;
+    projectRootSchema: z.ZodOptional<z.ZodString>;
+    fileEncodingSchema: z.ZodDefault<z.ZodEnum<["utf8", "base64"]>>;
+    expectedShaSchema: z.ZodUnion<[z.ZodString, z.ZodLiteral<"absent">]>;
+    expectedFileSchema: z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodUnion<[z.ZodString, z.ZodLiteral<"absent">]>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        sha256: string;
+    }, {
+        path: string;
+        sha256: string;
+    }>;
+    projectPathSchema: z.ZodString;
+    connectProjectWorkspace: typeof connectProjectWorkspace;
+    inspectRemoteProject: typeof inspectRemoteProject;
+    projectProfileSummary: typeof projectProfileSummary;
+    writeProjectFile: typeof writeProjectFile;
+    applySinglePatchFile: typeof applySinglePatchFile;
+    validateProjectPatch: typeof validateProjectPatch;
+    applyProjectPatch: typeof applyProjectPatch;
+    deleteProjectFile: typeof deleteProjectFile;
+    moveProjectFile: typeof moveProjectFile;
+    rollbackEdit: typeof rollbackEdit;
+    resolveProjectPathArgs: typeof resolveProjectPathArgs;
+    assertPatchSize: typeof assertPatchSize;
+    compactTreeOptions: typeof compactTreeOptions;
+    buildProjectSearchCommand: typeof buildProjectSearchCommand;
+    buildProjectDiffCommand: typeof buildProjectDiffCommand;
+    parseSearchMatches: typeof parseSearchMatches;
+    normalizeProfileNameForHistory: typeof normalizeProfileNameForHistory;
+    sessionIdSchema: z.ZodString;
+    ptySchema: z.ZodObject<{
+        rows: z.ZodOptional<z.ZodNumber>;
+        cols: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+        term: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        rows?: number | undefined;
+        cols?: number | undefined;
+        height?: number | undefined;
+        width?: number | undefined;
+        term?: string | undefined;
+    }, {
+        rows?: number | undefined;
+        cols?: number | undefined;
+        height?: number | undefined;
+        width?: number | undefined;
+        term?: string | undefined;
+    }>;
+    compactExecPty: typeof compactExecPty;
+    compactPty: typeof compactPty;
+    entryToJson: typeof entryToJson;
+    sftpChmod: typeof sftpChmod;
+    sftpChown: typeof sftpChown;
+    sftpMkdir: typeof sftpMkdir;
+    sftpMkdirRecursive: typeof sftpMkdirRecursive;
+    sftpReadFileLimited: typeof sftpReadFileLimited;
+    sftpReadDir: typeof sftpReadDir;
+    sftpReadlink: typeof sftpReadlink;
+    sftpRealpath: typeof sftpRealpath;
+    sftpRemove: typeof sftpRemove;
+    sftpRename: typeof sftpRename;
+    sftpSymlink: typeof sftpSymlink;
+    sftpUtimes: typeof sftpUtimes;
+    sftpWriteFile: typeof sftpWriteFile;
+    modeSchema: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    assertNonEmpty: typeof assertNonEmpty;
+    transfers: TransferManager;
+    positivePortSchema: z.ZodNumber;
+};
+export type ToolContext = typeof toolContext;
+export {};