@patruff/server-curl/README.md

MCP server for making curl/HTTP requests to fetch resources from the internet, with optional image conversion

# 🌐 @patruff/server-curl

An MCP (Model Context Protocol) server that allows Claude and other LLMs to make HTTP requests to fetch resources from the internet, with optional image conversion and automatic file saving.

## 🚀 Features

- 📡 Make HTTP requests (GET, POST, PUT, etc.) to any URL
- 🖼️ Automatically handles binary data (images, PDFs, etc.) and returns them as base64-encoded strings
- 👁️ Includes image preview for image responses
- 🔄 Fast image format conversion with graceful fallback (tries PNG/JPEG but reverts quickly if it can't convert)
- 💾 Direct file saving capability - save directly to the filesystem
- 🔧 Set custom headers, request body, timeout, and more

## 📦 Installation

```bash
# Install globally
npm install -g @patruff/server-curl

# Or install locally
npm install @patruff/server-curl
```

## 🔧 Usage

Start the server:

```bash
# If installed globally
server-curl

# If installed locally
npx @patruff/server-curl
```

The MCP server runs on stdio, making it compatible with LLM interfaces that support the Model Context Protocol.

## 🛠️ API

The server exposes a single tool:

### `curl`

Makes an HTTP request to the specified URL, with options for conversion and saving.

#### Parameters

- `url` (string, required): The URL to send the request to
- `method` (string, optional): HTTP method (GET, POST, PUT, etc.), defaults to "GET"
- `headers` (object, optional): HTTP headers to include in the request
- `body` (string, optional): Request body for POST/PUT/PATCH requests
- `timeout` (number, optional): Request timeout in milliseconds, defaults to 30000
- `convertTo` (string, optional): Convert image to specified format (png, jpeg, jpg, webp, gif)
- `saveAs` (string, optional): Save the response directly to this filename

#### Response

The response includes:

- `success` (boolean): Whether the request was successful
- `statusCode` (number): HTTP status code
- `headers` (object): Response headers
- `contentType` (string): Content-Type of the response
- `isBinary` (boolean): Whether the response is binary data
- `data` (string): Response data (text or base64-encoded binary)
- `error` (string): Error message if the request failed
- `saved` (string): Path where the file was saved (if saveAs was specified)
- `converted` (boolean): Whether image conversion was successful

## 💡 Examples

### Fetching an image

```json
{
  "url": "https://example.com/image.png"
}
```

### Fetching a Flux-generated image and converting to PNG

```json
{
  "url": "https://replicate.delivery/pbxt/example-image-url",
  "convertTo": "png"
}
```

### Fetching and saving an image directly to disk

```json
{
  "url": "https://example.com/image.jpg",
  "saveAs": "downloaded_image.jpg"
}
```

### Fetching a Flux image, converting to PNG, and saving

```json
{
  "url": "https://replicate.delivery/pbxt/example-flux-image",
  "convertTo": "png",
  "saveAs": "flux_image.png"
}
```

### Making a POST request

```json
{
  "url": "https://api.example.com/data",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer token123"
  },
  "body": "{\"key\": \"value\"}"
}
```

## ⚡ Fast Conversion

The MCP uses a smart approach to image conversion:

- Attempts to convert using Sharp but with a strict 3-second timeout
- If conversion fails or takes too long, immediately falls back to the original format
- Adjusts the file extension when saving to match the actual format

## 🔐 Security Considerations

- This MCP allows arbitrary HTTP requests to any URL
- Consider implementing URL allowlisting/denylisting for production use
- Be cautious when handling sensitive data

## 🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.