Path Info Tool¶

The PathInfo tool provides a single-call interface to retrieve file and directory metadata.

Class Overview¶

PathInfo - Unified metadata query returning existence, type, size, modification time, and permissions in a single call.

Usage¶

Basic Usage¶

from toolregistry_hub import PathInfo

# Query a file
info = PathInfo.info("/path/to/file.py")
print(info)
# {
#     "exists": True,
#     "type": "file",
#     "size": 1234,
#     "last_modified": "2026-03-18T12:00:00+00:00",
#     "permissions": "rw-r--r--"
# }

# Query a directory (size is recursive)
info = PathInfo.info("/path/to/dir")
print(info["size"])  # Total size of all files in the directory

# Non-existent path
info = PathInfo.info("/does/not/exist")
print(info)  # {"exists": False}

Return Value¶

info() returns a dict with the following keys when the path exists:

Key	Type	Description
`exists`	`bool`	Always `True` for existing paths
`type`	`str`	`"file"`, `"directory"`, `"symlink"`, or `"other"`
`size`	`int`	Size in bytes. For directories, total size of all contents (recursive)
`last_modified`	`str`	ISO 8601 timestamp in UTC
`permissions`	`str`	Unix-style permission string (e.g. `"rwxr-xr-x"`)

When the path does not exist, only {"exists": False} is returned.

Design Rationale¶

PathInfo consolidates five separate metadata queries (exists, is_file, is_dir, get_size, get_last_modified_time) into a single call. This reduces the number of tool invocations needed in agent workflows, as LLMs typically need multiple metadata fields at once.

MCP Server Endpoint¶

POST /tools/fs/path_info/info

Parameters:

Parameter	Type	Required	Description
`path`	`string`	Yes	Absolute or relative path to query

API Reference¶

toolregistry_hub.path_info.PathInfo ¶

File and directory metadata query.

info `staticmethod` ¶

info(path: str) -> dict

Get metadata for a file or directory in a single call.

Parameters:

Name	Type	Description	Default
`path`	`str`	Absolute or relative path to query.	required

Returns:

Type	Description
`dict`	A dict with keys: - exists (bool) - type ("file" \| "directory" \| "symlink" \| "other") - size (int, bytes) — for directories, total size of contents - last_modified (str, ISO 8601 in UTC) - permissions (str, e.g. "rwxr-xr-x")
`dict`	If path does not exist, returns `{"exists": False}`.

Source code in toolregistry_hub/path_info.py

@staticmethod
def info(path: str) -> dict:
    """Get metadata for a file or directory in a single call.

    Args:
        path: Absolute or relative path to query.

    Returns:
        A dict with keys:
            - exists (bool)
            - type ("file" | "directory" | "symlink" | "other")
            - size (int, bytes) — for directories, total size of contents
            - last_modified (str, ISO 8601 in UTC)
            - permissions (str, e.g. "rwxr-xr-x")

        If path does not exist, returns ``{"exists": False}``.
    """
    p = Path(path)

    if not p.exists():
        return {"exists": False}

    st = p.stat()

    # Determine type
    if p.is_symlink():
        path_type = "symlink"
    elif p.is_file():
        path_type = "file"
    elif p.is_dir():
        path_type = "directory"
    else:
        path_type = "other"

    # Calculate size — recursive for directories
    if p.is_dir():
        size = sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
    else:
        size = st.st_size

    # ISO 8601 timestamp in UTC
    last_modified = datetime.fromtimestamp(st.st_mtime, tz=timezone.utc).isoformat()

    # Human-readable permissions string (e.g. "rwxr-xr-x")
    permissions = stat.filemode(st.st_mode)[1:]  # strip leading type char

    return {
        "exists": True,
        "type": path_type,
        "size": size,
        "last_modified": last_modified,
        "permissions": permissions,
    }