Metadata-Version: 2.4
Name: gucken-image-reader
Version: 1.1.2
Summary: MCP server for image reader using OpenAI vision API (gpt-4o-mini)
Author: Jay Pak
Author-email: Jay Pak <jaypark@forestsoft.co.kr>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp
Requires-Dist: openai
Requires-Dist: python-dotenv
Dynamic: license-file

[English](#english) | [한국어](#한국어)

---

## English

**gucken-image-reader** is an MCP (Model Context Protocol) server that uses OpenAI's Vision API to generate descriptive text for images. It provides a single `describe_image` tool via stdio, enabling any MCP-compatible client (such as Claude or custom applications) to send an image file path and receive a detailed textual description in response.

### Installation

**Prerequisite: UV**

If you don't have UV installed, follow these steps:

* **macOS / Linux**

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

* **Windows (PowerShell)**

  ```powershell
  powershell -ExecutionPolicy ByPass -Command "irm https://astral.sh/uv/install.ps1 | iex"
  ```

### Configuration

In your working directory, create a `.env` file or export the environment variable directly:

```dotenv
OPENAI_API_KEY=your_openai_api_key_here
```

### Integration with an MCP host

Add the following entry to your `claude_desktop_config.json` (or other MCP-compatible host configuration):

```json
{
  "mcpServers": {
    "image-reader": {
      "command": "uvx",
      "args": ["gucken-image-reader"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}
```

* **command**: `uvx`
* **args**: `gucken-image-reader`
* **env**: Ensure that `OPENAI_API_KEY` is set.

### Usage

1. Complete the installation and configuration steps above.

2. Start or restart your MCP host (e.g., the Claude desktop app); it will launch the `gucken-image-reader` server over stdio.

3. Send an MCP request (JSON-RPC) calling the `describe_image` method with a local image file 

4. Receive a JSON response containing the image description generated by the model.

### License

MIT

---

## 한국어

**gucken-image-reader**은 OpenAI Vision API를 활용해 이미지에 대한 설명을 생성하는 MCP(Model Context Protocol) 서버입니다. `describe_image` 툴을 stdio 방식으로 사용해 이미지를 텍스트로 설명해줍니다

### 설치

**UV 설치 (아직 설치하지 않으셨다면)**

* **macOS / Linux**

  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
* **Windows (PowerShell)**

  ```powershell
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

### 설정

다음 내용을 담은 `.env` 파일을 작업 디렉터리에 생성하거나, 환경 변수를 직접 설정하세요:

```dotenv
OPENAI_API_KEY=your_openai_api_key_here
```

### MCP 호스트 통합

`claude_desktop_config.json`(또는 다른 MCP 호환 호스트 설정)에 다음 항목을 추가하세요:

```json
{
  "mcpServers": {
    "image-reader": {
      "command": "uvx",
      "args": [
        "gucken-image-reader"
      ],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}
```

* **command**: `uvx`
* **args**: 콘솔 스크립트 이름 `gucken-image-reader`
* **env**: `OPENAI_API_KEY` 설정 필수

### 사용 방법

1. 위 설치·설정 과정을 완료합니다.
2. MCP 호스트(예: Claude 앱)를 실행하거나 재시작하면 서버가 stdio로 구동됩니다.
3. `describe_image` 툴을 호출하며 로컬 이미지 파일 경로를 전송합니다:
4. 모델이 생성한 이미지 묘사 텍스트를 응답으로 받습니다.

### 라이선스

MIT
