Lupul-Augmentat/docs/tools/http-request.md

# HTTP Request Tool

Make HTTP/HTTPS requests with comprehensive options and security controls.

## Overview

The HttpRequestTool enables making HTTP requests to external services with support for various methods, headers, authentication, and response handling.

## Input Schema

```typescript
{
  url: string;                        // Target URL (required)
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
  headers?: Record<string, string>;   // Request headers
  body?: string | object;             // Request body
  timeout?: number;                   // Timeout in ms (default: 30000)
  followRedirects?: boolean;          // Follow redirects (default: true)
}
```

## Output Schema

```typescript
{
  status: number;                     // HTTP status code
  statusText: string;                 // Status message
  headers: Record<string, string>;    // Response headers
  body: any;                          // Response body (parsed based on content-type)
  duration: number;                   // Request duration in ms
}
```

## Features

### Supported Methods
- **GET** - Retrieve data
- **POST** - Submit data
- **PUT** - Update resource
- **DELETE** - Remove resource
- **PATCH** - Partial update
- **HEAD** - Headers only
- **OPTIONS** - Check allowed methods

### Automatic Content Handling
- JSON responses are automatically parsed
- Text responses returned as strings
- Binary data returned as base64 encoded strings
- Content-Type header automatically set for JSON bodies

### Security Features
- Blocks requests to private IP ranges (localhost, internal networks)
- Validates URLs before making requests
- Timeout protection against hanging requests
- Requires `network:http` permission

## Example Usage

### Simple GET Request
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/users'
});
console.log(response.body); // Parsed JSON
```

### POST with JSON Body
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/users',
  method: 'POST',
  body: {
    name: 'John Doe',
    email: 'john@example.com'
  }
});
```

### Custom Headers
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/data',
  headers: {
    'Authorization': 'Bearer token123',
    'X-API-Key': 'myapikey'
  }
});
```

### Form Data
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/form',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: 'name=John&email=john@example.com'
});
```

### With Timeout
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://slow-api.example.com/data',
  timeout: 5000  // 5 seconds
});
```

### Disable Redirect Following
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://example.com/redirect',
  followRedirects: false
});
// Check response.status for 301/302
```

## Response Handling

### JSON Response
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/json'
});
// response.body is already parsed object
console.log(response.body.data);
```

### Text Response
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://example.com/text.txt'
});
// response.body is string
console.log(response.body);
```

### Binary Response
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://example.com/image.png'
});
// response.body is base64 encoded string
const buffer = Buffer.from(response.body, 'base64');
```

### Status Checking
```javascript
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/resource'
});

if (response.status >= 200 && response.status < 300) {
  // Success
} else if (response.status === 404) {
  // Not found
} else if (response.status >= 500) {
  // Server error
}
```

## Error Handling

### Network Errors
```javascript
try {
  const response = await mcp.callTool('http_request', {
    url: 'https://nonexistent.example.com'
  });
} catch (error) {
  // Error: HTTP request failed: ...
}
```

### Timeout Errors
```javascript
try {
  const response = await mcp.callTool('http_request', {
    url: 'https://slow.example.com',
    timeout: 1000
  });
} catch (error) {
  // Error: Request timeout after 1000ms
}
```

### Invalid URLs
```javascript
try {
  const response = await mcp.callTool('http_request', {
    url: 'not-a-url'
  });
} catch (error) {
  // Error: Invalid URL
}
```

### Blocked Internal IPs
```javascript
try {
  const response = await mcp.callTool('http_request', {
    url: 'http://192.168.1.1/admin'
  });
} catch (error) {
  // Error: Requests to private IP ranges are not allowed
}
```

## Best Practices

1. **Always set appropriate timeouts** for external requests
2. **Handle all status codes** - don't assume 200 OK
3. **Use HTTPS** when possible for security
4. **Set User-Agent** header to identify your application
5. **Implement retry logic** for transient failures
6. **Respect rate limits** of external APIs
7. **Validate response data** before using it

## Common Patterns

### API Authentication
```javascript
// Bearer Token
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/protected',
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});

// API Key
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/data',
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

// Basic Auth
const credentials = Buffer.from('username:password').toString('base64');
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/secure',
  headers: {
    'Authorization': `Basic ${credentials}`
  }
});
```

### Pagination
```javascript
let allData = [];
let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await mcp.callTool('http_request', {
    url: `https://api.example.com/items?page=${page}&limit=100`
  });
  
  allData = allData.concat(response.body.items);
  hasMore = response.body.hasNextPage;
  page++;
}
```

## Limitations

- Cannot access localhost or private networks
- Maximum timeout of 5 minutes
- No support for streaming responses
- No built-in retry mechanism
- No connection pooling or keep-alive