http_head

Instructions

Implementation Reference

• src/mcp_requests/main.py:180-192 (handler)

  The main handler function for the 'http_head' MCP tool. It uses the shared 'make_http_request_with_logging' helper to perform the HTTP HEAD request, handles parameters like url, headers, cookies, timeout, and returns JSON-formatted results including logging info.

  @mcp.tool()
  def http_head(
      url: str, 
      headers: Optional[Dict[str, str]] = None,
      cookies: Optional[Dict[str, str]] = None,
      timeout: float = 30.0
  ) -> str:
      """HTTP HEAD request with full support (headers, cookies, timeout) - All requests logged"""
      try:
          result = make_http_request_with_logging("HEAD", url, headers or {}, cookies or {}, "", timeout)
          return json.dumps(result, indent=2)
      except Exception as e:
          return f"Error: {str(e)}"

• src/mcp_requests/main.py:56-101 (helper)

  Shared helper function that performs the actual HTTP request using httpx, logs the full request/response details, and returns structured results. Used by all http_* tools including http_head.

  def make_http_request_with_logging(method: str, url: str, headers: dict, cookies: dict, body: str, timeout: float):
      """Universal HTTP request function with logging"""
      try:
          with httpx.Client(timeout=timeout) as client:
              response = client.request(
                  method=method.upper(),
                  url=url,
                  headers=headers,
                  cookies=cookies,
                  content=body.encode('utf-8') if body else None
              )
              
              # Log the request and response
              log_path = log_request_response(
                  method=method.upper(), 
                  url=url, 
                  headers=headers, 
                  cookies=cookies, 
                  body=body,
                  status_code=response.status_code,
                  response_headers=dict(response.headers),
                  response_content=response.text,
                  response_length=len(response.text)
              )
              
              return {
                  "method": method.upper(),
                  "url": url,
                  "status_code": response.status_code,
                  "response_headers": dict(response.headers),
                  "response_content": response.text,
                  "response_length": len(response.text),
                  "request_headers": headers,
                  "request_cookies": cookies,
                  "request_body": body,
                  "logged_to": log_path
              }
      except Exception as e:
          # Log the error
          log_request_response(
              method=method.upper(), url=url, headers=headers, cookies=cookies, body=body,
              status_code=0, response_headers={}, response_content="", response_length=0,
              error=str(e)
          )
          raise e

• src/mcp_requests/main.py:30-54 (helper)

  Helper function that logs detailed request and response information to a timestamped file in ~/mcp_requests_logs/.

  def log_request_response(method: str, url: str, headers: dict, cookies: dict, body: str, 
                          status_code: int, response_headers: dict, response_content: str, 
                          response_length: int, error: str = None):
      """Log complete request and response details"""
      log_data = {
          "timestamp": datetime.datetime.now().isoformat(),
          "request": {
              "method": method,
              "url": url,
              "headers": headers,
              "cookies": cookies,
              "body": body,
              "body_length": len(body) if body else 0
          },
          "response": {
              "status_code": status_code if not error else "ERROR",
              "headers": response_headers if not error else {},
              "content_length": response_length if not error else 0,
              "content_preview": response_content[:500] + "..." if response_content and len(response_content) > 500 else response_content
          },
          "error": error
      }
      
      logger.info(f"HTTP_REQUEST: {json.dumps(log_data, indent=2, ensure_ascii=False)}")
      return log_path