Metadata-Version: 2.4
Name: mcp-recognize-image
Version: 0.1.0
Summary: MCP server that lets text-only models 'see' images via configurable vision LLM providers with priority fallback
Author-email: Your Name <you@example.com>
License-Expression: MIT
Keywords: mcp,model-context-protocol,vision,image-recognition,multimodal,vlm
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# mcp-recognize-image

An MCP (Model Context Protocol) server that gives **text-only models the ability
to "see" images**. It routes image-recognition requests through configurable
multimodal (vision) LLM providers, with **priority-ordered automatic fallback**:
if the top provider fails (auth / rate-limit / error / timeout), the next is tried.

## Install (end users)

```bash
uvx mcp-recognize-image
```

Install [uv](https://docs.astral.sh/uv/) first if needed:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Or with pip:

```bash
pip install mcp-recognize-image
```

## Configure

Works out of the box with the bundled default providers (free vision endpoints
pre-filled). You only need to set API keys for the providers you have:

```bash
export GEMINI_API_KEY=...         # free tier: https://aistudio.google.com
export SILICONFLOW_API_KEY=...    # free tier: https://cloud.siliconflow.cn
export OPENROUTER_API_KEY=...     # free models: https://openrouter.ai
```

Config path resolution (only if you customize the provider list):

1. `VISION_MCP_CONFIG` env var (absolute path)
2. `~/.config/vision-mcp/config.toml`
3. bundled `config.example.toml` (fallback — used by default)

To customize the provider list, copy the bundled example and edit (from a source
checkout):

```bash
mkdir -p ~/.config/vision-mcp
cp src/vision_mcp/config.example.toml ~/.config/vision-mcp/config.toml
```

Free vision models rotate. Re-verify with (from a source checkout):

```bash
python scripts/verify_free_models.py              # OpenRouter list is public
SILICONFLOW_API_KEY=... python scripts/verify_free_models.py
GEMINI_API_KEY=... python scripts/verify_free_models.py
```

## Use with Claude Desktop / Cursor / Cline

Add to your MCP client config (Claude Desktop: `claude_desktop_config.json`).

With `uvx` (recommended, zero install):

```json
{
  "mcpServers": {
    "vision": {
      "command": "uvx",
      "args": ["mcp-recognize-image"],
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}
```

With a local install:

```json
{
  "mcpServers": {
    "vision": {
      "command": "mcp-recognize-image",
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}
```

## The tool

`recognize_image(image, prompt="Describe this image in detail.")` — `image` is a
local file path, an http(s) URL, or a `data:` URI. Returns the model's text
answer, or an `Error: ...` string if every provider failed.

## Adapters

| adapter        | providers                                                    |
|----------------|--------------------------------------------------------------|
| `openai_compat`| OpenAI, SiliconFlow, OpenRouter, any OpenAI-compatible endpoint |
| `gemini`       | Google Gemini (native API)                                   |
| `anthropic`    | Anthropic Claude (native API)                                |

## Develop

```bash
git clone <repo>
cd mcp-recognize-image
uv venv --python 3.13 .venv
uv pip install -e ".[dev]"
pytest -q
```

## Publish (maintainer)

```bash
uv build      # builds wheel + sdist into dist/
uv publish    # uploads to PyPI (set PYPI_TOKEN env or pass --token)
```
