commit
77342c8680
12 changed files with 1078 additions and 0 deletions
@ -0,0 +1,210 @@ |
|||||||
|
# Byte-compiled / optimized / DLL files |
||||||
|
__pycache__/ |
||||||
|
*.py[cod] |
||||||
|
*$py.class |
||||||
|
|
||||||
|
# C extensions |
||||||
|
*.so |
||||||
|
|
||||||
|
# Distribution / packaging |
||||||
|
.Python |
||||||
|
build/ |
||||||
|
develop-eggs/ |
||||||
|
dist/ |
||||||
|
downloads/ |
||||||
|
eggs/ |
||||||
|
.eggs/ |
||||||
|
lib/ |
||||||
|
lib64/ |
||||||
|
parts/ |
||||||
|
sdist/ |
||||||
|
var/ |
||||||
|
wheels/ |
||||||
|
share/python-wheels/ |
||||||
|
*.egg-info/ |
||||||
|
.installed.cfg |
||||||
|
*.egg |
||||||
|
MANIFEST |
||||||
|
|
||||||
|
# PyInstaller |
||||||
|
# Usually these files are written by a python script from a template |
||||||
|
# before PyInstaller builds the exe, so as to inject date/other infos into it. |
||||||
|
*.manifest |
||||||
|
*.spec |
||||||
|
|
||||||
|
# Installer logs |
||||||
|
pip-log.txt |
||||||
|
pip-delete-this-directory.txt |
||||||
|
|
||||||
|
# Unit test / coverage reports |
||||||
|
htmlcov/ |
||||||
|
.tox/ |
||||||
|
.nox/ |
||||||
|
.coverage |
||||||
|
.coverage.* |
||||||
|
.cache |
||||||
|
nosetests.xml |
||||||
|
coverage.xml |
||||||
|
*.cover |
||||||
|
*.py,cover |
||||||
|
.hypothesis/ |
||||||
|
.pytest_cache/ |
||||||
|
cover/ |
||||||
|
|
||||||
|
# Translations |
||||||
|
*.mo |
||||||
|
*.pot |
||||||
|
|
||||||
|
# Django stuff: |
||||||
|
*.log |
||||||
|
local_settings.py |
||||||
|
db.sqlite3 |
||||||
|
db.sqlite3-journal |
||||||
|
|
||||||
|
# Flask stuff: |
||||||
|
instance/ |
||||||
|
.webassets-cache |
||||||
|
|
||||||
|
# Scrapy stuff: |
||||||
|
.scrapy |
||||||
|
|
||||||
|
# Sphinx documentation |
||||||
|
docs/_build/ |
||||||
|
|
||||||
|
# PyBuilder |
||||||
|
.pybuilder/ |
||||||
|
target/ |
||||||
|
|
||||||
|
# Jupyter Notebook |
||||||
|
.ipynb_checkpoints |
||||||
|
|
||||||
|
# IPython |
||||||
|
profile_default/ |
||||||
|
ipython_config.py |
||||||
|
|
||||||
|
# pyenv |
||||||
|
# For a library or package, you might want to ignore these files since the code is |
||||||
|
# intended to run in multiple environments; otherwise, check them in: |
||||||
|
# .python-version |
||||||
|
|
||||||
|
# pipenv |
||||||
|
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. |
||||||
|
# However, in case of collaboration, if having platform-specific dependencies or dependencies |
||||||
|
# having no cross-platform support, pipenv may install dependencies that don't work, or not |
||||||
|
# install all needed dependencies. |
||||||
|
#Pipfile.lock |
||||||
|
|
||||||
|
# poetry |
||||||
|
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. |
||||||
|
# This is especially recommended for binary packages to ensure reproducibility, and is more |
||||||
|
# commonly ignored for libraries. |
||||||
|
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control |
||||||
|
#poetry.lock |
||||||
|
|
||||||
|
# pdm |
||||||
|
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. |
||||||
|
#pdm.lock |
||||||
|
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it |
||||||
|
# in version control. |
||||||
|
# https://pdm.fming.dev/#use-with-ide |
||||||
|
.pdm.toml |
||||||
|
|
||||||
|
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm |
||||||
|
__pypackages__/ |
||||||
|
|
||||||
|
# Celery stuff |
||||||
|
celerybeat-schedule |
||||||
|
celerybeat.pid |
||||||
|
|
||||||
|
# SageMath parsed files |
||||||
|
*.sage.py |
||||||
|
|
||||||
|
# Environments |
||||||
|
.env |
||||||
|
.venv |
||||||
|
env/ |
||||||
|
venv/ |
||||||
|
ENV/ |
||||||
|
env.bak/ |
||||||
|
venv.bak/ |
||||||
|
|
||||||
|
# Spyder project settings |
||||||
|
.spyderproject |
||||||
|
.spyproject |
||||||
|
|
||||||
|
# Rope project settings |
||||||
|
.ropeproject |
||||||
|
|
||||||
|
# mkdocs documentation |
||||||
|
/site |
||||||
|
|
||||||
|
# mypy |
||||||
|
.mypy_cache/ |
||||||
|
.dmypy.json |
||||||
|
dmypy.json |
||||||
|
|
||||||
|
# Pyre type checker |
||||||
|
.pyre/ |
||||||
|
|
||||||
|
# pytype static type analyzer |
||||||
|
.pytype/ |
||||||
|
|
||||||
|
# Cython debug symbols |
||||||
|
cython_debug/ |
||||||
|
|
||||||
|
# IDEs |
||||||
|
.vscode/ |
||||||
|
.idea/ |
||||||
|
*.swp |
||||||
|
*.swo |
||||||
|
*~ |
||||||
|
|
||||||
|
# OS generated files |
||||||
|
.DS_Store |
||||||
|
.DS_Store? |
||||||
|
._* |
||||||
|
.Spotlight-V100 |
||||||
|
.Trashes |
||||||
|
ehthumbs.db |
||||||
|
Thumbs.db |
||||||
|
|
||||||
|
# Project-specific files |
||||||
|
# Server logs |
||||||
|
*.log |
||||||
|
image_server.log |
||||||
|
|
||||||
|
# Configuration files with sensitive data |
||||||
|
config.json |
||||||
|
secrets.json |
||||||
|
.env.local |
||||||
|
.env.production |
||||||
|
|
||||||
|
# Temporary files |
||||||
|
tmp/ |
||||||
|
temp/ |
||||||
|
.tmp/ |
||||||
|
|
||||||
|
# MCP Server specific |
||||||
|
# Kilocode configuration (may contain API keys) |
||||||
|
kilocode_config.json |
||||||
|
|
||||||
|
# Build artifacts |
||||||
|
*.tar.gz |
||||||
|
*.zip |
||||||
|
*.whl |
||||||
|
|
||||||
|
# Local development files |
||||||
|
run_local.sh |
||||||
|
test_images/ |
||||||
|
.local/ |
||||||
|
|
||||||
|
# Backup files |
||||||
|
*.bak |
||||||
|
*.backup |
||||||
|
*~.nib |
||||||
|
|
||||||
|
# API keys and secrets (extra safety) |
||||||
|
*api_key* |
||||||
|
*secret* |
||||||
|
*token* |
||||||
|
credentials.json |
||||||
@ -0,0 +1,21 @@ |
|||||||
|
MIT License |
||||||
|
|
||||||
|
Copyright (c) 2025 Image Recognition MCP Server |
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy |
||||||
|
of this software and associated documentation files (the "Software"), to deal |
||||||
|
in the Software without restriction, including without limitation the rights |
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
||||||
|
copies of the Software, and to permit persons to whom the Software is |
||||||
|
furnished to do so, subject to the following conditions: |
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all |
||||||
|
copies or substantial portions of the Software. |
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
||||||
|
SOFTWARE. |
||||||
@ -0,0 +1,5 @@ |
|||||||
|
include README.md |
||||||
|
include LICENSE |
||||||
|
include requirements.txt |
||||||
|
include run.sh |
||||||
|
recursive-include image_recognition_server *.py |
||||||
@ -0,0 +1,200 @@ |
|||||||
|
# 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. |
||||||
@ -0,0 +1,238 @@ |
|||||||
|
# MCP Image Recognition Server |
||||||
|
|
||||||
|
An MCP (Model Context Protocol) server that provides AI-powered image analysis tools for AI assistants. |
||||||
|
|
||||||
|
## Features |
||||||
|
|
||||||
|
- **describe_image**: Analyze images from base64 encoded data using OpenAI's Vision API |
||||||
|
- **describe_image_from_file**: Analyze images from file paths using OpenAI's Vision API |
||||||
|
- Automatic fallback to basic metadata if OpenAI API is not configured |
||||||
|
- **Automatic Kilocode configuration** on installation |
||||||
|
- Portable and distributable via PyPI |
||||||
|
|
||||||
|
## Quick Installation (Recommended) |
||||||
|
|
||||||
|
Install from PyPI (once published): |
||||||
|
|
||||||
|
```bash |
||||||
|
pip install image-recognition-mcp |
||||||
|
``` |
||||||
|
|
||||||
|
The server will **automatically configure itself** in Kilocode during installation! 🎉 |
||||||
|
|
||||||
|
If automatic configuration doesn't work, you can manually run: |
||||||
|
|
||||||
|
```bash |
||||||
|
image-recognition-mcp-install |
||||||
|
``` |
||||||
|
|
||||||
|
## Local Development Setup |
||||||
|
|
||||||
|
For local development or if you want to run from source: |
||||||
|
|
||||||
|
```bash |
||||||
|
cd /home/enne2/Sviluppo/tetris-sdl/mcp-image-server |
||||||
|
./run.sh |
||||||
|
``` |
||||||
|
|
||||||
|
The script will automatically: |
||||||
|
- ✅ Create virtual environment if it doesn't exist |
||||||
|
- ✅ Install dependencies if needed |
||||||
|
- ✅ Activate the virtual environment |
||||||
|
- ✅ Start the server |
||||||
|
|
||||||
|
## Configuration |
||||||
|
|
||||||
|
After installation, you need to add your OpenAI API key: |
||||||
|
|
||||||
|
1. Open Kilocode's MCP settings: |
||||||
|
`~/.config/VSCodium/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json` |
||||||
|
|
||||||
|
2. Find the `image-recognition` server entry |
||||||
|
|
||||||
|
3. Replace `"your-openai-api-key-here"` with your actual OpenAI API key |
||||||
|
|
||||||
|
4. Restart Kilocode |
||||||
|
|
||||||
|
## Available Tools |
||||||
|
|
||||||
|
### 1. describe_image |
||||||
|
Analyzes an image from base64 encoded data using OpenAI's GPT-4 Vision. |
||||||
|
|
||||||
|
**Parameters:** |
||||||
|
- `image_data` (string, required): Base64 encoded image data |
||||||
|
- `mime_type` (string, optional): MIME type of the image (default: 'image/jpeg') |
||||||
|
|
||||||
|
**Returns:** Detailed AI-generated description of the image including objects, colors, composition, and visible text |
||||||
|
|
||||||
|
**Fallback:** If OpenAI API is not configured, returns basic image metadata (size, mode, format) |
||||||
|
|
||||||
|
### 2. describe_image_from_file |
||||||
|
Analyzes an image from a file path using OpenAI's GPT-4 Vision. |
||||||
|
|
||||||
|
**Parameters:** |
||||||
|
- `file_path` (string, required): Path to the image file |
||||||
|
|
||||||
|
**Returns:** Detailed AI-generated description of the image |
||||||
|
|
||||||
|
**Supported formats:** JPEG, PNG, GIF, WebP (automatically detected from file extension) |
||||||
|
|
||||||
|
## Example Usage |
||||||
|
|
||||||
|
Once configured in Kilocode with a valid OpenAI API key: |
||||||
|
|
||||||
|
``` |
||||||
|
Can you analyze the image at /path/to/image.jpg? |
||||||
|
``` |
||||||
|
|
||||||
|
The AI will use the `describe_image_from_file` tool to provide a detailed description. |
||||||
|
|
||||||
|
## Installation Methods |
||||||
|
|
||||||
|
### Method 1: PyPI (Recommended - Once Published) |
||||||
|
|
||||||
|
```bash |
||||||
|
pip install image-recognition-mcp |
||||||
|
``` |
||||||
|
|
||||||
|
Automatically configures Kilocode! ✨ |
||||||
|
|
||||||
|
### Method 2: From Source |
||||||
|
|
||||||
|
```bash |
||||||
|
git clone https://github.com/yourusername/image-recognition-mcp.git |
||||||
|
cd image-recognition-mcp |
||||||
|
pip install -e . |
||||||
|
``` |
||||||
|
|
||||||
|
### Method 3: Using uvx (Portable) |
||||||
|
|
||||||
|
```bash |
||||||
|
uvx image-recognition-mcp |
||||||
|
``` |
||||||
|
|
||||||
|
No installation needed! Works like `npx` for Python. |
||||||
|
|
||||||
|
## Kilocode Configuration |
||||||
|
|
||||||
|
The server automatically adds this configuration: |
||||||
|
|
||||||
|
```json |
||||||
|
{ |
||||||
|
"mcpServers": { |
||||||
|
"image-recognition": { |
||||||
|
"command": "uvx", |
||||||
|
"args": ["image-recognition-mcp"], |
||||||
|
"env": { |
||||||
|
"OPENAI_API_KEY": "your-openai-api-key-here" |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
## Files Structure |
||||||
|
|
||||||
|
``` |
||||||
|
mcp-image-server/ |
||||||
|
├── run.sh # Local startup script |
||||||
|
├── requirements.txt # Python dependencies |
||||||
|
├── setup.py # Package setup (with auto-config) |
||||||
|
├── pyproject.toml # Modern Python packaging |
||||||
|
├── README.md # This file |
||||||
|
├── PUBLISHING.md # Publishing guide |
||||||
|
├── LICENSE # MIT License |
||||||
|
├── MANIFEST.in # Package manifest |
||||||
|
├── image_server.log # Server logs |
||||||
|
├── venv/ # Virtual environment (auto-created) |
||||||
|
└── image_recognition_server/ |
||||||
|
├── __init__.py |
||||||
|
├── server.py # Main server implementation |
||||||
|
└── install.py # Auto-configuration script |
||||||
|
``` |
||||||
|
|
||||||
|
## Commands |
||||||
|
|
||||||
|
After installation, these commands are available: |
||||||
|
|
||||||
|
- `image-recognition-mcp` - Start the MCP server |
||||||
|
- `image-recognition-mcp-install` - Configure Kilocode (runs automatically on install) |
||||||
|
|
||||||
|
## Dependencies |
||||||
|
|
||||||
|
- **fastmcp**: FastMCP framework for building MCP servers |
||||||
|
- **pillow**: Python Imaging Library for image processing |
||||||
|
- **openai**: OpenAI API client for Vision API |
||||||
|
|
||||||
|
## Logs |
||||||
|
|
||||||
|
Server logs are written to: |
||||||
|
`/home/enne2/Sviluppo/tetris-sdl/mcp-image-server/image_server.log` (local) |
||||||
|
|
||||||
|
Or when installed via pip: |
||||||
|
`~/.local/share/image-recognition-mcp/logs/` (system-wide) |
||||||
|
|
||||||
|
## How It Works |
||||||
|
|
||||||
|
1. **With OpenAI API Key:** |
||||||
|
- Images are encoded to base64 |
||||||
|
- Sent to OpenAI's GPT-4o-mini Vision model |
||||||
|
- Returns detailed AI-generated descriptions |
||||||
|
|
||||||
|
2. **Without OpenAI API Key:** |
||||||
|
- Falls back to basic image metadata |
||||||
|
- Returns size, color mode, and format information |
||||||
|
- Includes a note about configuring the API key |
||||||
|
|
||||||
|
## Troubleshooting |
||||||
|
|
||||||
|
### Server won't start |
||||||
|
- Check that Python 3.8+ is installed: `python3 --version` |
||||||
|
- Verify installation: `pip show image-recognition-mcp` |
||||||
|
- Check logs for errors |
||||||
|
|
||||||
|
### Automatic configuration failed |
||||||
|
- Run manually: `image-recognition-mcp-install` |
||||||
|
- Or configure manually (see PUBLISHING.md) |
||||||
|
|
||||||
|
### No AI descriptions |
||||||
|
- Verify your OpenAI API key is correctly set in MCP settings |
||||||
|
- Check that the key is valid and has credits |
||||||
|
- Review logs for API errors |
||||||
|
- The server will show a warning on startup if no valid API key is detected |
||||||
|
|
||||||
|
### Image not found |
||||||
|
- Ensure the file path is absolute |
||||||
|
- Check file permissions |
||||||
|
- Verify the file exists: `ls -la /path/to/image.jpg` |
||||||
|
|
||||||
|
## Development |
||||||
|
|
||||||
|
To modify the server: |
||||||
|
|
||||||
|
1. Clone the repository |
||||||
|
2. Install in development mode: `pip install -e .` |
||||||
|
3. Make changes to `image_recognition_server/server.py` |
||||||
|
4. Test locally: `image-recognition-mcp` |
||||||
|
|
||||||
|
## Publishing |
||||||
|
|
||||||
|
See [PUBLISHING.md](PUBLISHING.md) for instructions on publishing to PyPI. |
||||||
|
|
||||||
|
## License |
||||||
|
|
||||||
|
MIT License - see [LICENSE](LICENSE) file for details. |
||||||
|
|
||||||
|
## Contributing |
||||||
|
|
||||||
|
Contributions are welcome! Please feel free to submit a Pull Request. |
||||||
|
|
||||||
|
## Future Enhancements |
||||||
|
|
||||||
|
- Support for batch image processing |
||||||
|
- Image comparison tools |
||||||
|
- Custom vision models |
||||||
|
- Image generation capabilities |
||||||
|
- Support for more image formats |
||||||
|
- Caching for repeated image analyses |
||||||
|
- Web interface for testing |
||||||
@ -0,0 +1,2 @@ |
|||||||
|
# MCP Image Recognition Server Package |
||||||
|
from .server import mcp |
||||||
@ -0,0 +1,136 @@ |
|||||||
|
import base64 |
||||||
|
import io |
||||||
|
import logging |
||||||
|
import os |
||||||
|
from typing import Optional |
||||||
|
|
||||||
|
from PIL import Image |
||||||
|
from fastmcp import FastMCP |
||||||
|
import openai |
||||||
|
|
||||||
|
# Configure logging |
||||||
|
logging.basicConfig( |
||||||
|
level=logging.DEBUG, |
||||||
|
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', |
||||||
|
filename='/home/enne2/Sviluppo/tetris-sdl/mcp-image-server/image_server.log' |
||||||
|
) |
||||||
|
logger = logging.getLogger(__name__) |
||||||
|
|
||||||
|
# Create FastMCP server instance |
||||||
|
mcp = FastMCP("ImageRecognitionServer") |
||||||
|
|
||||||
|
# Get OpenAI API key from environment |
||||||
|
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY', '') |
||||||
|
HAS_OPENAI = bool(OPENAI_API_KEY and OPENAI_API_KEY != 'your-openai-api-key-here') |
||||||
|
|
||||||
|
if HAS_OPENAI: |
||||||
|
openai.api_key = OPENAI_API_KEY |
||||||
|
logger.info("OpenAI API key configured - AI descriptions enabled") |
||||||
|
else: |
||||||
|
logger.warning("No valid OpenAI API key - using basic image metadata only") |
||||||
|
|
||||||
|
@mcp.tool() |
||||||
|
def describe_image(image_data: str, mime_type: str = 'image/jpeg') -> str: |
||||||
|
""" |
||||||
|
Describe an image using base64 encoded image data |
||||||
|
|
||||||
|
Args: |
||||||
|
image_data: Base64 encoded image data |
||||||
|
mime_type: MIME type of the image (default: image/jpeg) |
||||||
|
|
||||||
|
Returns: |
||||||
|
Detailed description of the image |
||||||
|
""" |
||||||
|
try: |
||||||
|
logger.debug(f"Describing image - MIME type: {mime_type}") |
||||||
|
|
||||||
|
# Decode base64 image |
||||||
|
image_bytes = base64.b64decode(image_data) |
||||||
|
image = Image.open(io.BytesIO(image_bytes)) |
||||||
|
|
||||||
|
# Log image details |
||||||
|
logger.info(f"Image size: {image.size}, mode: {image.mode}") |
||||||
|
|
||||||
|
# If OpenAI is available, use Vision API |
||||||
|
if HAS_OPENAI: |
||||||
|
try: |
||||||
|
response = openai.chat.completions.create( |
||||||
|
model="gpt-4o-mini", |
||||||
|
messages=[ |
||||||
|
{ |
||||||
|
"role": "user", |
||||||
|
"content": [ |
||||||
|
{"type": "text", "text": "Describe this image in detail, including objects, colors, composition, and any text visible."}, |
||||||
|
{ |
||||||
|
"type": "image_url", |
||||||
|
"image_url": { |
||||||
|
"url": f"data:{mime_type};base64,{image_data}" |
||||||
|
} |
||||||
|
} |
||||||
|
] |
||||||
|
} |
||||||
|
], |
||||||
|
max_tokens=500 |
||||||
|
) |
||||||
|
|
||||||
|
description = response.choices[0].message.content |
||||||
|
logger.debug(f"OpenAI description: {description}") |
||||||
|
return description |
||||||
|
|
||||||
|
except Exception as e: |
||||||
|
logger.error(f"OpenAI API error: {str(e)}", exc_info=True) |
||||||
|
# Fall back to basic metadata |
||||||
|
return f"OpenAI API error: {str(e)}\n\nBasic metadata:\n- Size: {image.size[0]}x{image.size[1]} pixels\n- Mode: {image.mode}\n- Format: {image.format or 'Unknown'}" |
||||||
|
|
||||||
|
# Return basic metadata if no OpenAI |
||||||
|
description = f"Image Analysis (Basic Metadata):\n- Size: {image.size[0]}x{image.size[1]} pixels\n- Mode: {image.mode}\n- Format: {image.format or 'Unknown'}\n\nNote: For AI-powered descriptions, configure OPENAI_API_KEY in MCP settings." |
||||||
|
logger.debug(f"Returning basic description: {description}") |
||||||
|
|
||||||
|
return description |
||||||
|
|
||||||
|
except Exception as e: |
||||||
|
logger.error(f"Error describing image: {str(e)}", exc_info=True) |
||||||
|
return f"Error describing image: {str(e)}" |
||||||
|
|
||||||
|
@mcp.tool() |
||||||
|
def describe_image_from_file(file_path: str) -> str: |
||||||
|
""" |
||||||
|
Describe an image from a file path |
||||||
|
|
||||||
|
Args: |
||||||
|
file_path: Path to the image file |
||||||
|
|
||||||
|
Returns: |
||||||
|
Detailed description of the image |
||||||
|
""" |
||||||
|
try: |
||||||
|
logger.debug(f"Describing image from file: {file_path}") |
||||||
|
|
||||||
|
# Open the image file |
||||||
|
with open(file_path, 'rb') as image_file: |
||||||
|
# Encode image to base64 |
||||||
|
image_data = base64.b64encode(image_file.read()).decode('utf-8') |
||||||
|
|
||||||
|
# Determine MIME type from file extension |
||||||
|
mime_type = 'image/jpeg' |
||||||
|
if file_path.lower().endswith('.png'): |
||||||
|
mime_type = 'image/png' |
||||||
|
elif file_path.lower().endswith('.gif'): |
||||||
|
mime_type = 'image/gif' |
||||||
|
elif file_path.lower().endswith('.webp'): |
||||||
|
mime_type = 'image/webp' |
||||||
|
|
||||||
|
# Use the describe_image function |
||||||
|
return describe_image(image_data, mime_type) |
||||||
|
|
||||||
|
except Exception as e: |
||||||
|
logger.error(f"Error reading image file: {str(e)}", exc_info=True) |
||||||
|
return f"Error reading image file: {str(e)}" |
||||||
|
|
||||||
|
def main(): |
||||||
|
"""Main entry point for the MCP server.""" |
||||||
|
logger.info("Starting MCP Image Recognition Server") |
||||||
|
mcp.run() |
||||||
|
|
||||||
|
if __name__ == "__main__": |
||||||
|
main() |
||||||
@ -0,0 +1,45 @@ |
|||||||
|
[build-system] |
||||||
|
requires = ["setuptools>=61.0", "wheel"] |
||||||
|
build-backend = "setuptools.build_meta" |
||||||
|
|
||||||
|
[project] |
||||||
|
name = "image-recognition-mcp" |
||||||
|
version = "0.1.0" |
||||||
|
description = "An MCP server for AI-powered image analysis using OpenAI Vision API" |
||||||
|
readme = "README.md" |
||||||
|
requires-python = ">=3.8" |
||||||
|
license = {text = "MIT"} |
||||||
|
keywords = ["mcp", "modelcontextprotocol", "image", "vision", "openai", "ai"] |
||||||
|
authors = [ |
||||||
|
{name = "Your Name", email = "your.email@example.com"} |
||||||
|
] |
||||||
|
classifiers = [ |
||||||
|
"Development Status :: 3 - Alpha", |
||||||
|
"Intended Audience :: Developers", |
||||||
|
"Topic :: Software Development :: Libraries :: Python Modules", |
||||||
|
"License :: OSI Approved :: MIT License", |
||||||
|
"Programming Language :: Python :: 3", |
||||||
|
"Programming Language :: Python :: 3.8", |
||||||
|
"Programming Language :: Python :: 3.9", |
||||||
|
"Programming Language :: Python :: 3.10", |
||||||
|
"Programming Language :: Python :: 3.11", |
||||||
|
"Programming Language :: Python :: 3.12", |
||||||
|
] |
||||||
|
dependencies = [ |
||||||
|
"fastmcp>=2.0.0", |
||||||
|
"pillow>=10.0.0", |
||||||
|
"openai>=1.0.0", |
||||||
|
] |
||||||
|
|
||||||
|
[project.urls] |
||||||
|
Homepage = "https://github.com/yourusername/image-recognition-mcp" |
||||||
|
Repository = "https://github.com/yourusername/image-recognition-mcp" |
||||||
|
Issues = "https://github.com/yourusername/image-recognition-mcp/issues" |
||||||
|
|
||||||
|
[project.scripts] |
||||||
|
image-recognition-mcp = "image_recognition_server.server:main" |
||||||
|
image-recognition-mcp-install = "image_recognition_server.install:main" |
||||||
|
|
||||||
|
[tool.setuptools.packages.find] |
||||||
|
where = ["."] |
||||||
|
include = ["image_recognition_server*"] |
||||||
@ -0,0 +1,60 @@ |
|||||||
|
from setuptools import setup, find_packages |
||||||
|
from setuptools.command.install import install |
||||||
|
import subprocess |
||||||
|
import sys |
||||||
|
|
||||||
|
with open("README.md", "r", encoding="utf-8") as fh: |
||||||
|
long_description = fh.read() |
||||||
|
|
||||||
|
|
||||||
|
class PostInstallCommand(install): |
||||||
|
"""Post-installation for installation mode.""" |
||||||
|
def run(self): |
||||||
|
install.run(self) |
||||||
|
# Run the configuration script |
||||||
|
try: |
||||||
|
subprocess.check_call([sys.executable, "-m", "image_recognition_server.install"]) |
||||||
|
except Exception as e: |
||||||
|
print(f"Note: Automatic configuration failed: {e}") |
||||||
|
print("You can manually configure by running: image-recognition-mcp-install") |
||||||
|
|
||||||
|
|
||||||
|
setup( |
||||||
|
name="image-recognition-mcp", |
||||||
|
version="0.1.0", |
||||||
|
author="Your Name", |
||||||
|
author_email="your.email@example.com", |
||||||
|
description="An MCP server for AI-powered image analysis using OpenAI Vision API", |
||||||
|
long_description=long_description, |
||||||
|
long_description_content_type="text/markdown", |
||||||
|
url="https://github.com/yourusername/image-recognition-mcp", |
||||||
|
packages=find_packages(), |
||||||
|
classifiers=[ |
||||||
|
"Development Status :: 3 - Alpha", |
||||||
|
"Intended Audience :: Developers", |
||||||
|
"Topic :: Software Development :: Libraries :: Python Modules", |
||||||
|
"License :: OSI Approved :: MIT License", |
||||||
|
"Programming Language :: Python :: 3", |
||||||
|
"Programming Language :: Python :: 3.8", |
||||||
|
"Programming Language :: Python :: 3.9", |
||||||
|
"Programming Language :: Python :: 3.10", |
||||||
|
"Programming Language :: Python :: 3.11", |
||||||
|
"Programming Language :: Python :: 3.12", |
||||||
|
], |
||||||
|
python_requires=">=3.8", |
||||||
|
install_requires=[ |
||||||
|
"fastmcp>=2.0.0", |
||||||
|
"pillow>=10.0.0", |
||||||
|
"openai>=1.0.0", |
||||||
|
], |
||||||
|
entry_points={ |
||||||
|
"console_scripts": [ |
||||||
|
"image-recognition-mcp=image_recognition_server.server:main", |
||||||
|
"image-recognition-mcp-install=image_recognition_server.install:main", |
||||||
|
], |
||||||
|
}, |
||||||
|
cmdclass={ |
||||||
|
'install': PostInstallCommand, |
||||||
|
}, |
||||||
|
keywords=["mcp", "modelcontextprotocol", "image", "vision", "openai", "ai"], |
||||||
|
) |
||||||
Loading…
Reference in new issue