# transfer-ai-mcp

`transfer-ai-mcp` is a small MCP server for relay or proxy AI endpoints. It reads configuration from environment variables and exposes tools for text generation and image generation.

## Features

- Supports `openai`-style and `gemini`-style HTTP APIs
- Configurable `url`, `key`, and `model` through environment variables
- Saves generated images locally and returns file paths (no base64 in MCP response)
- Packaged as a standalone Node library for reuse on other machines

## Changelog

### v0.2.0

- **Fix**: `generate_image` no longer returns base64 image data in MCP response. This fixes a crash in MCP clients (e.g. Kiro) that occurred when processing large image payloads in subsequent turns. Images are saved to disk and only file paths are returned.
- **Change**: Default `TRANSFER_AI_API_FORMAT` changed from `openai` to `gemini`.
- Response now includes file size info for each saved image.

### v0.1.0

- Initial release.

## Install

```bash
npm install
```

For a global install:

```bash
npm install -g .
```

Then run:

```bash
transfer-ai-mcp
```

## Environment variables

Required:

- `TRANSFER_AI_API_KEY`
- `TRANSFER_AI_BASE_URL` unless you use `TRANSFER_AI_TEXT_URL` and `TRANSFER_AI_IMAGE_URL`
- `TRANSFER_AI_MODEL` unless you set both `TRANSFER_AI_TEXT_MODEL` and `TRANSFER_AI_IMAGE_MODEL`

Optional:

- `TRANSFER_AI_API_FORMAT`
  - `openai` or `gemini`
  - default: `gemini`
- `TRANSFER_AI_AUTH_MODE`
  - `bearer`, `query`, `x-goog-api-key`, or `none`
  - default: `bearer`
- `TRANSFER_AI_TEXT_MODEL`
- `TRANSFER_AI_IMAGE_MODEL`
- `TRANSFER_AI_TEXT_URL`
- `TRANSFER_AI_IMAGE_URL`
- `TRANSFER_AI_TEXT_PATH`
- `TRANSFER_AI_IMAGE_PATH`
- `TRANSFER_AI_OUTPUT_DIR`

## Default endpoint behavior

If `TRANSFER_AI_API_FORMAT=openai`:

- text requests default to `/v1/chat/completions`
- image requests default to `/v1/chat/completions`

If `TRANSFER_AI_API_FORMAT=gemini`:

- text requests default to `/v1beta/models/{model}:generateContent`
- image requests default to `/v1beta/models/{model}:generateContent`

Override any of these with `TRANSFER_AI_TEXT_URL`, `TRANSFER_AI_IMAGE_URL`, `TRANSFER_AI_TEXT_PATH`, or `TRANSFER_AI_IMAGE_PATH`.

## Tools

- `get_configuration_status`
- `generate_text`
- `generate_image`
- `get_last_image_info`

`generate_text` arguments:

- `prompt`
- `systemPrompt`
- `model`
- `temperature`
- `maxTokens`
- `extraBody`

`generate_image` arguments:

- `prompt`
- `systemPrompt`
- `model`
- `aspectRatio`
- `imageSize`
- `outputPath`
- `extraBody`

## Kiro / VS Code MCP example

```json
{
  "mcpServers": {
    "transfer-ai": {
      "command": "node",
      "args": ["/path/to/transfer-ai-mcp/dist/index.js"],
      "env": {
        "TRANSFER_AI_API_FORMAT": "gemini",
        "TRANSFER_AI_AUTH_MODE": "bearer",
        "TRANSFER_AI_API_KEY": "your-api-key",
        "TRANSFER_AI_BASE_URL": "https://your-endpoint.example.com",
        "TRANSFER_AI_MODEL": "gemini-2.0-flash-preview-image-generation",
        "TRANSFER_AI_OUTPUT_DIR": "/path/to/output/images"
      },
      "disabled": false,
      "autoApprove": ["generate_image", "get_configuration_status"]
    }
  }
}
```

## Codex MCP example

See [examples/codex-config.toml](./examples/codex-config.toml).