# image-recognition-mcp

An MCP (Model Context Protocol) server that exposes a single tool, `vlm_recognize`, for running an OpenAI-compatible vision-language model on a local image with a natural-language prompt.

## Tool

### `vlm_recognize`

| Parameter    | Type   | Required | Description |
|--------------|--------|----------|-------------|
| `prompt`     | string | yes      | Natural-language instruction, e.g. `"extract all text in the image"` |
| `image_path` | string | yes      | Path to a local image (png/jpg/jpeg/gif/webp/bmp) |

Returns the model's text response.

## Configuration

### Required env

| Env               | Purpose                                      |
|-------------------|----------------------------------------------|
| `API_KEY`         | Bearer token for the OpenAI-compatible API  |
| `MODEL`           | Model name, e.g. `gpt-4o`, `glm-4v`, etc.   |

### Optional env

| Env                | Default                       | Purpose |
|--------------------|-------------------------------|---------|
| `OPENAI_BASE_URL`  | `https://api.openai.com/v1`   | Base URL for any OpenAI-compatible endpoint |

## Install

### Option A: `npx` (once published to npm)

```jsonc
// e.g. Claude Code's mcp config
"image-recognition-mcp": {
  "command": "npx",
  "args": ["-y", "image-recognition-mcp"],
  "env": {
    "API_KEY": "your_key",
    "OPENAI_BASE_URL": "https://api.openai.com/v1",
    "MODEL": "gpt-4o"
  }
}
```

### Option B: local checkout

```jsonc
"image-recognition-mcp": {
  "command": "node",
  "args": ["/absolute/path/to/image_recognition_mcp/index.js"],
  "env": {
    "API_KEY": "your_key",
    "OPENAI_BASE_URL": "https://api.openai.com/v1",
    "MODEL": "gpt-4o"
  }
}
```

Or after `npm link` in this repo:

```jsonc
"image-recognition-mcp": {
  "command": "image-recognition-mcp",
  "env": { "API_KEY": "...", "MODEL": "..." }
}
```

## Self-test

```bash
API_KEY=test-key MODEL=gpt-4o node index.js --self-test
```

Verifies the image-file → data-URL helper (extension check + MIME map) without making an API call.

## Notes

- Reads files from the local filesystem only. No URL fetching.
- Image is sent as a base64 data URL inside the `chat/completions` request body. Large images will produce large requests — resize before sending if your provider has size limits.
- Errors from the VLM API are surfaced as tool-call errors (non-zero exit code on the tool result).