@pyrokine/mcp-ssh 2.4.0 → 2.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,49 @@
1
+ export const DEFAULT_SFTP_OPERATION_TIMEOUT_MS = 600_000;
2
+ export const HARD_SFTP_OPERATION_TIMEOUT_MS = 3_600_000;
3
+ export class SftpOperationTimeoutError extends Error {
4
+ timeout;
5
+ details;
6
+ constructor(timeout) {
7
+ super(`SFTP operation timed out after ${timeout}ms; remote transfer state is unknown`);
8
+ this.timeout = timeout;
9
+ this.name = 'SftpOperationTimeoutError';
10
+ this.details = {
11
+ operationStatus: 'unknown',
12
+ retryable: true,
13
+ timeout,
14
+ };
15
+ }
16
+ }
17
+ export function normalizeSftpOperationTimeout(timeout) {
18
+ const normalized = timeout ?? DEFAULT_SFTP_OPERATION_TIMEOUT_MS;
19
+ if (!Number.isSafeInteger(normalized) || normalized <= 0 || normalized > HARD_SFTP_OPERATION_TIMEOUT_MS) {
20
+ throw new Error(`SFTP timeout must be between 1 and ${HARD_SFTP_OPERATION_TIMEOUT_MS}ms`);
21
+ }
22
+ return normalized;
23
+ }
24
+ export function withSftpOperationTimeout(operation, timeout, onTimeout) {
25
+ const normalizedTimeout = normalizeSftpOperationTimeout(timeout);
26
+ return new Promise((resolve, reject) => {
27
+ let settled = false;
28
+ const settle = (callback) => {
29
+ if (settled) {
30
+ return;
31
+ }
32
+ settled = true;
33
+ clearTimeout(timer);
34
+ callback();
35
+ };
36
+ const timer = setTimeout(() => {
37
+ settle(() => {
38
+ try {
39
+ onTimeout();
40
+ }
41
+ catch {
42
+ // 超时响应优先于释放 SFTP channel 失败
43
+ }
44
+ reject(new SftpOperationTimeoutError(normalizedTimeout));
45
+ });
46
+ }, normalizedTimeout);
47
+ operation.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
48
+ });
49
+ }
@@ -9,32 +9,77 @@ import * as path from 'path';
9
9
  import { z } from 'zod';
10
10
  import { sessionManager } from '../session-manager.js';
11
11
  import { parseProxyJump, parseSSHConfig } from '../ssh-config.js';
12
+ import { sshPortSchema } from './schema.js';
12
13
  import { expandTilde, formatError, formatResult } from './utils.js';
14
+ const templateJumpHostSchema = z.object({
15
+ host: z.string(),
16
+ user: z.string(),
17
+ password: z.string().optional(),
18
+ keyPath: z.string().optional(),
19
+ port: sshPortSchema.optional(),
20
+ readyTimeout: z.number().int().positive().max(600000).optional(),
21
+ });
22
+ const connectionTemplateSchema = z.object({
23
+ configHost: z.string().optional(),
24
+ host: z.string().optional(),
25
+ user: z.string().optional(),
26
+ username: z.string().optional(),
27
+ password: z.string().optional(),
28
+ keyPath: z.string().optional(),
29
+ privateKeyPath: z.string().optional(),
30
+ port: sshPortSchema.optional(),
31
+ alias: z.string().optional(),
32
+ env: z.record(z.string(), z.string()).optional(),
33
+ defaultEnv: z.record(z.string(), z.string()).optional(),
34
+ runAs: z.string().optional(),
35
+ keepaliveInterval: z.number().int().positive().optional(),
36
+ readyTimeout: z.number().int().positive().max(600000).optional(),
37
+ jumpHost: templateJumpHostSchema.optional(),
38
+ });
13
39
  function loadTemplates() {
14
40
  const fromEnv = process.env.SSH_MCP_TEMPLATES;
15
- if (fromEnv) {
16
- return JSON.parse(fromEnv);
17
- }
18
- const filePath = path.join(os.homedir(), '.mcp-ssh', 'templates.json');
19
- if (!fs.existsSync(filePath)) {
41
+ const source = fromEnv ??
42
+ (() => {
43
+ const filePath = path.join(os.homedir(), '.mcp-ssh', 'templates.json');
44
+ return fs.existsSync(filePath) ? fs.readFileSync(expandTilde(filePath), 'utf-8') : undefined;
45
+ })();
46
+ if (!source) {
20
47
  return {};
21
48
  }
22
- return JSON.parse(fs.readFileSync(expandTilde(filePath), 'utf-8'));
49
+ const parsed = JSON.parse(source);
50
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
51
+ throw new Error('SSH templates must be an object keyed by template name');
52
+ }
53
+ return parsed;
23
54
  }
24
55
  function getTemplate(name) {
25
56
  if (!name) {
26
57
  return {};
27
58
  }
28
- const templates = loadTemplates();
29
- const template = templates[name];
30
- if (!template) {
59
+ let templates;
60
+ try {
61
+ templates = loadTemplates();
62
+ }
63
+ catch (error) {
64
+ throw new Error(`Template '${name}' could not be loaded: ${error instanceof Error ? error.message : String(error)}`, {
65
+ cause: error,
66
+ });
67
+ }
68
+ const rawTemplate = templates[name];
69
+ if (!rawTemplate) {
31
70
  const available = Object.keys(templates);
32
71
  const suggestion = available.length
33
72
  ? `Available templates: ${available.slice(0, 20).join(', ')}`
34
73
  : 'No templates found. Define SSH_MCP_TEMPLATES or ~/.mcp-ssh/templates.json';
35
74
  throw new Error(`Template '${name}' not found. ${suggestion}`);
36
75
  }
37
- return template;
76
+ const parsed = connectionTemplateSchema.safeParse(rawTemplate);
77
+ if (!parsed.success) {
78
+ const issue = parsed.error.issues[0];
79
+ const field = issue.path.length > 0 ? issue.path.join('.') : '<root>';
80
+ throw new Error(`Template '${name}' is invalid at ${field}: ${issue.message}`);
81
+ }
82
+ return parsed.data;
38
83
  }
39
84
  function mergeEnv(templateEnv, argsEnv) {
40
85
  const merged = { ...templateEnv, ...argsEnv };
@@ -49,7 +94,7 @@ const connectSchema = z.object({
49
94
  user: z.string().optional().describe('用户名(使用 configHost 时可省略)'),
50
95
  password: z.string().optional().describe('密码'),
51
96
  keyPath: z.string().optional().describe('SSH 私钥路径'),
52
- port: z.number().optional().describe('SSH 端口,默认 22'),
97
+ port: sshPortSchema.optional().describe('SSH 端口,默认 22'),
53
98
  alias: z.string().optional().describe('连接别名(可选,默认使用 configHost 或 host)'),
54
99
  env: z.record(z.string(), z.string()).optional().describe('环境变量'),
55
100
  defaultEnv: z.record(z.string(), z.string()).optional().describe('连接级默认环境变量'),
@@ -68,7 +113,7 @@ const connectSchema = z.object({
68
113
  user: z.string().describe('跳板机用户名'),
69
114
  password: z.string().optional().describe('跳板机密码'),
70
115
  keyPath: z.string().optional().describe('跳板机私钥路径'),
71
- port: z.number().optional().describe('跳板机端口,默认 22'),
116
+ port: sshPortSchema.optional().describe('跳板机端口,默认 22'),
72
117
  readyTimeout: z
73
118
  .number()
74
119
  .int()
@@ -135,10 +180,10 @@ async function handleConnect(args) {
135
180
  });
136
181
  }
137
182
  // 显式参数优先于 config 值
138
- host = host || hostConfig.hostName || hostConfig.host;
139
- user = user || hostConfig.user;
140
- port = port || hostConfig.port;
141
- keyPath = keyPath || hostConfig.identityFile;
183
+ host = host ?? hostConfig.hostName ?? hostConfig.host;
184
+ user = user ?? hostConfig.user;
185
+ port = port ?? hostConfig.port;
186
+ keyPath = keyPath ?? hostConfig.identityFile;
142
187
  // 解析 ProxyJump(支持 user@host:port 格式)
143
188
  if (hostConfig.proxyJump) {
144
189
  const parsed = parseProxyJump(hostConfig.proxyJump);
@@ -157,7 +202,7 @@ async function handleConnect(args) {
157
202
  }
158
203
  jumpHostResolved = {
159
204
  host: jumpHostConfig.hostName || jumpHostConfig.host,
160
- port: parsed.port || jumpHostConfig.port || 22,
205
+ port: parsed.port ?? jumpHostConfig.port ?? 22,
161
206
  username: jumpUser,
162
207
  privateKeyPath: jumpHostConfig.identityFile,
163
208
  };
@@ -173,7 +218,7 @@ async function handleConnect(args) {
173
218
  }
174
219
  jumpHostResolved = {
175
220
  host: parsed.host,
176
- port: parsed.port || 22,
221
+ port: parsed.port ?? 22,
177
222
  username: parsed.user,
178
223
  };
179
224
  }
@@ -187,18 +232,19 @@ async function handleConnect(args) {
187
232
  });
188
233
  }
189
234
  // 手动指定的 jumpHost 优先级高于 ProxyJump
190
- const jumpHost = args.jumpHost
235
+ const requestedJumpHost = args.jumpHost ?? template.jumpHost;
236
+ const jumpHost = requestedJumpHost
191
237
  ? {
192
- host: args.jumpHost.host,
193
- port: args.jumpHost.port || 22,
194
- username: args.jumpHost.user,
195
- password: args.jumpHost.password,
196
- privateKeyPath: args.jumpHost.keyPath,
197
- readyTimeout: args.jumpHost.readyTimeout ?? readyTimeout,
238
+ host: requestedJumpHost.host,
239
+ port: requestedJumpHost.port ?? 22,
240
+ username: requestedJumpHost.user,
241
+ password: requestedJumpHost.password,
242
+ privateKeyPath: requestedJumpHost.keyPath,
243
+ readyTimeout: requestedJumpHost.readyTimeout ?? readyTimeout,
198
244
  }
199
245
  : jumpHostResolved;
200
- const finalPort = port || 22;
201
- const finalAlias = requestedAlias || `${user}@${host}:${finalPort}`;
246
+ const finalPort = port ?? 22;
247
+ const finalAlias = requestedAlias ?? `${user}@${host}:${finalPort}`;
202
248
  const identity = `${user}@${host}:${finalPort}`;
203
249
  const sessionsBeforeConnect = sessionManager.listSessionDetails();
204
250
  const reused = sessionsBeforeConnect.some((session) => session.alias === finalAlias && session.connected);
@@ -211,7 +257,7 @@ async function handleConnect(args) {
211
257
  username: user,
212
258
  password,
213
259
  privateKeyPath: keyPath,
214
- alias: requestedAlias,
260
+ alias: finalAlias,
215
261
  template: args.template,
216
262
  runAs,
217
263
  defaultEnv,
@@ -220,22 +266,23 @@ async function handleConnect(args) {
220
266
  readyTimeout,
221
267
  jumpHost,
222
268
  });
269
+ const connected = sessionManager.getSessionConnectionInfo(alias);
223
270
  return formatResult({
224
271
  success: true,
225
- alias,
272
+ alias: connected.alias,
226
273
  reused,
227
- identity,
228
- loginUser: user,
229
- runAs,
230
- host,
231
- port: finalPort,
232
- defaultEnvKeys: defaultEnv ? Object.keys(defaultEnv) : [],
233
- envKeys: env ? Object.keys(env) : [],
274
+ identity: connected.identity,
275
+ loginUser: connected.loginUser,
276
+ runAs: connected.runAs,
277
+ host: connected.host,
278
+ port: connected.port,
279
+ defaultEnvKeys: connected.defaultEnvKeys,
280
+ envKeys: connected.envKeys,
234
281
  reusableSessions,
235
282
  suggestion: reusableSessions.length > 0
236
283
  ? '已有同 identity 的连接,可直接复用 reusableSessions 中的 alias'
237
284
  : undefined,
238
- message: `Connected to ${identity}${jumpHost ? ' via jump host' : ''}`,
285
+ message: `Connected to ${connected.identity}${connected.hasJumpHost ? ' via jump host' : ''}`,
239
286
  });
240
287
  }
241
288
  catch (error) {
@@ -309,7 +356,7 @@ export function registerConnectionTools(server) {
309
356
  description: [
310
357
  '建立 SSH 连接并保持会话,支持密码、密钥认证,支持跳板机',
311
358
  '',
312
- '可通过 configHost 参数使用 ~/.ssh/config 中的配置,无需重复填写连接信息',
359
+ '可通过 configHost 参数使用 ~/.ssh/config 中的配置,无需重复填写连接信息;模板会在连接前校验端口和嵌套 jumpHost 字段',
313
360
  '支持 Host 多别名、Host * 全局默认继承、ProxyJump(user@host:port 格式)',
314
361
  '',
315
362
  '示例',
@@ -4,11 +4,13 @@
4
4
  * ssh_exec, ssh_exec_as_user, ssh_exec_sudo,
5
5
  * ssh_exec_batch, ssh_quick_exec, ssh_exec_parallel
6
6
  */
7
+ import { randomUUID } from 'crypto';
7
8
  import { z } from 'zod';
8
9
  import { classifyCommandRisk } from '../command-risk.js';
9
10
  import * as fileOps from '../file-ops.js';
10
11
  import { sessionManager } from '../session-manager.js';
11
12
  import { HARD_EXEC_MAX_OUTPUT_SIZE } from '../types.js';
13
+ import { sshPortSchema } from './schema.js';
12
14
  import { escapeShellArg, formatError, formatResult } from './utils.js'; // ========== Schemas ==========
13
15
  // ========== Schemas ==========
14
16
  const maxOutputSizeSchema = z
@@ -52,6 +54,9 @@ const execSudoSchema = z.object({
52
54
  sudoPassword: z.string().optional().describe('sudo 密码(如果需要)'),
53
55
  timeout: z.number().optional().describe('超时(毫秒)'),
54
56
  maxOutputSize: maxOutputSizeSchema,
57
+ runAs: z.string().optional().describe('本次命令使用的目标用户,覆盖连接级 runAs'),
58
+ useLoginUser: z.boolean().optional().describe('设为 true 时跳过连接级 runAs,直接以登录用户执行'),
59
+ loadProfile: z.boolean().optional().describe('runAs 执行时是否加载目标用户 shell 配置,默认 true'),
55
60
  });
56
61
  const execBatchSchema = z.object({
57
62
  alias: z.string().describe('连接别名'),
@@ -65,8 +70,9 @@ const quickExecSchema = z.object({
65
70
  command: z.string().describe('要执行的命令'),
66
71
  password: z.string().optional().describe('密码'),
67
72
  keyPath: z.string().optional().describe('密钥路径'),
68
- port: z.number().optional().describe('端口'),
69
- timeout: z.number().optional().describe('超时(毫秒)'),
73
+ port: sshPortSchema.optional().describe('SSH 端口,默认 22'),
74
+ readyTimeout: z.number().int().positive().max(600000).optional().describe('等待 SSH ready 的超时,默认 30000'),
75
+ timeout: z.number().optional().describe('命令执行超时(毫秒),默认 30000'),
70
76
  });
71
77
  const EXEC_PARALLEL_MAX_ALIASES = 32;
72
78
  const EXEC_PARALLEL_DEFAULT_CONCURRENCY = 4;
@@ -145,6 +151,9 @@ async function handleExecSudo(args) {
145
151
  const result = await sessionManager.execSudo(args.alias, args.command, args.sudoPassword, {
146
152
  timeout: args.timeout,
147
153
  maxOutputSize: args.maxOutputSize,
154
+ runAs: args.runAs,
155
+ useLoginUser: args.useLoginUser,
156
+ loadProfile: args.loadProfile,
148
157
  });
149
158
  return formatResult(result);
150
159
  }
@@ -195,15 +204,16 @@ async function handleExecBatch(args) {
195
204
  }
196
205
  }
197
206
  async function handleQuickExec(args) {
198
- const tempAlias = `_quick_${Date.now()}`;
207
+ const tempAlias = `_quick_${randomUUID()}`;
199
208
  try {
200
209
  await sessionManager.connect({
201
210
  host: args.host,
202
- port: args.port || 22,
211
+ port: args.port ?? 22,
203
212
  username: args.user,
204
213
  password: args.password,
205
214
  privateKeyPath: args.keyPath,
206
215
  alias: tempAlias,
216
+ readyTimeout: args.readyTimeout,
207
217
  });
208
218
  const result = await sessionManager.exec(tempAlias, args.command, { timeout: args.timeout });
209
219
  return formatResult(result);
@@ -369,7 +379,7 @@ export function registerExecTools(server) {
369
379
  inputSchema: execAsUserSchema,
370
380
  }, (args) => handleExecAsUser(args));
371
381
  server.registerTool('ssh_exec_sudo', {
372
- description: '使用 sudo 执行命令',
382
+ description: '使用 sudo 执行命令。runAs、useLoginUser 与 loadProfile 的身份优先级与 ssh_exec 相同。',
373
383
  inputSchema: execSudoSchema,
374
384
  }, (args) => handleExecSudo(args));
375
385
  server.registerTool('ssh_exec_batch', {
@@ -379,7 +389,7 @@ export function registerExecTools(server) {
379
389
  inputSchema: execBatchSchema,
380
390
  }, (args) => handleExecBatch(args));
381
391
  server.registerTool('ssh_quick_exec', {
382
- description: '一次性执行命令(自动连接、执行、断开),适用于单次命令,不需要保持连接',
392
+ description: '一次性执行命令(自动连接、执行、断开)。readyTimeout 只限制建立 SSH 连接,timeout 只限制命令执行,适用于单次命令。',
383
393
  inputSchema: quickExecSchema,
384
394
  }, (args) => handleQuickExec(args));
385
395
  server.registerTool('ssh_exec_parallel', {
@@ -5,4 +5,5 @@
5
5
  * ssh_list_dir, ssh_file_info, ssh_mkdir, ssh_sync
6
6
  */
7
7
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
8
+ export declare function createAtomicUploadPath(remotePath: string): string;
8
9
  export declare function registerFileTools(server: McpServer): void;