@pyrokine/mcp-ssh 2.4.0 → 2.4.1

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.
@@ -4,7 +4,7 @@
4
4
  * ssh_upload, ssh_download, ssh_read_file, ssh_write_file,
5
5
  * ssh_list_dir, ssh_file_info, ssh_mkdir, ssh_sync
6
6
  */
7
- import { createHash } from 'crypto';
7
+ import { createHash, randomBytes } from 'crypto';
8
8
  import * as fs from 'fs';
9
9
  import * as path from 'path';
10
10
  import { z } from 'zod';
@@ -181,23 +181,16 @@ function uploadPathError(code, message, diagnostics) {
181
181
  }
182
182
  async function probeRemoteParent(alias, remotePath) {
183
183
  const parent = path.posix.dirname(remotePath);
184
- const escapedParent = escapeShellArg(parent);
185
- const command = [
186
- `if [ -d ${escapedParent} ]; then`,
187
- `if [ -w ${escapedParent} ]; then printf writable; else printf not-writable; fi;`,
188
- 'else printf missing; fi',
189
- ].join(' ');
190
184
  try {
191
- const result = await sessionManager.exec(alias, command, {
192
- timeout: 10000,
193
- useLoginUser: true,
194
- maxOutputSize: 4096,
195
- });
196
- const status = result.stdout.trim();
197
- return { exists: status !== 'missing', writable: status === 'writable' };
185
+ const result = await probeRemoteFile(alias, parent);
186
+ return {
187
+ exists: result.exists,
188
+ isDirectory: result.exists ? result.isDirectory : false,
189
+ probeMethod: 'sftp',
190
+ };
198
191
  }
199
192
  catch (error) {
200
- return { error: error instanceof Error ? error.message : String(error) };
193
+ return { error: error instanceof Error ? error.message : String(error), probeMethod: 'sftp' };
201
194
  }
202
195
  }
203
196
  function hashLocalFileMd5(filePath) {
@@ -236,26 +229,32 @@ function commandFailureDetails(result) {
236
229
  };
237
230
  }
238
231
  async function hashRemoteFileMd5(alias, remotePath) {
239
- const result = await sessionManager.exec(alias, `md5sum ${escapeShellArg(remotePath)} | awk '{print $1}'`, {
240
- timeout: 30000,
232
+ try {
233
+ return await fileOps.hashRemoteFileDigest(alias, remotePath, 'md5');
234
+ }
235
+ catch (error) {
236
+ throw new VerificationStageError('remote_probe', `Remote SFTP MD5 read failed: ${error instanceof Error ? error.message : String(error)}`, true, { operation: 'md5', probeMethod: 'sftp' });
237
+ }
238
+ }
239
+ async function resolveExpectedOwnerId(alias, owner) {
240
+ const ownerText = String(owner);
241
+ if (/^\d+$/.test(ownerText)) {
242
+ return ownerText;
243
+ }
244
+ const result = await sessionManager.exec(alias, `id -u ${escapeShellArg(ownerText)}`, {
245
+ timeout: 10000,
241
246
  useLoginUser: true,
242
247
  maxOutputSize: 4096,
243
248
  });
244
- if (!result.success) {
249
+ const ownerId = result.stdout.trim();
250
+ if (!result.success || !/^\d+$/.test(ownerId)) {
245
251
  const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
246
- throw new VerificationStageError('remote_probe', `Remote MD5 command failed: ${detail}`, true, {
247
- operation: 'md5',
248
- ...commandFailureDetails(result),
249
- });
250
- }
251
- const digest = result.stdout.trim().split(/\s+/)[0];
252
- if (!/^[a-fA-F0-9]{32}$/.test(digest)) {
253
- throw new VerificationStageError('remote_probe', 'Remote MD5 command returned an invalid digest', false, {
254
- operation: 'md5',
252
+ throw new VerificationStageError('remote_probe', `Remote owner lookup failed: ${detail}`, true, {
253
+ operation: 'owner_lookup',
255
254
  ...commandFailureDetails(result),
256
255
  });
257
256
  }
258
- return digest;
257
+ return ownerId;
259
258
  }
260
259
  function permissionStringToOctal(permissions) {
261
260
  const bits = permissions.slice(-9);
@@ -277,71 +276,58 @@ function permissionStringToOctal(permissions) {
277
276
  });
278
277
  return `0${values.join('')}`;
279
278
  }
280
- async function probeRemoteFile(alias, remotePath, timeout = 10000) {
281
- const escapedRemotePath = escapeShellArg(remotePath);
282
- const command = [
283
- `if [ -e ${escapedRemotePath} ]; then`,
284
- `stat -c '%U\t%u\t%G\t%g\t%a\t%s\t%Y\t%F' ${escapedRemotePath};`,
285
- 'else printf missing; fi',
286
- ].join(' ');
287
- const result = await sessionManager.exec(alias, command, {
288
- timeout,
289
- useLoginUser: true,
290
- maxOutputSize: 4096,
291
- });
292
- if (!result.success) {
293
- const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
294
- throw new VerificationStageError('remote_probe', `Remote stat command failed: ${detail}`, true, {
295
- operation: 'stat',
296
- ...commandFailureDetails(result),
297
- });
298
- }
299
- if (result.stdout.trim() === 'missing') {
300
- return { exists: false, remotePath, probeMethod: 'stat' };
279
+ function isRemoteMissingError(error) {
280
+ if (!error || typeof error !== 'object') {
281
+ return false;
301
282
  }
302
- const fields = result.stdout.trim().split('\t');
303
- if (fields.length !== 8) {
304
- throw new VerificationStageError('remote_probe', 'Remote stat command returned malformed output', false, {
305
- operation: 'stat',
306
- ...commandFailureDetails(result),
307
- });
283
+ const code = 'code' in error ? error.code : undefined;
284
+ const message = error instanceof Error ? error.message : String(error);
285
+ return code === 2 || code === 'ENOENT' || /no such file|not found/i.test(message);
286
+ }
287
+ async function probeRemoteFile(alias, remotePath, _timeout = 10000) {
288
+ try {
289
+ const info = await fileOps.getFileInfo(alias, remotePath);
290
+ const mode = permissionStringToOctal(info.permissions);
291
+ if (!mode) {
292
+ throw new VerificationStageError('remote_probe', 'Remote SFTP stat returned invalid mode metadata', false, {
293
+ operation: 'stat',
294
+ probeMethod: 'sftp',
295
+ });
296
+ }
297
+ return {
298
+ exists: true,
299
+ remotePath,
300
+ probeMethod: 'sftp',
301
+ ownerName: undefined,
302
+ ownerId: info.owner,
303
+ groupName: undefined,
304
+ groupId: info.group,
305
+ mode,
306
+ size: info.size,
307
+ mtimeMs: info.mtime.getTime(),
308
+ fileType: info.isDirectory
309
+ ? 'directory'
310
+ : info.isFile
311
+ ? 'regular file'
312
+ : info.isSymlink
313
+ ? 'symbolic link'
314
+ : 'other',
315
+ isDirectory: info.isDirectory,
316
+ isFile: info.isFile,
317
+ };
308
318
  }
309
- const [ownerName, ownerId, groupName, groupId, mode, size, mtimeSeconds, fileType] = fields;
310
- const ownerIdValue = Number(ownerId);
311
- const groupIdValue = Number(groupId);
312
- const sizeValue = Number(size);
313
- const mtimeValue = Number(mtimeSeconds);
314
- if (!Number.isSafeInteger(ownerIdValue) ||
315
- ownerIdValue < 0 ||
316
- !Number.isSafeInteger(groupIdValue) ||
317
- groupIdValue < 0 ||
318
- !Number.isSafeInteger(sizeValue) ||
319
- sizeValue < 0 ||
320
- !Number.isFinite(mtimeValue) ||
321
- !/^[0-7]{3,4}$/.test(mode)) {
322
- throw new VerificationStageError('remote_probe', 'Remote stat command returned invalid metadata', false, {
323
- operation: 'stat',
324
- ...commandFailureDetails(result),
325
- });
319
+ catch (error) {
320
+ if (isRemoteMissingError(error)) {
321
+ return { exists: false, remotePath, probeMethod: 'sftp' };
322
+ }
323
+ if (error instanceof VerificationStageError) {
324
+ throw error;
325
+ }
326
+ throw new VerificationStageError('remote_probe', `Remote SFTP stat failed: ${error instanceof Error ? error.message : String(error)}`, true, { operation: 'stat', probeMethod: 'sftp' });
326
327
  }
327
- return {
328
- exists: true,
329
- remotePath,
330
- probeMethod: 'stat',
331
- ownerName,
332
- ownerId: ownerIdValue,
333
- groupName,
334
- groupId: groupIdValue,
335
- mode: mode.length === 3 ? `0${mode}` : mode,
336
- size: sizeValue,
337
- mtimeMs: mtimeValue * 1000,
338
- fileType,
339
- isDirectory: fileType === 'directory',
340
- isFile: fileType.startsWith('regular '),
341
- };
342
328
  }
343
- async function buildUploadVerification(args, local) {
344
- const remote = await probeRemoteFile(args.alias, args.remotePath);
329
+ async function buildUploadVerification(args, local, verificationRemotePath = args.remotePath) {
330
+ const remote = await probeRemoteFile(args.alias, verificationRemotePath);
345
331
  const checks = {};
346
332
  if (args.verifySize) {
347
333
  checks.size = local.exists && remote.exists ? local.size === remote.size : false;
@@ -355,13 +341,13 @@ async function buildUploadVerification(args, local) {
355
341
  checks.mode = remote.exists && expectedMode !== undefined && remote.mode === expectedMode;
356
342
  }
357
343
  if (args.verifyOwner !== undefined) {
358
- const expectedOwner = String(args.verifyOwner);
359
- checks.owner = remote.exists && (String(remote.ownerId) === expectedOwner || remote.ownerName === expectedOwner);
344
+ const expectedOwnerId = await resolveExpectedOwnerId(args.alias, args.verifyOwner);
345
+ checks.owner = remote.exists && String(remote.ownerId) === expectedOwnerId;
360
346
  }
361
347
  if (args.verifyMd5 && local.exists) {
362
348
  const [localMd5, remoteMd5] = await Promise.all([
363
349
  hashLocalFileMd5(local.resolvedPath),
364
- hashRemoteFileMd5(args.alias, args.remotePath),
350
+ hashRemoteFileMd5(args.alias, verificationRemotePath),
365
351
  ]);
366
352
  checks.md5 = remoteMd5 ? localMd5 === remoteMd5 : undefined;
367
353
  return {
@@ -398,11 +384,11 @@ function normalizeExpectedMode(mode) {
398
384
  }
399
385
  return permissionStringToOctal(trimmed);
400
386
  }
401
- function buildSyncVerificationChecks(args, remote) {
387
+ async function buildSyncVerificationChecks(args, remote) {
402
388
  const checks = {};
403
389
  if (args.verifyOwner !== undefined) {
404
- const expectedOwner = String(args.verifyOwner);
405
- checks.owner = remote.exists && (String(remote.ownerId) === expectedOwner || remote.ownerName === expectedOwner);
390
+ const expectedOwnerId = await resolveExpectedOwnerId(args.alias, args.verifyOwner);
391
+ checks.owner = remote.exists && String(remote.ownerId) === expectedOwnerId;
406
392
  }
407
393
  if (args.verifyMode !== undefined) {
408
394
  const expectedMode = normalizeExpectedMode(args.verifyMode);
@@ -444,7 +430,7 @@ async function buildSyncUploadVerification(args, local, timeout) {
444
430
  }
445
431
  const verificationRemotePath = await resolveSyncUploadVerificationPath(args, local, timeout);
446
432
  const remote = await probeRemoteFile(args.alias, verificationRemotePath, timeout);
447
- const checks = buildSyncVerificationChecks(args, remote);
433
+ const checks = await buildSyncVerificationChecks(args, remote);
448
434
  const matched = Object.values(checks).every(Boolean);
449
435
  return {
450
436
  kind: 'owner_mode',
@@ -588,22 +574,52 @@ function mergeSyncVerification(existing, ownerMode, directory) {
588
574
  };
589
575
  }
590
576
  async function cleanupRemotePath(alias, remotePath) {
591
- const result = await sessionManager.exec(alias, `rm -f ${escapeShellArg(remotePath)}`, {
592
- timeout: 10000,
593
- useLoginUser: true,
594
- maxOutputSize: 4096,
595
- });
596
- if (!result.success) {
597
- const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
598
- throw new Error(`Temporary remote file cleanup failed: ${detail}`);
577
+ try {
578
+ await fileOps.removeRemoteFile(alias, remotePath);
599
579
  }
580
+ catch (error) {
581
+ throw new Error(`Temporary remote file cleanup failed: ${error instanceof Error ? error.message : String(error)}`, {
582
+ cause: error,
583
+ });
584
+ }
585
+ }
586
+ export function createAtomicUploadPath(remotePath) {
587
+ return `${remotePath}.mcp-tmp-${process.pid}-${randomBytes(12).toString('hex')}`;
588
+ }
589
+ function uploadPathDetails(args, verificationRemotePath, verification) {
590
+ return {
591
+ finalRemotePath: args.remotePath,
592
+ verifiedRemotePath: verification ? verificationRemotePath : undefined,
593
+ verifiedTempRemotePath: verification && args.atomic ? verificationRemotePath : undefined,
594
+ };
595
+ }
596
+ function addUploadVerificationPaths(verification, args, verificationRemotePath) {
597
+ if (!verification) {
598
+ return undefined;
599
+ }
600
+ return {
601
+ ...verification,
602
+ ...uploadPathDetails(args, verificationRemotePath, verification),
603
+ };
600
604
  }
601
605
  async function handleUpload(args) {
602
- const local = fileOps.probeLocalPath(args.localPath);
603
- if (local.exists && local.isDirectory) {
604
- return uploadPathError('UPLOAD_PATH_IS_DIRECTORY', 'localPath is a directory', {
605
- local: summarizeLocalPathProbe(local),
606
- suggestion: '使用 ssh_sync 上传目录,或把 localPath 指向具体文件',
606
+ let local;
607
+ try {
608
+ fileOps.validateUploadFileSource(args.localPath);
609
+ local = fileOps.probeLocalPath(args.localPath);
610
+ }
611
+ catch (error) {
612
+ local = fileOps.probeLocalPath(args.localPath);
613
+ if (local.exists && local.isDirectory) {
614
+ return uploadPathError('UPLOAD_PATH_IS_DIRECTORY', 'localPath is a directory', {
615
+ local: summarizeLocalPathProbe(local),
616
+ suggestion: '使用 ssh_sync 上传目录,或把 localPath 指向具体文件',
617
+ });
618
+ }
619
+ return formatResult({
620
+ success: false,
621
+ error: error instanceof Error ? error.message : String(error),
622
+ diagnostics: { local: summarizeLocalPathProbe(local) },
607
623
  });
608
624
  }
609
625
  const largeFileSuggestion = local.exists && typeof local.size === 'number' && local.size >= LARGE_UPLOAD_THRESHOLD
@@ -639,52 +655,97 @@ async function handleUpload(args) {
639
655
  : undefined;
640
656
  const existingMode = remoteBefore.exists && remoteBefore.mode ? Number.parseInt(remoteBefore.mode, 8) & 0o777 : undefined;
641
657
  const createMode = args.atomic && existingMode !== undefined ? existingMode : sourceMode;
642
- const tempRemotePath = args.atomic
643
- ? `${args.remotePath}.mcp-tmp-${process.pid}-${Date.now().toString(36)}`
644
- : args.remotePath;
658
+ const tempRemotePath = args.atomic ? createAtomicUploadPath(args.remotePath) : args.remotePath;
659
+ const verificationRequested = Boolean(args.verifyOwner !== undefined ||
660
+ args.verifyMode !== undefined ||
661
+ args.verifyMd5 ||
662
+ args.verifySize ||
663
+ args.verifyMtime);
645
664
  try {
646
- const uploadResult = await fileOps.uploadFile(args.alias, args.localPath, tempRemotePath, undefined, undefined, createMode);
665
+ const uploadResult = await fileOps.uploadFile(args.alias, args.localPath, tempRemotePath, undefined, undefined, createMode, undefined, false, args.atomic === true);
666
+ let verification;
667
+ let verificationError;
668
+ if (verificationRequested) {
669
+ try {
670
+ verification = await buildUploadVerification(args, local, tempRemotePath);
671
+ }
672
+ catch (error) {
673
+ verificationError = error;
674
+ verification = verificationErrorDetails(error);
675
+ }
676
+ }
677
+ verification = addUploadVerificationPaths(verification, args, tempRemotePath);
678
+ const outcome = buildTransferOutcome(uploadResult.success, verificationRequested, verification, verificationError);
679
+ const pathDetails = uploadPathDetails(args, tempRemotePath, verification);
680
+ if (args.atomic && !outcome.success) {
681
+ let cleanupWarning;
682
+ try {
683
+ await cleanupRemotePath(args.alias, tempRemotePath);
684
+ }
685
+ catch (cleanupError) {
686
+ cleanupWarning = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
687
+ }
688
+ return formatResult({
689
+ ...uploadResult,
690
+ ...outcome,
691
+ message: `Atomic upload verification failed; existing target preserved: ${args.remotePath}`,
692
+ error: verificationError === undefined
693
+ ? `Atomic upload verification failed: ${args.remotePath}`
694
+ : `Atomic upload verification failed: ${verificationError instanceof Error ? verificationError.message : String(verificationError)}`,
695
+ cleanupWarning,
696
+ atomic: true,
697
+ targetReplaced: false,
698
+ ...pathDetails,
699
+ createMode: uploadResult.createMode,
700
+ existingTargetModePreserved: remoteBefore.exists,
701
+ suggestion: largeFileSuggestion,
702
+ recommendedSync,
703
+ diagnostics: {
704
+ local: summarizeLocalPathProbe(local),
705
+ remoteParent,
706
+ atomic: true,
707
+ tempRemotePath,
708
+ },
709
+ verification,
710
+ });
711
+ }
647
712
  if (args.atomic) {
648
- const rename = await sessionManager.exec(args.alias, `mv -f -- ${escapeShellArg(tempRemotePath)} ${escapeShellArg(args.remotePath)}`, { timeout: 30000, useLoginUser: true, maxOutputSize: 4096 });
649
- if (!rename.success) {
650
- const renameError = rename.stderr || rename.stdout || `atomic rename failed with exit code ${rename.exitCode}`;
713
+ try {
714
+ await fileOps.renameRemoteFile(args.alias, tempRemotePath, args.remotePath, remoteBefore.exists);
715
+ }
716
+ catch (error) {
717
+ const renameNotStarted = error instanceof fileOps.RemoteRenameNotStartedError;
718
+ const renameError = error instanceof Error ? error.message : String(error);
651
719
  let cleanupWarning;
652
720
  try {
653
721
  await cleanupRemotePath(args.alias, tempRemotePath);
654
722
  }
655
- catch (error) {
656
- cleanupWarning = error instanceof Error ? error.message : String(error);
723
+ catch (cleanupError) {
724
+ cleanupWarning = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
657
725
  }
658
726
  return formatResult({
659
727
  success: false,
660
- error: renameError,
728
+ transferSuccess: true,
729
+ operationStatus: renameNotStarted ? 'failed' : 'unknown',
730
+ retryable: true,
731
+ error: renameNotStarted
732
+ ? `Atomic SFTP rename request was not sent; target was not replaced: ${renameError}`
733
+ : `Atomic SFTP rename response failed; target replacement state is unknown: ${renameError}`,
661
734
  cleanupWarning,
735
+ atomic: true,
736
+ targetReplaced: renameNotStarted ? false : null,
737
+ targetReplacementStatus: renameNotStarted ? 'not_replaced' : 'unknown',
738
+ ...pathDetails,
662
739
  diagnostics: {
663
740
  local: summarizeLocalPathProbe(local),
664
741
  remoteParent,
665
742
  atomic: true,
666
743
  tempRemotePath,
667
744
  },
745
+ verification,
668
746
  });
669
747
  }
670
748
  }
671
- const verificationRequested = Boolean(args.verifyOwner !== undefined ||
672
- args.verifyMode !== undefined ||
673
- args.verifyMd5 ||
674
- args.verifySize ||
675
- args.verifyMtime);
676
- let verification;
677
- let verificationError;
678
- if (verificationRequested) {
679
- try {
680
- verification = await buildUploadVerification(args, local);
681
- }
682
- catch (error) {
683
- verificationError = error;
684
- verification = verificationErrorDetails(error);
685
- }
686
- }
687
- const outcome = buildTransferOutcome(uploadResult.success, verificationRequested, verification, verificationError);
688
749
  return formatResult({
689
750
  ...uploadResult,
690
751
  ...outcome,
@@ -695,6 +756,8 @@ async function handleUpload(args) {
695
756
  ? undefined
696
757
  : `Upload completed, but verification failed: ${verificationError instanceof Error ? verificationError.message : String(verificationError)}`,
697
758
  atomic: args.atomic === true,
759
+ targetReplaced: args.atomic ? true : undefined,
760
+ ...pathDetails,
698
761
  createMode: uploadResult.createMode,
699
762
  existingTargetModePreserved: remoteBefore.exists,
700
763
  suggestion: largeFileSuggestion,
@@ -710,7 +773,8 @@ async function handleUpload(args) {
710
773
  }
711
774
  catch (error) {
712
775
  let cleanupWarning;
713
- if (args.atomic) {
776
+ const shouldCleanupTemporaryUpload = args.atomic && (!(error instanceof fileOps.UploadFileError) || error.remoteCreated);
777
+ if (shouldCleanupTemporaryUpload) {
714
778
  try {
715
779
  await cleanupRemotePath(args.alias, tempRemotePath);
716
780
  }
@@ -722,6 +786,7 @@ async function handleUpload(args) {
722
786
  success: false,
723
787
  error: error instanceof Error ? error.message : String(error),
724
788
  cleanupWarning,
789
+ finalRemotePath: args.remotePath,
725
790
  diagnostics: {
726
791
  local: summarizeLocalPathProbe(local),
727
792
  remoteParent,
@@ -815,6 +880,23 @@ async function handleSync(args) {
815
880
  }
816
881
  const operationTimeout = args.operationTimeout ?? 600_000;
817
882
  const remainingTimeout = () => operationTimeout - (Date.now() - startedAt);
883
+ try {
884
+ if (args.direction === 'upload') {
885
+ fileOps.validateSyncUploadSource(args.localPath, args.followSymlinks === true, args.exclude);
886
+ }
887
+ else {
888
+ fileOps.validateLocalPathPolicy(args.localPath);
889
+ }
890
+ }
891
+ catch (error) {
892
+ return formatResult({
893
+ success: false,
894
+ error: error instanceof Error ? error.message : String(error),
895
+ diagnostics: {
896
+ localBefore: summarizeLocalPathProbe(fileOps.probeLocalPath(args.localPath, args.direction === 'upload' && args.followSymlinks === true)),
897
+ },
898
+ });
899
+ }
818
900
  const localBefore = fileOps.probeLocalPath(args.localPath, args.direction === 'upload' && args.followSymlinks === true);
819
901
  const diagnostics = {
820
902
  localBefore: summarizeLocalPathProbe(localBefore),
@@ -23,7 +23,7 @@ const forwardLocalSchema = z.object({
23
23
  });
24
24
  const forwardRemoteSchema = z.object({
25
25
  alias: z.string().describe('连接别名'),
26
- remotePort: z.number().describe('远程监听端口'),
26
+ remotePort: z.number().int().min(0).max(65535).describe('远程监听端口,传 0 时由服务器动态分配'),
27
27
  localHost: z.string().describe('本地目标地址'),
28
28
  localPort: z.number().describe('本地目标端口'),
29
29
  remoteHost: loopbackHostSchema.describe('远程监听地址,仅允许 loopback(127.0.0.1 / ::1 / localhost),默认 127.0.0.1'),
@@ -52,12 +52,13 @@ async function handleForwardLocal(args) {
52
52
  }
53
53
  async function handleForwardRemote(args) {
54
54
  try {
55
- const forwardId = await sessionManager.forwardRemote(args.alias, args.remotePort, args.localHost, args.localPort, args.remoteHost);
55
+ const { forwardId, remotePort } = await sessionManager.forwardRemote(args.alias, args.remotePort, args.localHost, args.localPort, args.remoteHost);
56
56
  return formatResult({
57
57
  success: true,
58
58
  forwardId,
59
59
  type: 'remote',
60
- message: `Remote forward: ${args.remoteHost}:${args.remotePort} -> ${args.localHost}:${args.localPort}`,
60
+ remotePort,
61
+ message: `Remote forward: ${args.remoteHost}:${remotePort} -> ${args.localHost}:${args.localPort}`,
61
62
  });
62
63
  }
63
64
  catch (error) {
@@ -111,7 +112,8 @@ export function registerForwardTools(server) {
111
112
 
112
113
  用途:将本地服务暴露到远程
113
114
  示例:ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
114
- 效果:远程访问 localhost:8080 会转发到本地的 127.0.0.1:3000`,
115
+ 效果:远程访问 localhost:8080 会转发到本地的 127.0.0.1:3000
116
+ 传 remotePort=0 时由服务器动态分配端口,返回结果中的 remotePort 是实际监听端口`,
115
117
  inputSchema: forwardRemoteSchema,
116
118
  }, (args) => handleForwardRemote(args));
117
119
  server.registerTool('ssh_forward_close', {
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { DEFAULT_OPERATION_MAX_OUTPUT_BYTES, DEFAULT_OPERATION_READ_BYTES, DEFAULT_OPERATION_RETENTION_MS, HARD_OPERATION_MAX_OUTPUT_BYTES, HARD_OPERATION_READ_BYTES, MAX_OPERATION_RETENTION_MS, } from '../operation-manager.js';
2
+ import { DEFAULT_OPERATION_MAX_OUTPUT_BYTES, DEFAULT_OPERATION_READ_BYTES, DEFAULT_OPERATION_RETENTION_MS, DEFAULT_OPERATION_START_TIMEOUT_MS, HARD_OPERATION_MAX_OUTPUT_BYTES, HARD_OPERATION_READ_BYTES, MAX_OPERATION_RETENTION_MS, MAX_OPERATION_START_TIMEOUT_MS, } from '../operation-manager.js';
3
3
  import { sessionManager } from '../session-manager.js';
4
4
  import { formatError, formatResult } from './utils.js';
5
5
  const operationStartSchema = z.object({
@@ -24,6 +24,13 @@ const operationStartSchema = z.object({
24
24
  .max(MAX_OPERATION_RETENTION_MS)
25
25
  .optional()
26
26
  .describe(`完成后的状态保留时间,默认 ${DEFAULT_OPERATION_RETENTION_MS}ms,最大 ${MAX_OPERATION_RETENTION_MS}ms`),
27
+ startTimeoutMs: z
28
+ .number()
29
+ .int()
30
+ .positive()
31
+ .max(MAX_OPERATION_START_TIMEOUT_MS)
32
+ .optional()
33
+ .describe(`等待 SSH operation channel 建立的超时,默认 ${DEFAULT_OPERATION_START_TIMEOUT_MS}ms,最大 ${MAX_OPERATION_START_TIMEOUT_MS}ms`),
27
34
  });
28
35
  const operationIdSchema = z.object({
29
36
  operationId: z.string().describe('tracked operation ID'),
@@ -52,6 +59,7 @@ async function handleOperationStart(args) {
52
59
  loadProfile: args.loadProfile,
53
60
  maxOutputBytes: args.maxOutputBytes,
54
61
  retentionMs: args.retentionMs,
62
+ startTimeoutMs: args.startTimeoutMs,
55
63
  });
56
64
  return formatResult({ success: true, ...operation });
57
65
  }
@@ -103,8 +111,8 @@ export function registerOperationTools(server) {
103
111
  server.registerTool('ssh_operation_start', {
104
112
  description: `启动可跟踪的长时间远端命令
105
113
 
106
- 返回不可预测的 operationId。输出保存在有硬上限的内存缓冲区中,完成后按 retentionMs 自动过期。
107
- 普通 ssh_exec 的同步和 timeout 行为不变。`,
114
+ 返回不可预测的 operationId。channel 建立受 startTimeoutMs 限制,等待期间 record 可通过 list 查询;超时 details 返回 operationId。
115
+ 输出保存在有硬上限的内存缓冲区中,完成后按 retentionMs 自动过期。普通 ssh_exec 的同步和 timeout 行为不变。`,
108
116
  inputSchema: operationStartSchema,
109
117
  }, (args) => handleOperationStart(args));
110
118
  server.registerTool('ssh_operation_status', {
package/dist/types.d.ts CHANGED
@@ -111,6 +111,7 @@ export interface OperationStartOptions {
111
111
  loadProfile?: boolean;
112
112
  maxOutputBytes?: number;
113
113
  retentionMs?: number;
114
+ startTimeoutMs?: number;
114
115
  }
115
116
  export interface OperationInfo {
116
117
  operationId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pyrokine/mcp-ssh",
3
- "version": "2.4.0",
3
+ "version": "2.4.1",
4
4
  "description": "A comprehensive SSH MCP Server for Claude Code",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",