# Publishing Guide

This guide explains how to make the Image Recognition MCP Server portable and distributable.

## Current Setup (Local)

The server currently runs locally using the `run.sh` script. This is configured in Kilocode's MCP settings:

```json
{
  "mcpServers": {
    "image-recognition": {
      "command": "/home/enne2/Sviluppo/tetris-sdl/mcp-image-server/run.sh",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}
```

## Making It Portable (PyPI Distribution)

To make this server portable and installable by anyone, you can publish it to PyPI.

### Prerequisites

1. Install build tools:
```bash
pip install build twine
```

2. Create a PyPI account at https://pypi.org/account/register/

3. Create an API token at https://pypi.org/manage/account/token/

### Step 1: Update Package Metadata

Edit `setup.py` and `pyproject.toml` to update:
- `author` and `author_email`
- `url` (your GitHub repository)
- Version number

### Step 2: Build the Package

```bash
cd /home/enne2/Sviluppo/tetris-sdl/mcp-image-server
python -m build
```

This creates:
- `dist/image-recognition-mcp-0.1.0.tar.gz` (source distribution)
- `dist/image_recognition_mcp-0.1.0-py3-none-any.whl` (wheel distribution)

### Step 3: Test Locally

Before publishing, test the package locally:

```bash
pip install dist/image_recognition_mcp-0.1.0-py3-none-any.whl
```

Then test the command:
```bash
image-recognition-mcp
```

### Step 4: Publish to PyPI

#### Option A: Using Twine (Recommended)

```bash
python -m twine upload dist/*
```

You'll be prompted for your PyPI username and password/token.

#### Option B: Using UV (Modern Alternative)

```bash
uv publish
```

Set your PyPI token:
```bash
export UV_PUBLISH_TOKEN="your-pypi-token"
```

### Step 5: Update Kilocode Configuration

After publishing, users can install and use your server with:

```bash
pip install image-recognition-mcp
```

Or use it directly with `uvx` (like `npx` for Python):

```json
{
  "mcpServers": {
    "image-recognition": {
      "command": "uvx",
      "args": [
        "image-recognition-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}
```

Or with `pipx`:

```json
{
  "mcpServers": {
    "image-recognition": {
      "command": "pipx",
      "args": [
        "run",
        "image-recognition-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}
```

## Benefits of PyPI Distribution

1. **Easy Installation**: Users can install with `pip install image-recognition-mcp`
2. **Version Management**: Easy to update and manage versions
3. **Dependency Management**: Automatically installs required dependencies
4. **Portable**: Works on any system with Python installed
5. **No Local Path**: No need for absolute paths in configuration

## Alternative: GitHub Distribution

If you don't want to publish to PyPI, you can distribute via GitHub:

```json
{
  "mcpServers": {
    "image-recognition": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/image-recognition-mcp.git",
        "image-recognition-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}
```

## Updating the Package

1. Update version in `setup.py` and `pyproject.toml`
2. Rebuild: `python -m build`
3. Republish: `python -m twine upload dist/*`

Users will get updates automatically when they reinstall or when using `uvx`.

## Testing Before Publishing

Always test your package locally before publishing:

```bash
# Build
python -m build

# Install locally
pip install dist/*.whl

# Test
image-recognition-mcp

# Uninstall
pip uninstall image-recognition-mcp
```

## Current Status

✅ Package structure ready
✅ `setup.py` configured
✅ `pyproject.toml` configured
✅ `MANIFEST.in` created
✅ LICENSE added
✅ Entry point configured

**Ready to publish!** Just update the metadata and follow the steps above.