mcp-image-server/PUBLISHING.md

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:

{
  "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:

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

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:

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

Then test the command:

image-recognition-mcp

Step 4: Publish to PyPI

Option A: Using Twine (Recommended)

python -m twine upload dist/*

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

Option B: Using UV (Modern Alternative)

uv publish

Set your PyPI token:

export UV_PUBLISH_TOKEN="your-pypi-token"

Step 5: Update Kilocode Configuration

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

pip install image-recognition-mcp

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

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

Or with pipx:

{
  "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:

{
  "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:

# 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.