@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.
- package/README.md +193 -109
- package/README_zh.md +238 -130
- package/dist/directory-verification.js +29 -4
- package/dist/file-ops.d.ts +31 -6
- package/dist/file-ops.js +493 -169
- package/dist/forward-manager.d.ts +17 -1
- package/dist/forward-manager.js +397 -89
- package/dist/operation-manager.d.ts +13 -6
- package/dist/operation-manager.js +200 -99
- package/dist/pty-manager.d.ts +3 -3
- package/dist/pty-manager.js +61 -15
- package/dist/session-manager.d.ts +29 -4
- package/dist/session-manager.js +288 -67
- package/dist/sftp-timeout.d.ts +9 -0
- package/dist/sftp-timeout.js +49 -0
- package/dist/tools/connection.js +85 -38
- package/dist/tools/exec.js +16 -6
- package/dist/tools/file.d.ts +1 -0
- package/dist/tools/file.js +276 -148
- package/dist/tools/forward.js +11 -8
- package/dist/tools/operation.js +12 -3
- package/dist/tools/pty.js +17 -13
- package/dist/tools/schema.d.ts +4 -0
- package/dist/tools/schema.js +9 -0
- package/dist/types.d.ts +16 -0
- package/dist/utf8.d.ts +3 -0
- package/dist/utf8.js +44 -0
- package/package.json +6 -6
|
@@ -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
|
+
}
|
package/dist/tools/connection.js
CHANGED
|
@@ -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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
|
139
|
-
user = user
|
|
140
|
-
port = port
|
|
141
|
-
keyPath = keyPath
|
|
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
|
|
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
|
|
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
|
|
235
|
+
const requestedJumpHost = args.jumpHost ?? template.jumpHost;
|
|
236
|
+
const jumpHost = requestedJumpHost
|
|
191
237
|
? {
|
|
192
|
-
host:
|
|
193
|
-
port:
|
|
194
|
-
username:
|
|
195
|
-
password:
|
|
196
|
-
privateKeyPath:
|
|
197
|
-
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
|
|
201
|
-
const finalAlias = requestedAlias
|
|
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:
|
|
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:
|
|
229
|
-
runAs,
|
|
230
|
-
host,
|
|
231
|
-
port:
|
|
232
|
-
defaultEnvKeys:
|
|
233
|
-
envKeys:
|
|
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}${
|
|
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
|
'示例',
|
package/dist/tools/exec.js
CHANGED
|
@@ -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:
|
|
69
|
-
|
|
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_${
|
|
207
|
+
const tempAlias = `_quick_${randomUUID()}`;
|
|
199
208
|
try {
|
|
200
209
|
await sessionManager.connect({
|
|
201
210
|
host: args.host,
|
|
202
|
-
port: args.port
|
|
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', {
|
package/dist/tools/file.d.ts
CHANGED
|
@@ -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;
|