head_object
Retrieve metadata from S3 objects without downloading content. Check object existence, size, type, and version details using conditional headers.
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 | ||
| key | Yes | ||
| if_match | No | ||
| if_none_match | No | ||
| version_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/s3_mcp.py:300-327 (handler)The primary handler for the 'head_object' MCP tool, registered via @mcp.tool() decorator. It invokes the helper function and formats the boto3 response as JSON.
@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-297 (helper)Helper function containing the core implementation logic for the head_object tool, constructing parameters and calling boto3's head_object method.
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)