head_object
Retrieve metadata of an S3 object without downloading its contents. Specify bucket, key, and optional conditions like ETag or version ID to filter results. Ideal for verifying object details efficiently.
Instructions
Retrieves metadata from an object without returning the object itself.
Args: bucket (str): The name of the bucket. key (str): The key (name) of the object. if_match (Optional[str]): Return object only if its ETag is the same. if_none_match (Optional[str]): Return object only if its ETag is different. version_id (Optional[str]): Version of the object.
Returns: str: JSON formatted S3 response.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| if_match | No | ||
| if_none_match | No | ||
| key | Yes | ||
| version_id | No |
Implementation Reference
- src/s3_mcp.py:300-327 (handler)The main handler function for the 'head_object' tool, decorated with @mcp.tool() for registration in FastMCP. It handles parameters, calls the core logic helper, and formats the JSON response.@mcp.tool() def head_object( bucket: str, key: str, if_match: Optional[str] = None, if_none_match: Optional[str] = None, version_id: Optional[str] = None, ) -> str: """Retrieves metadata from an object without returning the object itself. Args: bucket (str): The name of the bucket. key (str): The key (name) of the object. if_match (Optional[str]): Return object only if its ETag is the same. if_none_match (Optional[str]): Return object only if its ETag is different. version_id (Optional[str]): Version of the object. Returns: str: JSON formatted S3 response. """ result = _head_object_logic( bucket=bucket, key=key, if_match=if_match, if_none_match=if_none_match, version_id=version_id, ) return format_response(result)
- src/s3_mcp.py:270-298 (helper)The supporting helper function that executes the core boto3 S3 client.head_object call with conditional parameters.def _head_object_logic( bucket: str, key: str, if_match: Optional[str] = None, if_none_match: Optional[str] = None, version_id: Optional[str] = None, ) -> Dict[str, Any]: """Core logic to retrieve metadata from an object. Args: bucket (str): The S3 bucket name. key (str): The S3 object key. if_match (Optional[str]): Return object only if its ETag is the same. if_none_match (Optional[str]): Return object only if its ETag is different. version_id (Optional[str]): Version of the object. Returns: Dict[str, Any]: Raw boto3 response from head_object. """ client = get_s3_client() params: Dict[str, Any] = {"Bucket": bucket, "Key": key} if if_match: params["IfMatch"] = if_match if if_none_match: params["IfNoneMatch"] = if_none_match if version_id: params["VersionId"] = version_id return client.head_object(**params)