MCP Filesystem Server

Instructions

Args:
    path: Path to the file
    lines: Number of lines to read (default: 10)
    encoding: Text encoding (default: utf-8)
    ctx: MCP context

Returns:
    Last N lines of the file

Implementation Reference

• mcp_filesystem/server.py:351-374 (handler)

  MCP tool handler for 'tail_file'. This is the entrypoint function decorated with @mcp.tool(), defining the input schema via type annotations and docstring, handling errors, and delegating to the operations layer.

  @mcp.tool()
  async def tail_file(
      path: str,
      ctx: Context,
      lines: int = 10,
      encoding: str = "utf-8",
  ) -> str:
      """Read the last N lines of a text file.
  
      Args:
          path: Path to the file
          lines: Number of lines to read (default: 10)
          encoding: Text encoding (default: utf-8)
          ctx: MCP context
  
      Returns:
          Last N lines of the file
      """
      try:
          components = get_components()
          content = await components["operations"].tail_file(path, lines, encoding)
          return content
      except Exception as e:
          return f"Error reading file: {str(e)}"

• mcp_filesystem/operations.py:458-493 (helper)

  Core implementation of tail_file in the FileOperations class. Performs path validation, reads the entire file content, splits into lines, and returns the last N lines.

  async def tail_file(
      self, path: Union[str, Path], lines: int = 10, encoding: str = "utf-8"
  ) -> str:
      """Read the last N lines of a text file.
  
      Args:
          path: Path to the file
          lines: Number of lines to read (default: 10)
          encoding: Text encoding (default: utf-8)
  
      Returns:
          Last N lines of the file
  
      Raises:
          ValueError: If path is outside allowed directories
          FileNotFoundError: If file does not exist
      """
      abs_path, allowed = await self.validator.validate_path(path)
      if not allowed:
          raise ValueError(f"Path outside allowed directories: {path}")
  
      try:
          # We need to read the whole file to get the last N lines
          # This could be optimized for very large files
          data = await anyio.to_thread.run_sync(abs_path.read_text, encoding)
          file_lines = data.splitlines()
          start = max(0, len(file_lines) - lines)
          return "\n".join(file_lines[start:])
  
      except FileNotFoundError:
          raise FileNotFoundError(f"File not found: {path}")
      except PermissionError:
          raise ValueError(f"Permission denied: {path}")
      except UnicodeDecodeError:
          raise ValueError(f"Cannot decode file as {encoding}: {path}")

• mcp_filesystem/server.py:351-351 (registration)

  The @mcp.tool() decorator registers the tail_file function as an MCP tool.

  @mcp.tool()