ToolBox MCP Server

Implementation Reference

• src/tools/sftp_tool.ts:194-255 (handler)

  The primary handler function for the sftp_tool. It validates input, establishes SSH/SFTP connection, executes upload or download based on action, and returns structured response or error.
  export default async (request: any) => { try { // 解析请求参数 const { serverName, action, localPath, remotePath } = request.params.arguments; // 验证参数 if (!serverName || !action || !localPath || !remotePath) { throw new Error("Missing required parameters: serverName, action, localPath, remotePath"); } if (action !== 'upload' && action !== 'download') { throw new Error('Invalid action. Must be "upload" or "download".'); } // 获取SSH连接 const conn = await getSSHConnection(serverName); // 获取SFTP会话 const sftp = await getSFTPSession(conn); let result; try { // 执行文件操作 if (action === 'upload') { result = await uploadFile(sftp, localPath, remotePath); } else { result = await downloadFile(sftp, remotePath, localPath); } } finally { // 关闭SFTP会话 sftp.end(); } // 返回成功结果 return { content: [ { type: "text", text: JSON.stringify({ message: result, action: action, localPath: localPath, remotePath: remotePath }, null, 2) } ] }; } catch (error) { // 返回错误结果 return { content: [ { type: "text", text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2) } ], isError: true }; } };
• src/tools/sftp_tool.ts:9-33 (schema)

  JSON schema defining the input parameters for the sftp_tool: serverName, action (upload/download), localPath, remotePath.
  export const schema = { name: "sftp_tool", description: "Connect to SSH server and upload/download files", type: "object", properties: { serverName: { type: "string", description: "SSH server name", }, action: { type: "string", description: "Action: upload or download", enum: ["upload", "download"], }, localPath: { type: "string", description: "Local file path (absolute)", }, remotePath: { type: "string", description: "Remote file path", }, }, required: ["serverName", "action", "localPath", "remotePath"] };
• src/tools/sftp_tool.ts:40-82 (helper)

  Helper function to retrieve or establish a cached SSH connection using environment variable SSH_{serverName}_URI (format: user:pass@host:port).
  async function getSSHConnection(serverName: string): Promise<Client> { // 如果已有连接，直接返回 if (sshConnections[serverName]) { return sshConnections[serverName]; } // 从环境变量获取连接信息 const sshUri = process.env[`SSH_${serverName}_URI`]; if (!sshUri) { throw new Error(`SSH_${serverName}_URI environment variable must be set.`); } // 解析连接信息 const [usernameAndpassword, HostAndport] = sshUri.split('@'); const [username, password] = usernameAndpassword.split(':'); const [host, port] = HostAndport.split(':'); // 创建新连接 return new Promise((resolve, reject) => { const conn = new Client(); conn.on('ready', () => { sshConnections[serverName] = conn; resolve(conn); }); conn.on('error', (err) => { delete sshConnections[serverName]; reject(new Error(`SSH connection error: ${err.message}`)); }); conn.on('end', () => { delete sshConnections[serverName]; }); conn.connect({ host: host, port: parseInt(port), username: username, password: password }); }); }
• src/tools/sftp_tool.ts:146-165 (helper)

  Helper function for uploading a local file to remote path via SFTP, ensuring the remote directory exists first.
  async function uploadFile(sftp: any, localPath: string, remotePath: string): Promise<string> { try { // 确保远程目录存在 const remoteDir = path.dirname(remotePath); await ensureRemoteDir(sftp, remoteDir); // 上传文件 return new Promise((resolve, reject) => { sftp.fastPut(localPath, remotePath, {}, (err: any) => { if (err) { reject(new Error(`Upload failed: ${err.message}`)); } else { resolve(`File uploaded successfully to ${remotePath}`); } }); }); } catch (error) { throw new Error(`Upload operation failed: ${error instanceof Error ? error.message : String(error)}`); } }
• src/tools/sftp_tool.ts:173-192 (helper)

  Helper function for downloading a remote file to local path via SFTP, ensuring the local directory exists first.
  async function downloadFile(sftp: any, remotePath: string, localPath: string): Promise<string> { try { // 确保本地目录存在 const localDir = path.dirname(localPath); await ensureLocalDir(localDir); // 下载文件 return new Promise((resolve, reject) => { sftp.fastGet(remotePath, localPath, {}, (err: any) => { if (err) { reject(new Error(`Download failed: ${err.message}`)); } else { resolve(`File downloaded successfully to ${localPath}`); } }); }); } catch (error) { throw new Error(`Download operation failed: ${error instanceof Error ? error.message : String(error)}`); } }