first commit
This commit is contained in:
Matteo Benedetto
+210
@@ -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
|
||||||
+200
@@ -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,109 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Post-installation script to automatically configure Kilocode MCP settings.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
|
||||||
|
def get_kilocode_config_path():
|
||||||
|
"""Find the Kilocode MCP settings file."""
|
||||||
|
# Common paths for Kilocode/VSCodium
|
||||||
|
possible_paths = [
|
||||||
|
Path.home() / ".config/VSCodium/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
|
||||||
|
Path.home() / ".config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
|
||||||
|
Path.home() / "Library/Application Support/VSCodium/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
|
||||||
|
Path.home() / "Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
|
||||||
|
]
|
||||||
|
|
||||||
|
for path in possible_paths:
|
||||||
|
if path.exists():
|
||||||
|
return path
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def add_to_kilocode_config():
|
||||||
|
"""Add the image-recognition server to Kilocode's MCP settings."""
|
||||||
|
config_path = get_kilocode_config_path()
|
||||||
|
|
||||||
|
if not config_path:
|
||||||
|
print("⚠️ Kilocode MCP settings file not found.")
|
||||||
|
print(" You'll need to manually add the server configuration.")
|
||||||
|
print("\n Add this to your MCP settings:")
|
||||||
|
print(json.dumps({
|
||||||
|
"image-recognition": {
|
||||||
|
"command": "uvx",
|
||||||
|
"args": ["image-recognition-mcp"],
|
||||||
|
"env": {
|
||||||
|
"OPENAI_API_KEY": "your-openai-api-key-here"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}, indent=2))
|
||||||
|
return False
|
||||||
|
|
||||||
|
try:
|
||||||
|
# Read existing config
|
||||||
|
with open(config_path, 'r') as f:
|
||||||
|
config = json.load(f)
|
||||||
|
|
||||||
|
# Ensure mcpServers exists
|
||||||
|
if "mcpServers" not in config:
|
||||||
|
config["mcpServers"] = {}
|
||||||
|
|
||||||
|
# Check if already configured
|
||||||
|
if "image-recognition" in config["mcpServers"]:
|
||||||
|
print("✅ Image Recognition MCP server already configured in Kilocode")
|
||||||
|
return True
|
||||||
|
|
||||||
|
# Add our server
|
||||||
|
config["mcpServers"]["image-recognition"] = {
|
||||||
|
"command": "uvx",
|
||||||
|
"args": ["image-recognition-mcp"],
|
||||||
|
"env": {
|
||||||
|
"OPENAI_API_KEY": "your-openai-api-key-here"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Backup original config
|
||||||
|
backup_path = config_path.with_suffix('.json.backup')
|
||||||
|
with open(backup_path, 'w') as f:
|
||||||
|
json.dump(config, f, indent=2)
|
||||||
|
|
||||||
|
# Write updated config
|
||||||
|
with open(config_path, 'w') as f:
|
||||||
|
json.dump(config, f, indent=2)
|
||||||
|
|
||||||
|
print("✅ Successfully added Image Recognition MCP server to Kilocode!")
|
||||||
|
print(f" Config file: {config_path}")
|
||||||
|
print(f" Backup saved: {backup_path}")
|
||||||
|
print("\n⚠️ Remember to:")
|
||||||
|
print(" 1. Replace 'your-openai-api-key-here' with your actual OpenAI API key")
|
||||||
|
print(" 2. Restart Kilocode to load the new server")
|
||||||
|
|
||||||
|
return True
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
print(f"❌ Error updating Kilocode config: {e}")
|
||||||
|
return False
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
"""Main entry point for the installer."""
|
||||||
|
print("🚀 Image Recognition MCP Server - Post-Install Configuration")
|
||||||
|
print("=" * 60)
|
||||||
|
|
||||||
|
if add_to_kilocode_config():
|
||||||
|
print("\n✨ Installation complete!")
|
||||||
|
else:
|
||||||
|
print("\n⚠️ Manual configuration required.")
|
||||||
|
print(" See PUBLISHING.md for instructions.")
|
||||||
|
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sys.exit(main())
|
||||||
@@ -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,5 @@
|
|||||||
|
fastmcp
|
||||||
|
pillow
|
||||||
|
python-multipart
|
||||||
|
uvicorn
|
||||||
|
openai
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# MCP Image Recognition Server Startup Script
|
||||||
|
# This script sets up the environment and starts the server
|
||||||
|
|
||||||
|
set -e # Exit on error
|
||||||
|
|
||||||
|
# Get the directory where this script is located
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
cd "$SCRIPT_DIR"
|
||||||
|
|
||||||
|
echo "🚀 Starting MCP Image Recognition Server..."
|
||||||
|
echo "📁 Working directory: $SCRIPT_DIR"
|
||||||
|
|
||||||
|
# Check if virtual environment exists
|
||||||
|
if [ ! -d "venv" ]; then
|
||||||
|
echo "📦 Virtual environment not found. Creating..."
|
||||||
|
python3 -m venv venv
|
||||||
|
echo "✅ Virtual environment created"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Activate virtual environment
|
||||||
|
echo "🔧 Activating virtual environment..."
|
||||||
|
source venv/bin/activate
|
||||||
|
|
||||||
|
# Check if dependencies are installed
|
||||||
|
if ! python -c "import fastmcp" 2>/dev/null; then
|
||||||
|
echo "📥 Installing dependencies..."
|
||||||
|
pip install -q -r requirements.txt
|
||||||
|
echo "✅ Dependencies installed"
|
||||||
|
else
|
||||||
|
echo "✅ Dependencies already installed"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check for OpenAI API key
|
||||||
|
if [ -z "$OPENAI_API_KEY" ] || [ "$OPENAI_API_KEY" = "your-openai-api-key-here" ]; then
|
||||||
|
echo "⚠️ Warning: OPENAI_API_KEY not set or using placeholder"
|
||||||
|
echo " Server will run with basic image metadata only"
|
||||||
|
echo " To enable AI descriptions, set OPENAI_API_KEY environment variable"
|
||||||
|
else
|
||||||
|
echo "✅ OpenAI API key configured"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Start the server
|
||||||
|
echo "🎯 Starting server..."
|
||||||
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
|
python -m image_recognition_server.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"],
|
||||||
|
)
|
||||||
Reference in New Issue
Block a user