label-image-mcp 0.1.0__tar.gz

label_image_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra agent
+      - run: uv run pytest -q

label_image_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+# Push a tag like v0.1.0 (matching the version in pyproject.toml, server.json
+# and manifest.json) to publish to PyPI and the MCP Registry, and attach the
+# Claude Desktop extension (.mcpb) to a GitHub release.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Check tag matches package version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match version $version" >&2
+            exit 1
+          fi
+      - run: uv sync --extra agent
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx -y @anthropic-ai/mcpb pack . dist-mcpb/label-image-mcp.mcpb
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: |
+            dist/
+            dist-mcpb/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # GitHub OIDC login for the io.github.sachinbkale27 namespace
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
+      - name: Publish to MCP Registry
+        run: |
+          ./mcp-publisher login github-oidc
+          # The registry verifies the package on PyPI, which can take a minute to appear
+          for attempt in 1 2 3 4 5; do
+            ./mcp-publisher publish && exit 0
+            sleep 30
+          done
+          exit 1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+      - run: gh release create "$GITHUB_REF_NAME" dist-mcpb/label-image-mcp.mcpb dist/* --repo "$GITHUB_REPOSITORY" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

label_image_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+.pytest_cache/
+dist/

label_image_mcp-0.1.0/.mcpbignore

@@ -0,0 +1,7 @@
+.venv/
+.pytest_cache/
+__pycache__/
+dist/
+tests/
+.github/
+*.mcpb

label_image_mcp-0.1.0/LICENSE

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

label_image_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: label-image-mcp
+Version: 0.1.0
+Summary: MCP server and LangGraph agent for the Image Label annotation app (labels.sachin-kale.com)
+Project-URL: Homepage, https://labels.sachin-kale.com/mcp
+Project-URL: Source, https://github.com/sachinbkale27/label-image-mcp
+Project-URL: Issues, https://github.com/sachinbkale27/label-image-mcp/issues
+Author: Sachin Kale
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coco,histopathology,image-annotation,langgraph,mcp,model-context-protocol,yolo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: agent
+Requires-Dist: langchain-anthropic>=1.0; extra == 'agent'
+Requires-Dist: langchain-mcp-adapters>=0.3; extra == 'agent'
+Requires-Dist: langchain>=1.4; extra == 'agent'
+Requires-Dist: langgraph>=1.2; extra == 'agent'
+Description-Content-Type: text/markdown
+
+# Image Label MCP server
+
+<!-- mcp-name: io.github.sachinbkale27/label-image-mcp -->
+
+An [MCP](https://modelcontextprotocol.io) server for [Image Label](https://labels.sachin-kale.com),
+a free image annotation tool. It lets Claude and other AI assistants list and upload your images,
+add or clean up annotations, and export COCO or YOLO training data. A LangGraph agent is included.
+
+Use cases and setup guide: https://labels.sachin-kale.com/mcp
+
+```
+LangGraph agent (label-image-agent)      Claude Desktop / Claude Code / any MCP client
+              │  langchain-mcp-adapters             │
+              └──────────────┬──────────────────────┘
+                             ▼
+                    label-image-mcp (stdio or HTTP)
+                             │
+                             ▼
+                 Image Label API  (/api/images ...)
+```
+
+## Account
+
+Uploading and saving annotations needs an Image Label account
+([request one](https://labels.sachin-kale.com/contact)). Without one, the tools can read but not
+save. Only images saved to your account are visible. Work kept only in your browser is not.
+
+## Install
+
+**Claude Desktop:** download `label-image-mcp.mcpb` from the
+[latest release](https://github.com/sachinbkale27/label-image-mcp/releases/latest), open it, and
+enter your username and password when asked.
+
+**Claude Code:**
+
+```bash
+claude mcp add label-image -e LABEL_USERNAME=... -e LABEL_PASSWORD=... -- uvx label-image-mcp
+```
+
+**Any MCP client** (needs [uv](https://docs.astral.sh/uv/)):
+
+```json
+{
+  "mcpServers": {
+    "label-image": {
+      "command": "uvx",
+      "args": ["label-image-mcp"],
+      "env": { "LABEL_USERNAME": "...", "LABEL_PASSWORD": "..." }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LABEL_USERNAME` / `LABEL_PASSWORD` | unset | Account credentials. Without them requests are anonymous and read-only in practice |
+| `LABEL_API_URL` | `https://labels.sachin-kale.com/api` | API base URL, for another deployment or `sam local start-api` |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_images(category?)` | Image summaries with annotation counts |
+| `get_image(image_id)` | Metadata, annotations and a signed viewing URL |
+| `update_image_metadata(image_id, name?, category?, sub_category?, description?)` | Edit image details |
+| `add_annotations(image_id, annotations)` | Append pins, polygons, circles, rectangles or arrows |
+| `replace_annotations(image_id, annotations)` | Replace all annotations |
+| `remove_annotations(image_id, annotation_ids)` | Remove annotations by id |
+| `upload_image(path, name?, category?, description?)` | Upload a local image file |
+| `export_annotations(image_id, format)` | COCO JSON or YOLO, same output as the web app's export |
+
+There is deliberately no tool for deleting images.
+
+## HTTP mode
+
+`label-image-mcp --http [--host 127.0.0.1] [--port 8765]` serves Streamable HTTP at
+`http://HOST:PORT/mcp`, so several clients can share one running server:
+
+```bash
+claude mcp add --transport http label-image http://127.0.0.1:8765/mcp
+```
+
+## LangGraph agent
+
+A terminal chat agent that uses these tools. The graph is `START → agent ⇄ tools`, with
+conversation memory kept for the session.
+
+```bash
+uv tool install "label-image-mcp[agent]"
+export ANTHROPIC_API_KEY=... LABEL_USERNAME=... LABEL_PASSWORD=...
+label-image-agent
+```
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LABEL_AGENT_MODEL` | `anthropic:claude-sonnet-5-5` | Model as `provider:model`, e.g. `openai:gpt-4.1` or `ollama:llama3.1` (install `langchain-openai` / `langchain-ollama`) |
+| `LABEL_MCP_URL` | unset | Connect to a running HTTP server instead of starting one |
+
+## Development
+
+```bash
+uv sync --extra agent
+uv run pytest
+npx @modelcontextprotocol/inspector uv run label-image-mcp
+```
+
+In the Image Label app repo, `./start.sh` runs this server in HTTP mode next to the web app.
+It reads credentials from `mcp-server/.env`. Releases are described in [PUBLISHING.md](PUBLISHING.md).
+
+## License
+
+MIT

label_image_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,37 @@
+# Publishing
+
+The source of truth is `mcp-server/` in the private `label-image` repo. The public repo
+`sachinbkale27/label-image-mcp` gets that folder's history via `git subtree`:
+
+```bash
+# from the label-image repo root
+git subtree push --prefix mcp-server mcp-public main
+```
+
+(`mcp-public` is a git remote pointing at https://github.com/sachinbkale27/label-image-mcp.git)
+
+## One-time setup
+
+1. **PyPI trusted publisher:** on https://pypi.org/manage/account/publishing/ add a pending
+   publisher: project `label-image-mcp`, owner `sachinbkale27`, repo `label-image-mcp`,
+   workflow `release.yml`, environment `pypi`.
+2. **GitHub environment:** in the public repo, Settings → Environments → create `pypi`.
+3. **MCP Registry:** nothing to set up. The release workflow logs in with GitHub OIDC, which
+   owns the `io.github.sachinbkale27/*` namespace.
+
+## Release
+
+1. Bump the version in `pyproject.toml`, `server.json` (both `version` fields) and
+   `manifest.json`. `tests/test_metadata.py` fails if they disagree.
+2. Push with `git subtree push` (above), then tag the public repo:
+   `git tag v0.1.1 && git push mcp-public v0.1.1`, or create the tag on GitHub.
+3. The `Release` workflow tests, publishes to PyPI, publishes `server.json` to the MCP Registry,
+   and attaches the `.mcpb` Claude Desktop extension to a GitHub release.
+
+## Directories (one-time, manual)
+
+- **Glama** (https://glama.ai/mcp/servers): indexes public GitHub repos. `glama.json` claims the
+  listing for `sachinbkale27`.
+- **Smithery** (https://smithery.ai): add the server from the public GitHub repo on the site.
+- **mcp.so** (https://mcp.so/submit) and **PulseMCP** (https://www.pulsemcp.com/submit): submit
+  the GitHub URL. PulseMCP also imports from the MCP Registry.

label_image_mcp-0.1.0/README.md

@@ -0,0 +1,114 @@
+# Image Label MCP server
+
+<!-- mcp-name: io.github.sachinbkale27/label-image-mcp -->
+
+An [MCP](https://modelcontextprotocol.io) server for [Image Label](https://labels.sachin-kale.com),
+a free image annotation tool. It lets Claude and other AI assistants list and upload your images,
+add or clean up annotations, and export COCO or YOLO training data. A LangGraph agent is included.
+
+Use cases and setup guide: https://labels.sachin-kale.com/mcp
+
+```
+LangGraph agent (label-image-agent)      Claude Desktop / Claude Code / any MCP client
+              │  langchain-mcp-adapters             │
+              └──────────────┬──────────────────────┘
+                             ▼
+                    label-image-mcp (stdio or HTTP)
+                             │
+                             ▼
+                 Image Label API  (/api/images ...)
+```
+
+## Account
+
+Uploading and saving annotations needs an Image Label account
+([request one](https://labels.sachin-kale.com/contact)). Without one, the tools can read but not
+save. Only images saved to your account are visible. Work kept only in your browser is not.
+
+## Install
+
+**Claude Desktop:** download `label-image-mcp.mcpb` from the
+[latest release](https://github.com/sachinbkale27/label-image-mcp/releases/latest), open it, and
+enter your username and password when asked.
+
+**Claude Code:**
+
+```bash
+claude mcp add label-image -e LABEL_USERNAME=... -e LABEL_PASSWORD=... -- uvx label-image-mcp
+```
+
+**Any MCP client** (needs [uv](https://docs.astral.sh/uv/)):
+
+```json
+{
+  "mcpServers": {
+    "label-image": {
+      "command": "uvx",
+      "args": ["label-image-mcp"],
+      "env": { "LABEL_USERNAME": "...", "LABEL_PASSWORD": "..." }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LABEL_USERNAME` / `LABEL_PASSWORD` | unset | Account credentials. Without them requests are anonymous and read-only in practice |
+| `LABEL_API_URL` | `https://labels.sachin-kale.com/api` | API base URL, for another deployment or `sam local start-api` |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_images(category?)` | Image summaries with annotation counts |
+| `get_image(image_id)` | Metadata, annotations and a signed viewing URL |
+| `update_image_metadata(image_id, name?, category?, sub_category?, description?)` | Edit image details |
+| `add_annotations(image_id, annotations)` | Append pins, polygons, circles, rectangles or arrows |
+| `replace_annotations(image_id, annotations)` | Replace all annotations |
+| `remove_annotations(image_id, annotation_ids)` | Remove annotations by id |
+| `upload_image(path, name?, category?, description?)` | Upload a local image file |
+| `export_annotations(image_id, format)` | COCO JSON or YOLO, same output as the web app's export |
+
+There is deliberately no tool for deleting images.
+
+## HTTP mode
+
+`label-image-mcp --http [--host 127.0.0.1] [--port 8765]` serves Streamable HTTP at
+`http://HOST:PORT/mcp`, so several clients can share one running server:
+
+```bash
+claude mcp add --transport http label-image http://127.0.0.1:8765/mcp
+```
+
+## LangGraph agent
+
+A terminal chat agent that uses these tools. The graph is `START → agent ⇄ tools`, with
+conversation memory kept for the session.
+
+```bash
+uv tool install "label-image-mcp[agent]"
+export ANTHROPIC_API_KEY=... LABEL_USERNAME=... LABEL_PASSWORD=...
+label-image-agent
+```
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LABEL_AGENT_MODEL` | `anthropic:claude-sonnet-5-5` | Model as `provider:model`, e.g. `openai:gpt-4.1` or `ollama:llama3.1` (install `langchain-openai` / `langchain-ollama`) |
+| `LABEL_MCP_URL` | unset | Connect to a running HTTP server instead of starting one |
+
+## Development
+
+```bash
+uv sync --extra agent
+uv run pytest
+npx @modelcontextprotocol/inspector uv run label-image-mcp
+```
+
+In the Image Label app repo, `./start.sh` runs this server in HTTP mode next to the web app.
+It reads credentials from `mcp-server/.env`. Releases are described in [PUBLISHING.md](PUBLISHING.md).
+
+## License
+
+MIT

label_image_mcp-0.1.0/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["sachinbkale27"]
+}

label_image_mcp-0.1.0/manifest.json

@@ -0,0 +1,71 @@
+{
+  "manifest_version": "0.4",
+  "name": "label-image-mcp",
+  "display_name": "Image Label",
+  "version": "0.1.0",
+  "description": "Manage images and annotations in the Image Label app, and export COCO or YOLO datasets.",
+  "long_description": "Lets Claude list, upload and describe images saved in Image Label (labels.sachin-kale.com), add or clean up annotations, and export COCO or YOLO training data. Needs an Image Label account to upload or save annotations.",
+  "author": {
+    "name": "Sachin Kale",
+    "url": "https://labels.sachin-kale.com"
+  },
+  "homepage": "https://labels.sachin-kale.com/mcp",
+  "documentation": "https://github.com/sachinbkale27/label-image-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sachinbkale27/label-image-mcp"
+  },
+  "server": {
+    "type": "uv",
+    "entry_point": "src/label_image_mcp/server.py",
+    "mcp_config": {
+      "command": "uv",
+      "args": ["run", "--directory", "${__dirname}", "label-image-mcp"],
+      "env": {
+        "LABEL_USERNAME": "${user_config.username}",
+        "LABEL_PASSWORD": "${user_config.password}",
+        "LABEL_API_URL": "${user_config.api_url}"
+      }
+    }
+  },
+  "user_config": {
+    "username": {
+      "type": "string",
+      "title": "Username",
+      "description": "Image Label account username. Leave empty for read-only access.",
+      "required": false
+    },
+    "password": {
+      "type": "string",
+      "title": "Password",
+      "description": "Image Label account password",
+      "sensitive": true,
+      "required": false
+    },
+    "api_url": {
+      "type": "string",
+      "title": "API URL",
+      "description": "Only change this to use a different deployment",
+      "default": "https://labels.sachin-kale.com/api",
+      "required": false
+    }
+  },
+  "tools": [
+    { "name": "list_images", "description": "List saved images, optionally filtered by category" },
+    { "name": "get_image", "description": "Get an image's metadata, annotations and viewing URL" },
+    { "name": "update_image_metadata", "description": "Update an image's name, category or description" },
+    { "name": "add_annotations", "description": "Append annotations to an image" },
+    { "name": "replace_annotations", "description": "Replace all annotations on an image" },
+    { "name": "remove_annotations", "description": "Remove annotations by id" },
+    { "name": "upload_image", "description": "Upload a local image file" },
+    { "name": "export_annotations", "description": "Export annotations as COCO JSON or YOLO" }
+  ],
+  "compatibility": {
+    "platforms": ["darwin", "linux", "win32"],
+    "runtimes": {
+      "python": ">=3.10"
+    }
+  },
+  "keywords": ["image annotation", "coco", "yolo", "histopathology", "dataset"],
+  "license": "MIT"
+}

label_image_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "label-image-mcp"
+version = "0.1.0"
+description = "MCP server and LangGraph agent for the Image Label annotation app (labels.sachin-kale.com)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sachin Kale" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "image-annotation", "coco", "yolo", "langgraph", "histopathology"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    # langchain-mcp-adapters does not support mcp 2.x yet
+    "mcp>=1.24,<2",
+    "httpx>=0.27",
+    "pillow>=10.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+agent = [
+    "langgraph>=1.2",
+    "langchain>=1.4",
+    "langchain-mcp-adapters>=0.3",
+    "langchain-anthropic>=1.0",
+]
+
+[project.urls]
+Homepage = "https://labels.sachin-kale.com/mcp"
+Source = "https://github.com/sachinbkale27/label-image-mcp"
+Issues = "https://github.com/sachinbkale27/label-image-mcp/issues"
+
+[project.scripts]
+label-image-mcp = "label_image_mcp.server:main"
+label-image-agent = "label_image_mcp.agent:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/label_image_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

label_image_mcp-0.1.0/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.sachinbkale27/label-image-mcp",
+  "title": "Image Label",
+  "description": "Manage images and annotations in the Image Label app, and export COCO or YOLO datasets.",
+  "version": "0.1.0",
+  "websiteUrl": "https://labels.sachin-kale.com/mcp",
+  "repository": {
+    "url": "https://github.com/sachinbkale27/label-image-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "label-image-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "LABEL_USERNAME",
+          "description": "Image Label account username (needed to save annotations and upload)",
+          "isRequired": false
+        },
+        {
+          "name": "LABEL_PASSWORD",
+          "description": "Image Label account password",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "LABEL_API_URL",
+          "description": "API base URL",
+          "isRequired": false,
+          "default": "https://labels.sachin-kale.com/api"
+        }
+      ]
+    }
+  ]
+}

label_image_mcp-0.1.0/src/label_image_mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server and LangGraph agent for the Image Label web app."""