@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.
@@ -5,6 +5,7 @@
5
5
  */
6
6
  import { z } from 'zod';
7
7
  import { sessionManager } from '../session-manager.js';
8
+ import { dynamicSshPortSchema, sshPortSchema } from './schema.js';
8
9
  import { formatError, formatResult } from './utils.js';
9
10
  // ========== Schemas ==========
10
11
  // 仅允许 loopback 地址监听,防止把端口暴露到外网
@@ -16,16 +17,16 @@ const loopbackHostSchema = z
16
17
  .default('127.0.0.1');
17
18
  const forwardLocalSchema = z.object({
18
19
  alias: z.string().describe('连接别名'),
19
- localPort: z.number().describe('本地监听端口'),
20
+ localPort: dynamicSshPortSchema.describe('本地监听端口,传 0 时由系统动态分配'),
20
21
  remoteHost: z.string().describe('远程目标主机'),
21
- remotePort: z.number().describe('远程目标端口'),
22
+ remotePort: sshPortSchema.describe('远程目标端口'),
22
23
  localHost: loopbackHostSchema.describe('本地监听地址,仅允许 loopback(127.0.0.1 / ::1 / localhost),默认 127.0.0.1'),
23
24
  });
24
25
  const forwardRemoteSchema = z.object({
25
26
  alias: z.string().describe('连接别名'),
26
- remotePort: z.number().describe('远程监听端口'),
27
+ remotePort: dynamicSshPortSchema.describe('远程监听端口,传 0 时由服务器动态分配'),
27
28
  localHost: z.string().describe('本地目标地址'),
28
- localPort: z.number().describe('本地目标端口'),
29
+ localPort: sshPortSchema.describe('本地目标端口'),
29
30
  remoteHost: loopbackHostSchema.describe('远程监听地址,仅允许 loopback(127.0.0.1 / ::1 / localhost),默认 127.0.0.1'),
30
31
  });
31
32
  const forwardCloseSchema = z.object({
@@ -52,12 +53,13 @@ async function handleForwardLocal(args) {
52
53
  }
53
54
  async function handleForwardRemote(args) {
54
55
  try {
55
- const forwardId = await sessionManager.forwardRemote(args.alias, args.remotePort, args.localHost, args.localPort, args.remoteHost);
56
+ const { forwardId, remotePort } = await sessionManager.forwardRemote(args.alias, args.remotePort, args.localHost, args.localPort, args.remoteHost);
56
57
  return formatResult({
57
58
  success: true,
58
59
  forwardId,
59
60
  type: 'remote',
60
- message: `Remote forward: ${args.remoteHost}:${args.remotePort} -> ${args.localHost}:${args.localPort}`,
61
+ remotePort,
62
+ message: `Remote forward: ${args.remoteHost}:${remotePort} -> ${args.localHost}:${args.localPort}`,
61
63
  });
62
64
  }
63
65
  catch (error) {
@@ -111,7 +113,8 @@ export function registerForwardTools(server) {
111
113
 
112
114
  用途:将本地服务暴露到远程
113
115
  示例:ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
114
- 效果:远程访问 localhost:8080 会转发到本地的 127.0.0.1:3000`,
116
+ 效果:远程访问 localhost:8080 会转发到本地的 127.0.0.1:3000
117
+ 传 remotePort=0 时由服务器动态分配端口,返回结果中的 remotePort 是实际监听端口`,
115
118
  inputSchema: forwardRemoteSchema,
116
119
  }, (args) => handleForwardRemote(args));
117
120
  server.registerTool('ssh_forward_close', {
@@ -122,7 +125,7 @@ export function registerForwardTools(server) {
122
125
  inputSchema: forwardCloseSchema,
123
126
  }, (args) => handleForwardClose(args));
124
127
  server.registerTool('ssh_forward_list', {
125
- description: '列出所有端口转发',
128
+ description: '列出所有端口转发,lifecycle 和 acceptingConnections 表示当前关闭与接流量状态。',
126
129
  inputSchema: forwardListSchema,
127
130
  }, () => handleForwardList());
128
131
  }
@@ -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,14 @@ 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,` +
34
+ `最大 ${MAX_OPERATION_START_TIMEOUT_MS}ms`),
27
35
  });
28
36
  const operationIdSchema = z.object({
29
37
  operationId: z.string().describe('tracked operation ID'),
@@ -52,6 +60,7 @@ async function handleOperationStart(args) {
52
60
  loadProfile: args.loadProfile,
53
61
  maxOutputBytes: args.maxOutputBytes,
54
62
  retentionMs: args.retentionMs,
63
+ startTimeoutMs: args.startTimeoutMs,
55
64
  });
56
65
  return formatResult({ success: true, ...operation });
57
66
  }
@@ -103,8 +112,8 @@ export function registerOperationTools(server) {
103
112
  server.registerTool('ssh_operation_start', {
104
113
  description: `启动可跟踪的长时间远端命令
105
114
 
106
- 返回不可预测的 operationId。输出保存在有硬上限的内存缓冲区中,完成后按 retentionMs 自动过期。
107
- 普通 ssh_exec 的同步和 timeout 行为不变。`,
115
+ 返回不可预测的 operationId。channel 建立受 startTimeoutMs 限制,等待期间 record 可通过 list 查询;超时 details 返回 operationId。
116
+ 输出保存在有硬上限的内存缓冲区中,完成后按 retentionMs 自动过期。普通 ssh_exec 的同步和 timeout 行为不变。`,
108
117
  inputSchema: operationStartSchema,
109
118
  }, (args) => handleOperationStart(args));
110
119
  server.registerTool('ssh_operation_status', {
package/dist/tools/pty.js CHANGED
@@ -11,8 +11,8 @@ import { formatError, formatResult } from './utils.js'; // ========== Schemas ==
11
11
  const ptyStartSchema = z.object({
12
12
  alias: z.string().describe('连接别名'),
13
13
  command: z.string().describe('要执行的命令'),
14
- rows: z.number().optional().describe('终端行数,默认 24'),
15
- cols: z.number().optional().describe('终端列数,默认 80'),
14
+ rows: z.number().int().positive().optional().describe('终端行数,默认 24'),
15
+ cols: z.number().int().positive().optional().describe('终端列数,默认 80'),
16
16
  term: z.string().optional().describe('终端类型,默认 xterm-256color'),
17
17
  cwd: z.string().optional().describe('工作目录'),
18
18
  env: z.record(z.string(), z.string()).optional().describe('环境变量'),
@@ -35,8 +35,8 @@ const ptyReadSchema = z.object({
35
35
  });
36
36
  const ptyResizeSchema = z.object({
37
37
  ptyId: z.string().describe('PTY 会话 ID'),
38
- rows: z.number().describe('新的行数'),
39
- cols: z.number().describe('新的列数'),
38
+ rows: z.number().int().positive().describe('新的行数'),
39
+ cols: z.number().int().positive().describe('新的列数'),
40
40
  });
41
41
  const ptyCloseSchema = z.object({
42
42
  ptyId: z.string().describe('PTY 会话 ID'),
@@ -65,8 +65,8 @@ async function handlePtyStart(args) {
65
65
  }
66
66
  async function handlePtyWrite(args) {
67
67
  try {
68
- const success = sessionManager.ptyWrite(args.ptyId, args.data);
69
- return formatResult({ success, ptyId: args.ptyId });
68
+ const result = sessionManager.ptyWrite(args.ptyId, args.data);
69
+ return formatResult({ success: result.accepted, ptyId: args.ptyId, ...result });
70
70
  }
71
71
  catch (error) {
72
72
  return formatError(error);
@@ -75,13 +75,13 @@ async function handlePtyWrite(args) {
75
75
  async function handlePtyRead(args) {
76
76
  try {
77
77
  const readResult = sessionManager.ptyRead(args.ptyId, {
78
- mode: args.mode || 'screen',
78
+ mode: args.mode ?? 'screen',
79
79
  clear: args.clear !== false,
80
80
  });
81
81
  return formatResult({
82
82
  success: true,
83
83
  ptyId: args.ptyId,
84
- mode: args.mode || 'screen',
84
+ mode: args.mode ?? 'screen',
85
85
  ...readResult,
86
86
  });
87
87
  }
@@ -100,10 +100,12 @@ async function handlePtyResize(args) {
100
100
  }
101
101
  async function handlePtyClose(args) {
102
102
  try {
103
- const success = sessionManager.ptyClose(args.ptyId);
103
+ const result = sessionManager.ptyClose(args.ptyId);
104
104
  return formatResult({
105
- success,
106
- message: success ? `PTY session closed: ${args.ptyId}` : `PTY session not found: ${args.ptyId}`,
105
+ ...result,
106
+ message: result.success
107
+ ? `PTY session closed: ${args.ptyId}`
108
+ : `PTY session close ${result.status}: ${args.ptyId}`,
107
109
  });
108
110
  }
109
111
  catch (error) {
@@ -151,7 +153,9 @@ export function registerPtyTools(server) {
151
153
 
152
154
  示例:
153
155
  - 发送命令: ssh_pty_write(ptyId="xxx", data="ls -la\\r")
154
- - 退出 top: ssh_pty_write(ptyId="xxx", data="q")`,
156
+ - 退出 top: ssh_pty_write(ptyId="xxx", data="q")
157
+
158
+ write 返回 accepted=true 表示数据已被本地 stream 接收。backpressured=true 仅表示缓冲区达到高水位,不表示数据丢失。`,
155
159
  inputSchema: ptyWriteSchema,
156
160
  }, (args) => handlePtyWrite(args));
157
161
  server.registerTool('ssh_pty_read', {
@@ -171,7 +175,7 @@ export function registerPtyTools(server) {
171
175
  inputSchema: ptyResizeSchema,
172
176
  }, (args) => handlePtyResize(args));
173
177
  server.registerTool('ssh_pty_close', {
174
- description: '关闭 PTY 会话',
178
+ description: '关闭 PTY 会话,返回 closed、not_found、failed 或 unknown。可重试失败会保留会话供同一 ptyId 重试。',
175
179
  inputSchema: ptyCloseSchema,
176
180
  }, (args) => handlePtyClose(args));
177
181
  server.registerTool('ssh_pty_list', {
@@ -0,0 +1,4 @@
1
+ import { z } from 'zod';
2
+ export declare const sshPortSchema: z.ZodNumber;
3
+ export declare const dynamicSshPortSchema: z.ZodNumber;
4
+ export declare const operationTimeoutSchema: z.ZodNumber;
@@ -0,0 +1,9 @@
1
+ import { z } from 'zod';
2
+ export const sshPortSchema = z.number().int().min(1).max(65535);
3
+ export const dynamicSshPortSchema = z.number().int().min(0).max(65535);
4
+ export const operationTimeoutSchema = z
5
+ .number()
6
+ .int()
7
+ .positive()
8
+ .max(3_600_000)
9
+ .describe('操作超时(毫秒),默认 600000,超时后远端状态可能未知');
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;
@@ -201,7 +202,20 @@ export interface PtySessionInfo {
201
202
  foregroundProcess: string;
202
203
  active: boolean;
203
204
  }
205
+ export interface PtyWriteResult {
206
+ accepted: true;
207
+ backpressured: boolean;
208
+ }
209
+ export type PtyCloseStatus = 'closed' | 'not_found' | 'failed' | 'unknown';
210
+ export interface PtyCloseResult {
211
+ success: boolean;
212
+ ptyId: string;
213
+ status: PtyCloseStatus;
214
+ retryable: boolean;
215
+ error?: string;
216
+ }
204
217
  export type ForwardType = 'local' | 'remote';
218
+ export type ForwardLifecycle = 'pending' | 'active' | 'closing' | 'closed';
205
219
  export interface PortForwardInfo {
206
220
  id: string;
207
221
  alias: string;
@@ -212,6 +226,8 @@ export interface PortForwardInfo {
212
226
  remotePort: number;
213
227
  createdAt: number;
214
228
  active: boolean;
229
+ lifecycle: ForwardLifecycle;
230
+ acceptingConnections: boolean;
215
231
  }
216
232
  export type ForwardCloseMode = 'graceful' | 'force';
217
233
  export interface ForwardCloseOptions {
package/dist/utf8.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ export declare function isUtf8ContinuationByte(value: number): boolean;
2
+ export declare function ensureUtf8Boundary(buffer: Buffer, offset: number, field: string): void;
3
+ export declare function utf8SafeEnd(buffer: Buffer, start: number, requestedEnd: number, stream: string, limitedByMaxBytes?: boolean): number;
package/dist/utf8.js ADDED
@@ -0,0 +1,44 @@
1
+ export function isUtf8ContinuationByte(value) {
2
+ return (value & 0xc0) === 0x80;
3
+ }
4
+ function utf8SequenceLength(value) {
5
+ if ((value & 0x80) === 0) {
6
+ return 1;
7
+ }
8
+ if ((value & 0xe0) === 0xc0) {
9
+ return 2;
10
+ }
11
+ if ((value & 0xf0) === 0xe0) {
12
+ return 3;
13
+ }
14
+ if ((value & 0xf8) === 0xf0) {
15
+ return 4;
16
+ }
17
+ return 1;
18
+ }
19
+ export function ensureUtf8Boundary(buffer, offset, field) {
20
+ if (offset < buffer.length && isUtf8ContinuationByte(buffer[offset])) {
21
+ throw new Error(`${field} must point to a UTF-8 character boundary`);
22
+ }
23
+ }
24
+ export function utf8SafeEnd(buffer, start, requestedEnd, stream, limitedByMaxBytes = requestedEnd < buffer.length) {
25
+ let end = requestedEnd;
26
+ if (limitedByMaxBytes) {
27
+ while (end > start && isUtf8ContinuationByte(buffer[end])) {
28
+ --end;
29
+ }
30
+ }
31
+ if (end > start) {
32
+ let sequenceStart = end - 1;
33
+ while (sequenceStart > start && isUtf8ContinuationByte(buffer[sequenceStart])) {
34
+ --sequenceStart;
35
+ }
36
+ if (sequenceStart + utf8SequenceLength(buffer[sequenceStart]) > end) {
37
+ end = sequenceStart;
38
+ }
39
+ }
40
+ if (end === start && requestedEnd > start && limitedByMaxBytes) {
41
+ throw new Error(`maxBytes is too small to read the next UTF-8 character from ${stream}`);
42
+ }
43
+ return end;
44
+ }
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.2",
4
4
  "description": "A comprehensive SSH MCP Server for Claude Code",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -13,11 +13,11 @@
13
13
  "dev": "node node_modules/typescript7/bin/tsc && node dist/index.js",
14
14
  "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
15
15
  "prepublishOnly": "npm run build",
16
- "lint": "eslint \"src/**/*.ts\"",
17
- "lint:fix": "eslint \"src/**/*.ts\" --fix",
16
+ "lint": "eslint \"src/**/*.ts\" \"test/**/*.mjs\"",
17
+ "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.mjs\" --fix",
18
18
  "test": "npm run build && node test/run-tests.mjs",
19
- "format": "prettier --write src/",
20
- "format:check": "prettier --check src/"
19
+ "format": "prettier --write --prose-wrap always src/ test/ README.md README_zh.md TESTING.md",
20
+ "format:check": "prettier --check --prose-wrap always src/ test/ README.md README_zh.md TESTING.md"
21
21
  },
22
22
  "keywords": [
23
23
  "mcp",
@@ -33,7 +33,7 @@
33
33
  "url": "git+https://github.com/Pyrokine/claude-tools.git"
34
34
  },
35
35
  "dependencies": {
36
- "@modelcontextprotocol/sdk": "^1.29.0",
36
+ "@modelcontextprotocol/sdk": "^1.30.0",
37
37
  "@xterm/headless": "^6.0.0",
38
38
  "ssh2": "^1.17.0",
39
39
  "zod": "^4.4.3"