farshid-mcp-imageprocessing 0.2.1__tar.gz

farshid_mcp_imageprocessing-0.2.1/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+.farshid/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / runtime output
+test_output/
+
+# OS / editor cruft
+.DS_Store
+Thumbs.db
+*.swp
+.idea/
+

farshid_mcp_imageprocessing-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Farshid Pirahansiah
+
+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.

farshid_mcp_imageprocessing-0.2.1/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: farshid-mcp-imageprocessing
+Version: 0.2.1
+Summary: Local offline OpenCV-based image-processing MCP server: webcam capture, image transforms, edges, contours, face/QR detection, video, and ~40 tools.
+Project-URL: Homepage, https://github.com/pirahansiah/farshid-mcp-imageProcessing
+Project-URL: Repository, https://github.com/pirahansiah/farshid-mcp-imageProcessing
+Project-URL: Issues, https://github.com/pirahansiah/farshid-mcp-imageProcessing/issues
+Author: Farshid Pirahansiah
+License: MIT
+License-File: LICENSE
+Keywords: computer-vision,image-processing,mcp,model-context-protocol,opencv,webcam
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.18.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: opencv-contrib-python>=4.10.0
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.pirahansiah/farshid-mcp-imageProcessing -->
+
+# farshid-mcp-imageProcessing
+
+A comprehensive **OpenCV image-processing MCP server** for VS Code Copilot
+Agent Mode (or any MCP client). Exposes ~40 tools across webcam capture, image
+I/O, transforms, color, filtering, edges, thresholding, morphology,
+contours/shapes, feature matching, object detection (faces / eyes / bodies /
+QR), drawing, image arithmetic, template matching, and video processing.
+
+- **PyPI:** [`farshid-mcp-imageProcessing`](https://pypi.org/project/farshid-mcp-imageProcessing/)
+- **MCP Registry:** `io.github.pirahansiah/farshid-mcp-imageProcessing`
+- **Python:** 3.14+
+- **OS:** latest Windows 11, latest macOS, latest mainstream Linux (Ubuntu 24.04+/Fedora 41+)
+
+## Install (PyPI)
+
+```bash
+pip install farshid-mcp-imageProcessing
+farshid-mcp-imageprocessing          # runs the stdio MCP server
+```
+
+## Register in VS Code
+
+Add this to your user or workspace `mcp.json`:
+
+```jsonc
+{
+  "servers": {
+    "imageProcessing": {
+      "command": "farshid-mcp-imageprocessing",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Or, if you cloned the repo and want to run from source with the local `.venv`:
+
+```bash
+git clone https://github.com/pirahansiah/farshid-mcp-imageProcessing
+cd farshid-mcp-imageProcessing
+# Windows (PowerShell):
+py -3.14 -m venv .venv ; .\.venv\Scripts\Activate.ps1
+# macOS / Linux:
+python3.14 -m venv .venv && source .venv/bin/activate
+
+pip install -U pip
+pip install -e .
+```
+
+`opencv-contrib-python` is used so the bundled Haar cascades and extra
+algorithms are available.
+
+## Quick start: the `/cv` Copilot prompt
+
+This repo ships a workspace prompt file at
+[.github/prompts/cv.prompt.md](.github/prompts/cv.prompt.md). In VS Code
+Copilot Chat (Agent mode), type:
+
+```
+/cv take image from webcam and save it as gray scale 240 * 240
+```
+
+The agent will call `webcam_save`, `image_to_grayscale`, and `image_resize`
+from this server to produce the requested file under `./.farshid/cv/`.
+
+## Tool catalog
+
+### Webcam / capture
+- `webcam_capture(camera_index=0)` → returns a PNG image
+- `webcam_save(output_path="", camera_index=0)`
+- `webcam_preview(camera_index=0, seconds=10)` (local desktop window)
+- `webcam_record(output_path, seconds=5, camera_index=0, fps=20)`
+
+### Image I/O & info
+- `image_show(path)` — return image to chat
+- `image_info(path)` — shape, dtype, mean, file size
+- `image_convert(input_path, output_path, quality=95)`
+
+### Geometric transforms
+- `image_resize(... width|height|scale, interpolation)`
+- `image_crop(input_path, output_path, x, y, width, height)`
+- `image_rotate(input_path, output_path, angle, scale=1, keep_size=False)`
+- `image_flip(input_path, output_path, direction)`
+- `image_pad(... top, bottom, left, right, border_type, color)`
+
+### Color
+- `image_to_grayscale`
+- `color_convert(target=gray|hsv|hls|lab|ycrcb|rgb|bgr)`
+- `adjust_brightness_contrast`
+- `histogram_equalize(method=clahe|global)`
+- `histogram_data(bins=32)`
+
+### Filtering
+- `blur_gaussian(ksize, sigma)`
+- `blur_median(ksize)`
+- `blur_bilateral(d, sigma_color, sigma_space)`
+- `sharpen(amount)`
+- `denoise(strength)`
+
+### Edges / gradients
+- `edges_canny(threshold1, threshold2)`
+- `edges_sobel(ksize)`
+- `edges_laplacian(ksize)`
+
+### Thresholding & morphology
+- `threshold(method=otsu|binary|binary_inv|adaptive_mean|adaptive_gaussian)`
+- `morphology(op=erode|dilate|open|close|gradient|tophat|blackhat)`
+
+### Contours & shapes
+- `find_contours(input_path, output_path?, thresh, min_area)`
+- `detect_circles(...)` — Hough
+- `detect_lines(...)` — Probabilistic Hough
+- `detect_corners(...)` — Shi-Tomasi
+
+### Feature matching
+- `feature_match(image1, image2, output_path?)` — ORB + BFMatcher
+
+### Object detection (Haar)
+- `detect_faces`
+- `detect_eyes`
+- `detect_bodies`
+- `detect_qrcode`
+
+### Drawing
+- `draw_rectangle`, `draw_circle`, `draw_line`, `draw_text`
+
+### Composition / arithmetic
+- `image_blend(image1, image2, output_path, alpha)`
+- `image_diff(image1, image2, output_path?)` → mean/max diff
+- `image_concat(images, output_path, direction)`
+- `template_match(image_path, template_path, output_path?, threshold)`
+
+### Video
+- `video_info(path)`
+- `video_extract_frames(video_path, output_dir, every_n, max_frames, ext)`
+- `video_thumbnail(video_path, output_path, time_seconds)`
+
+## Build & publish
+
+```bash
+pip install -U build twine mcp-publisher
+python -m build
+twine upload dist/*
+mcp-publisher login github
+mcp-publisher publish .mcp/server.json
+```
+
+## OS notes
+
+- **Windows 11 (latest):** webcam works out of the box; ensure *Settings →
+  Privacy & security → Camera → Let desktop apps access your camera* is **On**.
+- **macOS (latest):** the first webcam call triggers a system Camera
+  permission prompt; grant it to the terminal/VS Code process.
+- **Linux (latest):** requires a working `/dev/video*` device. Headless
+  servers without a display cannot use `webcam_preview` (it opens an OpenCV
+  window).
+
+## Notes
+
+- Never use `print()` in tool functions: stdout is the MCP protocol channel.
+  Use `sys.stderr` (the `_log` helper at the bottom of `server.py`).
+- `webcam_preview` opens a real desktop window — only works where the server
+  has a display (not over plain SSH or in a headless container).
+- All paths support `~` expansion. Output directories are created
+  automatically.
+- Tools that return annotated images take an optional `output_path`; when
+  omitted they only return the JSON metadata.

farshid_mcp_imageprocessing-0.2.1/README.md

@@ -0,0 +1,169 @@
+<!-- mcp-name: io.github.pirahansiah/farshid-mcp-imageProcessing -->
+
+# farshid-mcp-imageProcessing
+
+A comprehensive **OpenCV image-processing MCP server** for VS Code Copilot
+Agent Mode (or any MCP client). Exposes ~40 tools across webcam capture, image
+I/O, transforms, color, filtering, edges, thresholding, morphology,
+contours/shapes, feature matching, object detection (faces / eyes / bodies /
+QR), drawing, image arithmetic, template matching, and video processing.
+
+- **PyPI:** [`farshid-mcp-imageProcessing`](https://pypi.org/project/farshid-mcp-imageProcessing/)
+- **MCP Registry:** `io.github.pirahansiah/farshid-mcp-imageProcessing`
+- **Python:** 3.14+
+- **OS:** latest Windows 11, latest macOS, latest mainstream Linux (Ubuntu 24.04+/Fedora 41+)
+
+## Install (PyPI)
+
+```bash
+pip install farshid-mcp-imageProcessing
+farshid-mcp-imageprocessing          # runs the stdio MCP server
+```
+
+## Register in VS Code
+
+Add this to your user or workspace `mcp.json`:
+
+```jsonc
+{
+  "servers": {
+    "imageProcessing": {
+      "command": "farshid-mcp-imageprocessing",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Or, if you cloned the repo and want to run from source with the local `.venv`:
+
+```bash
+git clone https://github.com/pirahansiah/farshid-mcp-imageProcessing
+cd farshid-mcp-imageProcessing
+# Windows (PowerShell):
+py -3.14 -m venv .venv ; .\.venv\Scripts\Activate.ps1
+# macOS / Linux:
+python3.14 -m venv .venv && source .venv/bin/activate
+
+pip install -U pip
+pip install -e .
+```
+
+`opencv-contrib-python` is used so the bundled Haar cascades and extra
+algorithms are available.
+
+## Quick start: the `/cv` Copilot prompt
+
+This repo ships a workspace prompt file at
+[.github/prompts/cv.prompt.md](.github/prompts/cv.prompt.md). In VS Code
+Copilot Chat (Agent mode), type:
+
+```
+/cv take image from webcam and save it as gray scale 240 * 240
+```
+
+The agent will call `webcam_save`, `image_to_grayscale`, and `image_resize`
+from this server to produce the requested file under `./.farshid/cv/`.
+
+## Tool catalog
+
+### Webcam / capture
+- `webcam_capture(camera_index=0)` → returns a PNG image
+- `webcam_save(output_path="", camera_index=0)`
+- `webcam_preview(camera_index=0, seconds=10)` (local desktop window)
+- `webcam_record(output_path, seconds=5, camera_index=0, fps=20)`
+
+### Image I/O & info
+- `image_show(path)` — return image to chat
+- `image_info(path)` — shape, dtype, mean, file size
+- `image_convert(input_path, output_path, quality=95)`
+
+### Geometric transforms
+- `image_resize(... width|height|scale, interpolation)`
+- `image_crop(input_path, output_path, x, y, width, height)`
+- `image_rotate(input_path, output_path, angle, scale=1, keep_size=False)`
+- `image_flip(input_path, output_path, direction)`
+- `image_pad(... top, bottom, left, right, border_type, color)`
+
+### Color
+- `image_to_grayscale`
+- `color_convert(target=gray|hsv|hls|lab|ycrcb|rgb|bgr)`
+- `adjust_brightness_contrast`
+- `histogram_equalize(method=clahe|global)`
+- `histogram_data(bins=32)`
+
+### Filtering
+- `blur_gaussian(ksize, sigma)`
+- `blur_median(ksize)`
+- `blur_bilateral(d, sigma_color, sigma_space)`
+- `sharpen(amount)`
+- `denoise(strength)`
+
+### Edges / gradients
+- `edges_canny(threshold1, threshold2)`
+- `edges_sobel(ksize)`
+- `edges_laplacian(ksize)`
+
+### Thresholding & morphology
+- `threshold(method=otsu|binary|binary_inv|adaptive_mean|adaptive_gaussian)`
+- `morphology(op=erode|dilate|open|close|gradient|tophat|blackhat)`
+
+### Contours & shapes
+- `find_contours(input_path, output_path?, thresh, min_area)`
+- `detect_circles(...)` — Hough
+- `detect_lines(...)` — Probabilistic Hough
+- `detect_corners(...)` — Shi-Tomasi
+
+### Feature matching
+- `feature_match(image1, image2, output_path?)` — ORB + BFMatcher
+
+### Object detection (Haar)
+- `detect_faces`
+- `detect_eyes`
+- `detect_bodies`
+- `detect_qrcode`
+
+### Drawing
+- `draw_rectangle`, `draw_circle`, `draw_line`, `draw_text`
+
+### Composition / arithmetic
+- `image_blend(image1, image2, output_path, alpha)`
+- `image_diff(image1, image2, output_path?)` → mean/max diff
+- `image_concat(images, output_path, direction)`
+- `template_match(image_path, template_path, output_path?, threshold)`
+
+### Video
+- `video_info(path)`
+- `video_extract_frames(video_path, output_dir, every_n, max_frames, ext)`
+- `video_thumbnail(video_path, output_path, time_seconds)`
+
+## Build & publish
+
+```bash
+pip install -U build twine mcp-publisher
+python -m build
+twine upload dist/*
+mcp-publisher login github
+mcp-publisher publish .mcp/server.json
+```
+
+## OS notes
+
+- **Windows 11 (latest):** webcam works out of the box; ensure *Settings →
+  Privacy & security → Camera → Let desktop apps access your camera* is **On**.
+- **macOS (latest):** the first webcam call triggers a system Camera
+  permission prompt; grant it to the terminal/VS Code process.
+- **Linux (latest):** requires a working `/dev/video*` device. Headless
+  servers without a display cannot use `webcam_preview` (it opens an OpenCV
+  window).
+
+## Notes
+
+- Never use `print()` in tool functions: stdout is the MCP protocol channel.
+  Use `sys.stderr` (the `_log` helper at the bottom of `server.py`).
+- `webcam_preview` opens a real desktop window — only works where the server
+  has a display (not over plain SSH or in a headless container).
+- All paths support `~` expansion. Output directories are created
+  automatically.
+- Tools that return annotated images take an optional `output_path`; when
+  omitted they only return the JSON metadata.

farshid_mcp_imageprocessing-0.2.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "farshid-mcp-imageprocessing"
+version = "0.2.1"
+description = "Local offline OpenCV-based image-processing MCP server: webcam capture, image transforms, edges, contours, face/QR detection, video, and ~40 tools."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Farshid Pirahansiah" }
+]
+keywords = ["mcp", "model-context-protocol", "opencv", "computer-vision", "image-processing", "webcam"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: Microsoft :: Windows :: Windows 11",
+  "Operating System :: MacOS :: MacOS X",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+  "mcp[cli]>=1.18.0",
+  "opencv-contrib-python>=4.10.0",
+  "numpy>=1.26",
+]
+
+[project.urls]
+Homepage = "https://github.com/pirahansiah/farshid-mcp-imageProcessing"
+Repository = "https://github.com/pirahansiah/farshid-mcp-imageProcessing"
+Issues = "https://github.com/pirahansiah/farshid-mcp-imageProcessing/issues"
+
+[project.scripts]
+farshid-mcp-imageprocessing = "farshid_mcp_imageprocessing.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/farshid_mcp_imageprocessing"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/farshid_mcp_imageprocessing",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+]

farshid_mcp_imageprocessing-0.2.1/src/farshid_mcp_imageprocessing/__init__.py

@@ -0,0 +1,2 @@
+"""farshid-mcp-imageProcessing — local offline OpenCV image-processing MCP server."""
+__version__ = "0.2.0"

farshid_mcp_imageprocessing-0.2.1/src/farshid_mcp_imageprocessing/cv_helpers.py

@@ -0,0 +1,100 @@
+"""Shared helpers for the OpenCV MCP server."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Tuple
+
+import cv2
+import numpy as np
+from mcp.server.fastmcp import Image
+
+
+# ---------- I/O ----------
+
+def read_image(path: str, flag: int = cv2.IMREAD_UNCHANGED) -> np.ndarray:
+    """Read an image from disk, raising a clear error on failure."""
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise FileNotFoundError(f"Image not found: {p}")
+    img = cv2.imread(str(p), flag)
+    if img is None:
+        raise RuntimeError(f"OpenCV could not decode image: {p}")
+    return img
+
+
+def write_image(path: str, img: np.ndarray) -> Path:
+    """Write an image, creating parent dirs."""
+    p = Path(path).expanduser()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    ok = cv2.imwrite(str(p), img)
+    if not ok:
+        raise RuntimeError(f"OpenCV could not write image: {p}")
+    return p
+
+
+def to_mcp_image(img: np.ndarray, fmt: str = "png") -> Image:
+    """Encode an ndarray as an MCP Image payload."""
+    fmt = fmt.lower().lstrip(".")
+    ext = "." + fmt
+    ok, buf = cv2.imencode(ext, img)
+    if not ok:
+        raise RuntimeError(f"Could not encode image as {fmt}")
+    return Image(data=buf.tobytes(), format=fmt)
+
+
+# ---------- Webcam ----------
+
+def grab_frame(camera_index: int = 0, warmup_frames: int = 2) -> np.ndarray:
+    """Open webcam, discard a few warmup frames, return one frame."""
+    cap = cv2.VideoCapture(camera_index)
+    try:
+        if not cap.isOpened():
+            raise RuntimeError(
+                f"Could not open webcam at camera_index={camera_index}. "
+                "Check OS camera permissions and whether another app is using it."
+            )
+        frame = None
+        for _ in range(max(1, warmup_frames + 1)):
+            ok, frame = cap.read()
+            if not ok or frame is None:
+                raise RuntimeError("Webcam opened, but no frame could be read.")
+        return frame
+    finally:
+        cap.release()
+
+
+# ---------- Geometry / parsing ----------
+
+def parse_color(color: "str | Tuple[int, int, int]") -> Tuple[int, int, int]:
+    """Accept '#rrggbb', 'r,g,b', or tuple. Returns BGR for OpenCV."""
+    if isinstance(color, (tuple, list)) and len(color) == 3:
+        r, g, b = [int(c) for c in color]
+        return (b, g, r)
+    s = str(color).strip()
+    if s.startswith("#") and len(s) == 7:
+        r = int(s[1:3], 16); g = int(s[3:5], 16); b = int(s[5:7], 16)
+        return (b, g, r)
+    parts = [p.strip() for p in s.split(",")]
+    if len(parts) == 3:
+        r, g, b = [int(p) for p in parts]
+        return (b, g, r)
+    raise ValueError(f"Cannot parse color: {color!r}")
+
+
+def ensure_bgr(img: np.ndarray) -> np.ndarray:
+    """Convert grayscale or BGRA to 3-channel BGR."""
+    if img.ndim == 2:
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    if img.shape[2] == 4:
+        return cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
+    return img
+
+
+def odd(n: int, minimum: int = 1) -> int:
+    """Force value to an odd integer >= minimum (kernel sizes need odd)."""
+    n = int(n)
+    if n < minimum:
+        n = minimum
+    if n % 2 == 0:
+        n += 1
+    return n