MCP Filesystem Server

Instructions

Implementation Reference

• src/utils/bash/bash_tools.ts:139-195 (handler)

  Core handler function that validates and executes the bash command using child_process.exec, captures stdout/stderr/exitCode, with safety checks and logging.

  export async function bashExecute(
    args: z.infer<typeof BashExecuteArgsSchema>,
    config: Config
  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
    // Validate the command
    validateCommand(args.command)
  
    // Validate working directory if provided
    // Initialize cwd with the current directory and possibly override it
    const cwd = args.workingDir ? await validatePath(args.workingDir, config) : process.cwd()
  
    // Prepare execution options
    const options = {
      cwd,
      timeout: args.timeout || 30000,
      env: args.env ? { ...process.env, ...args.env } : process.env,
      encoding: 'utf8' as const,
      maxBuffer: 10 * 1024 * 1024, // 10MB buffer for output
    }
  
    try {
      await logger.debug(`Executing bash command: ${args.command}`, {
        workingDir: cwd,
        timeout: options.timeout,
      })
  
      // Execute the command
      const { stdout, stderr } = await execPromise(args.command, options)
  
      await logger.debug(`Command executed successfully: ${args.command}`, {
        exitCode: 0,
        stdoutPreview: stdout.substring(0, 100) + (stdout.length > 100 ? '...' : ''),
      })
  
      return {
        stdout,
        stderr,
        exitCode: 0,
      }
    } catch (error: any) {
      // Handle command execution errors
      const stderr = error.stderr || ''
      const stdout = error.stdout || ''
      const exitCode = error.code || 1
  
      await logger.warn(`Command execution failed: ${args.command}`, {
        exitCode,
        stderr: stderr.substring(0, 100) + (stderr.length > 100 ? '...' : ''),
      })
  
      return {
        stdout,
        stderr,
        exitCode,
      }
    }
  }

• src/utils/bash/bash_tools.ts:69-82 (schema)

  Zod schema defining the input parameters for the bash_execute tool: command, workingDir, timeout, env.

  // Schema for bash_execute arguments
  export const BashExecuteArgsSchema = z.object({
    command: z.string().describe('The bash command to execute'),
    workingDir: z.string().optional().describe('Working directory for command execution'),
    timeout: z
      .number()
      .int()
      .positive()
      .max(60000)
      .optional()
      .default(30000)
      .describe('Maximum execution time in milliseconds (max 60s)'),
    env: z.record(z.string()).optional().describe('Additional environment variables for the command'),
  })

• src/bash/tools/index.ts:50-99 (handler)

  MCP-specific handler wrapper: parses args with schema, calls core bashExecute, formats MCP response with content array.

  export async function handleBashExecute(args: any, config: Config) {
    const endMetric = metrics.startOperation('bash_execute')
  
    try {
      // Validate arguments
      const parsed = BashExecuteArgsSchema.safeParse(args)
      if (!parsed.success) {
        throw new FileSystemError(`Invalid arguments for bash_execute`, 'INVALID_ARGS', undefined, {
          errors: parsed.error.format(),
        })
      }
  
      // Execute the command
      const result = await bashExecute(parsed.data, config)
  
      // Format the response
      const formattedResponse = formatCommandResult(result, parsed.data.command)
  
      await logger.debug(`Bash command executed: ${args.command}`, {
        exitCode: result.exitCode,
      })
  
      endMetric()
      return {
        content: [
          {
            type: 'text',
            text: formattedResponse,
          },
        ],
      }
    } catch (error) {
      metrics.recordError('bash_execute')
  
      if (error instanceof FileSystemError) {
        await logger.error(`Error in bash_execute:`, error.toJSON())
        return {
          content: [{ type: 'text', text: `Error: ${error.message}` }],
          isError: true,
        }
      }
  
      const errorMessage = error instanceof Error ? error.message : String(error)
      await logger.error(`Unexpected error in bash_execute:`, { error })
  
      return {
        content: [{ type: 'text', text: `Error: ${errorMessage}` }],
        isError: true,
      }
    }

• src/index.ts:356-361 (registration)

  Tool definition and schema registration in the listTools handler response.

  name: 'bash_execute',
  description:
    'Execute a Bash command directly with output capture. ' +
    'More flexible than execute_command but still with security restrictions. ' +
    'Allows for direct access to Bash functionality.',
  inputSchema: zodToJsonSchema(BashExecuteArgsSchema) as ToolInput,

• src/index.ts:757-758 (registration)

  Dispatch/handling registration in the callToolRequest switch statement.

  case 'bash_execute': {
    return await handleBashExecute(a, config)