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