@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
package/dist/tools/forward.js
CHANGED
|
@@ -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:
|
|
20
|
+
localPort: dynamicSshPortSchema.describe('本地监听端口,传 0 时由系统动态分配'),
|
|
20
21
|
remoteHost: z.string().describe('远程目标主机'),
|
|
21
|
-
remotePort:
|
|
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:
|
|
27
|
+
remotePort: dynamicSshPortSchema.describe('远程监听端口,传 0 时由服务器动态分配'),
|
|
27
28
|
localHost: z.string().describe('本地目标地址'),
|
|
28
|
-
localPort:
|
|
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
|
-
|
|
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
|
}
|
package/dist/tools/operation.js
CHANGED
|
@@ -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
|
|
107
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
103
|
+
const result = sessionManager.ptyClose(args.ptyId);
|
|
104
104
|
return formatResult({
|
|
105
|
-
|
|
106
|
-
message: success
|
|
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,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.
|
|
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.
|
|
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"
|