qrforge-mcp 0.1.0__tar.gz

qrforge_mcp-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# Local (stdio) configuration for qrforge-mcp.
+# Copy to .env or set in your MCP client config.
+
+# Required for local use: your QR Forge API token (https://qrforge.work/api/keys).
+QRFORGE_API_TOKEN=
+
+# Optional: override the API base URL (defaults to https://qrforge.work).
+# QRFORGE_API_URL=https://qrforge.work
+
+# Hosted server only (Docker): which API to forward to. No token here — the
+# hosted server reads each request's Authorization: Bearer <token> header.
+# QRFORGE_API_URL=https://qrforge.work

qrforge_mcp-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Test / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# CI workflow withheld until a workflow-scoped token is available
+.github/workflows/

qrforge_mcp-0.1.0/Dockerfile

@@ -0,0 +1,23 @@
+# QR Forge MCP server — hosted (streamable-HTTP) image.
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    MCP_HOST=0.0.0.0 \
+    MCP_PORT=8001
+
+WORKDIR /app
+
+# Install the package (and its deps) from the build context.
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+
+# Drop privileges.
+RUN useradd --create-home appuser
+USER appuser
+
+EXPOSE 8001
+
+# Hosted mode: each request carries its own Authorization: Bearer <token>.
+CMD ["qrforge-mcp", "--http", "--host", "0.0.0.0", "--port", "8001"]

qrforge_mcp-0.1.0/LICENSE

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

qrforge_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: qrforge-mcp
+Version: 0.1.0
+Summary: MCP server for the QR Forge API — create and manage trackable QR codes.
+Project-URL: Homepage, https://qrforge.work
+Project-URL: Repository, https://github.com/jkolarov/qrforge-mcp
+Project-URL: Issues, https://github.com/jkolarov/qrforge-mcp/issues
+Author: Georgi Kolarov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,model-context-protocol,qr,qrcode,qrforge
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.3.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# QR Forge MCP server
+
+An [MCP](https://modelcontextprotocol.io) server for [QR Forge](https://qrforge.work) —
+create and manage trackable QR codes (links, files, Wi-Fi, WhatsApp, phone, email)
+straight from an AI agent. It's a thin client over the public QR Forge REST API; it
+stores nothing and authenticates with **your** QR Forge API token.
+
+Get a token at **https://qrforge.work/api/keys**.
+
+## Two ways to use it
+
+### 1. Local (stdio) — install and run on your machine
+
+```bash
+uvx qrforge-mcp            # or: pipx install qrforge-mcp
+```
+
+Add it to your MCP client (Claude Desktop / Claude Code) — `claude_desktop_config.json`
+or `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "qrforge": {
+      "command": "qrforge-mcp",
+      "env": { "QRFORGE_API_TOKEN": "your-token-here" }
+    }
+  }
+}
+```
+
+Or with Claude Code's CLI:
+
+```bash
+claude mcp add qrforge --env QRFORGE_API_TOKEN=your-token-here -- qrforge-mcp
+```
+
+Environment variables:
+
+| Var | Required | Default | Purpose |
+|-----|----------|---------|---------|
+| `QRFORGE_API_TOKEN` | yes (local) | — | Your QR Forge API token |
+| `QRFORGE_API_URL` | no | `https://qrforge.work` | API base URL |
+
+### 2. Hosted — connect to our server, no install
+
+The hosted server runs at **`https://mcp.qrforge.work/mcp/`**. Pass your token in the
+`X-QRForge-Token` header:
+
+```bash
+claude mcp add --transport http qrforge https://mcp.qrforge.work/mcp/ \
+  --header "X-QRForge-Token: your-token-here"
+```
+
+> The hosted server sits behind Cloudflare, which strips the `Authorization` header
+> on streaming requests — so use **`X-QRForge-Token`** for the hosted endpoint.
+> (`Authorization: Bearer <token>` still works for local/self-hosted instances.)
+
+The hosted server is stateless and multi-user: it forwards each request's token to
+the API and never stores it.
+
+## Tools
+
+- **Identity/tokens:** `whoami`, `list_api_tokens`, `create_api_token`, `revoke_api_token`
+- **Discovery:** `list_qr_types`, `list_qr_styles`
+- **Render (no save):** `render_qr`
+- **Create:** `create_url_qrcode`, `create_whatsapp_qrcode`, `create_wifi_qrcode`,
+  `create_phone_qrcode`, `create_email_qrcode`, `create_file_qrcode`
+- **Manage:** `list_qrcodes`, `get_qrcode`, `update_qrcode`, `delete_qrcode`
+- **Images:** `get_qrcode_png`, `get_qrcode_svg`
+- **Files/logo:** `download_qrcode_file`, `replace_qrcode_file`, `set_qrcode_logo`,
+  `remove_qrcode_logo`
+- **Analytics:** `get_qrcode_history`, `get_qrcode_scans`
+
+`style` (optional, on create/render/update) is an object with keys `module_drawer`
+(`square|rounded|circle|gapped|vertical_bars|horizontal_bars`), `fill_type`
+(`solid|radial|horizontal|vertical`), `fill_color`, `fill_color_2`, `back_color` (hex).
+
+File tools accept the file via `file_path` (local), `file_url` (server downloads it),
+or `file_base64` — up to 50 MB.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Run the hosted server locally:
+
+```bash
+qrforge-mcp --http --host 0.0.0.0 --port 8001     # streamable-HTTP at /mcp/
+# or stdio:
+QRFORGE_API_TOKEN=... qrforge-mcp
+```
+
+## License
+
+MIT

qrforge_mcp-0.1.0/README.md

@@ -0,0 +1,99 @@
+# QR Forge MCP server
+
+An [MCP](https://modelcontextprotocol.io) server for [QR Forge](https://qrforge.work) —
+create and manage trackable QR codes (links, files, Wi-Fi, WhatsApp, phone, email)
+straight from an AI agent. It's a thin client over the public QR Forge REST API; it
+stores nothing and authenticates with **your** QR Forge API token.
+
+Get a token at **https://qrforge.work/api/keys**.
+
+## Two ways to use it
+
+### 1. Local (stdio) — install and run on your machine
+
+```bash
+uvx qrforge-mcp            # or: pipx install qrforge-mcp
+```
+
+Add it to your MCP client (Claude Desktop / Claude Code) — `claude_desktop_config.json`
+or `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "qrforge": {
+      "command": "qrforge-mcp",
+      "env": { "QRFORGE_API_TOKEN": "your-token-here" }
+    }
+  }
+}
+```
+
+Or with Claude Code's CLI:
+
+```bash
+claude mcp add qrforge --env QRFORGE_API_TOKEN=your-token-here -- qrforge-mcp
+```
+
+Environment variables:
+
+| Var | Required | Default | Purpose |
+|-----|----------|---------|---------|
+| `QRFORGE_API_TOKEN` | yes (local) | — | Your QR Forge API token |
+| `QRFORGE_API_URL` | no | `https://qrforge.work` | API base URL |
+
+### 2. Hosted — connect to our server, no install
+
+The hosted server runs at **`https://mcp.qrforge.work/mcp/`**. Pass your token in the
+`X-QRForge-Token` header:
+
+```bash
+claude mcp add --transport http qrforge https://mcp.qrforge.work/mcp/ \
+  --header "X-QRForge-Token: your-token-here"
+```
+
+> The hosted server sits behind Cloudflare, which strips the `Authorization` header
+> on streaming requests — so use **`X-QRForge-Token`** for the hosted endpoint.
+> (`Authorization: Bearer <token>` still works for local/self-hosted instances.)
+
+The hosted server is stateless and multi-user: it forwards each request's token to
+the API and never stores it.
+
+## Tools
+
+- **Identity/tokens:** `whoami`, `list_api_tokens`, `create_api_token`, `revoke_api_token`
+- **Discovery:** `list_qr_types`, `list_qr_styles`
+- **Render (no save):** `render_qr`
+- **Create:** `create_url_qrcode`, `create_whatsapp_qrcode`, `create_wifi_qrcode`,
+  `create_phone_qrcode`, `create_email_qrcode`, `create_file_qrcode`
+- **Manage:** `list_qrcodes`, `get_qrcode`, `update_qrcode`, `delete_qrcode`
+- **Images:** `get_qrcode_png`, `get_qrcode_svg`
+- **Files/logo:** `download_qrcode_file`, `replace_qrcode_file`, `set_qrcode_logo`,
+  `remove_qrcode_logo`
+- **Analytics:** `get_qrcode_history`, `get_qrcode_scans`
+
+`style` (optional, on create/render/update) is an object with keys `module_drawer`
+(`square|rounded|circle|gapped|vertical_bars|horizontal_bars`), `fill_type`
+(`solid|radial|horizontal|vertical`), `fill_color`, `fill_color_2`, `back_color` (hex).
+
+File tools accept the file via `file_path` (local), `file_url` (server downloads it),
+or `file_base64` — up to 50 MB.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Run the hosted server locally:
+
+```bash
+qrforge-mcp --http --host 0.0.0.0 --port 8001     # streamable-HTTP at /mcp/
+# or stdio:
+QRFORGE_API_TOKEN=... qrforge-mcp
+```
+
+## License
+
+MIT

qrforge_mcp-0.1.0/docker-compose.yml

@@ -0,0 +1,25 @@
+# Hosted QR Forge MCP server. Public traffic reaches it via the Cloudflare
+# tunnel ingress mcp.qrforge.work -> http://localhost:8001.
+services:
+  mcp-server:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: qr-mcp-server
+    ports:
+      - "8001:8001"
+    environment:
+      # The QR Forge API this server talks to. No token is stored here — each
+      # MCP request must carry its own Authorization: Bearer <token>.
+      - QRFORGE_API_URL=${QRFORGE_API_URL:-https://qrforge.work}
+      - MCP_HOST=0.0.0.0
+      - MCP_PORT=8001
+    restart: unless-stopped
+    healthcheck:
+      # Prove the server is listening (TCP connect). Avoids HTTP-status quirks of
+      # the MCP endpoint.
+      test: ["CMD", "python", "-c", "import socket; socket.create_connection(('localhost', 8001), 3).close()"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 20s

qrforge_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qrforge-mcp"
+version = "0.1.0"
+description = "MCP server for the QR Forge API — create and manage trackable QR codes."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Georgi Kolarov" }]
+keywords = ["mcp", "qr", "qrcode", "qrforge", "model-context-protocol"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastmcp>=2.3.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[project.scripts]
+qrforge-mcp = "qrforge_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://qrforge.work"
+Repository = "https://github.com/jkolarov/qrforge-mcp"
+Issues = "https://github.com/jkolarov/qrforge-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qrforge_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

qrforge_mcp-0.1.0/src/qrforge_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""QR Forge MCP server — expose the QR Forge REST API as MCP tools."""
+
+__version__ = "0.1.0"

qrforge_mcp-0.1.0/src/qrforge_mcp/__main__.py

@@ -0,0 +1,31 @@
+"""CLI entrypoint. Default transport is stdio (local); ``--http`` runs the
+hosted streamable-HTTP server."""
+from __future__ import annotations
+
+import argparse
+import os
+
+from .server import mcp
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="qrforge-mcp",
+        description="MCP server for the QR Forge API (https://qrforge.work).",
+    )
+    parser.add_argument(
+        "--http", action="store_true",
+        help="Run as a hosted HTTP (streamable-http) server instead of stdio.",
+    )
+    parser.add_argument("--host", default=os.environ.get("MCP_HOST", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("MCP_PORT", "8001")))
+    args = parser.parse_args()
+
+    if args.http:
+        mcp.run(transport="http", host=args.host, port=args.port)
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()

qrforge_mcp-0.1.0/src/qrforge_mcp/client.py

@@ -0,0 +1,176 @@
+"""Thin REST client for the QR Forge API, shared by all MCP tools.
+
+The MCP server never touches QR Forge's database — it only calls the public REST
+API (``/api/v1``) with the user's API token. This module resolves the token and
+base URL, performs requests, and normalises the API's error envelope into MCP
+``ToolError``s.
+
+Token resolution (in order):
+  1. Hosted (HTTP) mode: the caller's ``Authorization: Bearer <token>`` header,
+     read via ``fastmcp.server.dependencies.get_http_headers`` and forwarded.
+  2. Local (stdio) mode: the ``QRFORGE_API_TOKEN`` environment variable.
+
+Base URL: ``QRFORGE_API_URL`` (default ``https://qrforge.work``).
+"""
+from __future__ import annotations
+
+import base64
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_http_headers
+
+DEFAULT_BASE_URL = "https://qrforge.work"
+MAX_FILE_BYTES = 50 * 1024 * 1024  # mirrors the API's 50 MB upload limit
+TIMEOUT = httpx.Timeout(120.0, connect=15.0)
+
+
+def api_base() -> str:
+    base = os.environ.get("QRFORGE_API_URL", DEFAULT_BASE_URL).rstrip("/")
+    return f"{base}/api/v1"
+
+
+def resolve_token() -> str:
+    """Return the API token from the request header (hosted) or env (local)."""
+    headers: dict[str, str] = {}
+    try:
+        # `authorization` is excluded from get_http_headers() by default; opt it in.
+        # Also read X-QRForge-Token: some proxies (notably Cloudflare) strip the
+        # Authorization header, so a custom header is the reliable hosted path.
+        headers = get_http_headers(include={"authorization", "x-qrforge-token"}) or {}
+    except Exception:
+        headers = {}
+
+    # Custom token header (survives proxies that strip Authorization).
+    custom = (headers.get("x-qrforge-token") or "").strip()
+    if custom:
+        return custom
+
+    # Standard Authorization: Bearer <token> (local/direct or proxies that keep it).
+    auth = headers.get("authorization") or headers.get("Authorization") or ""
+    if auth.lower().startswith("bearer "):
+        token = auth[7:].strip()
+        if token:
+            return token
+
+    # Local (stdio) mode: environment variable.
+    token = (os.environ.get("QRFORGE_API_TOKEN") or "").strip()
+    if token:
+        return token
+
+    raise ToolError(
+        "No QR Forge API token found. Local: set QRFORGE_API_TOKEN. Hosted: send "
+        "'X-QRForge-Token: <token>' (or 'Authorization: Bearer <token>'). Create a "
+        "token at https://qrforge.work/api/keys."
+    )
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    params: dict | None = None,
+    json: dict | None = None,
+    data: dict | None = None,
+    files: dict | None = None,
+    expect: str = "json",
+) -> Any:
+    """Call the QR Forge API. ``expect`` is 'json', 'bytes', or 'text'.
+
+    Raises ToolError on transport failures and on any 4xx/5xx, surfacing the
+    API's ``{"error": ..., "code": ...}`` envelope.
+    """
+    url = f"{api_base()}{path}"
+    headers = {"Authorization": f"Bearer {resolve_token()}"}
+    # Strip None values so optional fields don't get sent as literal nulls.
+    if json is not None:
+        json = {k: v for k, v in json.items() if v is not None}
+    if data is not None:
+        data = {k: v for k, v in data.items() if v is not None}
+
+    try:
+        resp = httpx.request(
+            method, url, params=params, json=json, data=data, files=files,
+            headers=headers, timeout=TIMEOUT,
+        )
+    except httpx.HTTPError as exc:
+        raise ToolError(f"Could not reach the QR Forge API at {url}: {exc}") from exc
+
+    if resp.status_code >= 400:
+        code = msg = None
+        try:
+            body = resp.json()
+            code, msg = body.get("code"), body.get("error")
+        except Exception:
+            msg = (resp.text or "")[:300]
+        suffix = f"/{code}" if code else ""
+        raise ToolError(
+            f"QR Forge API error ({resp.status_code}{suffix}): {msg or 'request failed'}"
+        )
+
+    if expect == "bytes":
+        return resp.content
+    if expect == "text":
+        return resp.text
+    if not resp.content:
+        return {}
+    try:
+        return resp.json()
+    except Exception:
+        return {"raw": resp.text}
+
+
+def load_file(
+    *,
+    file_path: str | None = None,
+    file_url: str | None = None,
+    file_base64: str | None = None,
+    filename: str | None = None,
+) -> tuple[str, bytes]:
+    """Resolve file content from a local path, a URL, or base64 (in that order).
+
+    Returns ``(filename, content_bytes)``. Enforces the 50 MB API limit.
+    """
+    if file_path:
+        path = Path(file_path).expanduser()
+        if not path.is_file():
+            raise ToolError(f"File not found: {file_path}")
+        content = path.read_bytes()
+        name = filename or path.name
+    elif file_url:
+        try:
+            resp = httpx.get(file_url, timeout=TIMEOUT, follow_redirects=True)
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise ToolError(f"Could not download file_url: {exc}") from exc
+        content = resp.content
+        name = filename or os.path.basename(urlparse(file_url).path) or "upload"
+    elif file_base64:
+        try:
+            content = base64.b64decode(file_base64, validate=True)
+        except Exception as exc:
+            raise ToolError(f"Invalid base64 in file_base64: {exc}") from exc
+        name = filename or "upload"
+    else:
+        raise ToolError("Provide one of: file_path, file_url, or file_base64.")
+
+    if len(content) > MAX_FILE_BYTES:
+        raise ToolError(
+            f"File is {len(content) // (1024 * 1024)} MB; the QR Forge limit is 50 MB."
+        )
+    return name, content
+
+
+# Style fields accepted by the API (see _style_from / _sanitise_style server-side).
+STYLE_KEYS = ("module_drawer", "fill_color", "back_color", "fill_type", "fill_color_2")
+
+
+def clean_style(style: dict | None) -> dict:
+    """Keep only recognised, non-null style keys."""
+    if not style:
+        return {}
+    return {k: v for k, v in style.items() if k in STYLE_KEYS and v is not None}

qrforge_mcp-0.1.0/src/qrforge_mcp/server.py

@@ -0,0 +1,400 @@
+"""QR Forge MCP server: every QR Forge REST API capability as an MCP tool.
+
+Tools are a thin mirror of ``/api/v1``. Authentication is the caller's QR Forge
+API token (forwarded header when hosted, ``QRFORGE_API_TOKEN`` env when local).
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+from fastmcp.utilities.types import Image
+from mcp.types import TextContent
+from pydantic import Field
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from . import client
+
+mcp = FastMCP(
+    name="QR Forge",
+    instructions=(
+        "Tools to create and manage trackable QR codes via the QR Forge API "
+        "(https://qrforge.work). Authenticate with a QR Forge API token. Use "
+        "list_qr_types and list_qr_styles to discover options. 'style' is an "
+        "optional object with keys: module_drawer (square|rounded|circle|gapped|"
+        "vertical_bars|horizontal_bars), fill_type (solid|radial|horizontal|"
+        "vertical), fill_color, fill_color_2, back_color (hex like #000000)."
+    ),
+)
+
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health(_request: Request) -> JSONResponse:
+    """Unauthenticated liveness probe for uptime monitors (HTTP transport only)."""
+    return JSONResponse({"status": "ok"})
+
+Style = Annotated[dict | None, Field(
+    default=None,
+    description="Optional QR style: module_drawer, fill_type, fill_color, "
+                "fill_color_2, back_color.",
+)]
+
+# Fields surfaced to the user/model. We drop the raw API `links` and the
+# `download_url` (auth-gated /api/v1 paths) so the model never hands the user a
+# URL that 401s — image/file access goes through the dedicated tools instead.
+_PRESENT_FIELDS = (
+    "id", "name", "type", "public_id", "public_url", "is_active", "is_expired",
+    "expires_at", "total_scans", "has_logo", "style", "target",
+)
+
+
+def present(doc: dict) -> dict:
+    """Trim a QR document to user-facing fields (no internal API links)."""
+    out = {k: doc.get(k) for k in _PRESENT_FIELDS if doc.get(k) is not None}
+    target = out.get("target")
+    if isinstance(target, dict):
+        out["target"] = {k: v for k, v in target.items() if k != "download_url"}
+    return out
+
+
+def _render_png(doc_id: int) -> bytes | None:
+    """Best-effort: render the saved QR as PNG. Never fails the calling tool."""
+    try:
+        return client.request("GET", f"/qrcodes/{doc_id}/qr.png",
+                               params={"size": 10}, expect="bytes")
+    except Exception:
+        return None
+
+
+def _qr_result(doc: dict, note: str) -> ToolResult:
+    """Return the QR image inline (for the client to display) plus clean metadata
+    the model can reason over. The image is also re-fetchable via get_qrcode_png."""
+    summary = present(doc)
+    blocks: list = []
+    png = _render_png(doc["id"])
+    if png is not None:
+        blocks.append(Image(data=png, format="png").to_image_content())
+    public = doc.get("public_url")
+    text = (f"{note} QR code #{doc['id']} (type={doc.get('type')})."
+            + (f" Encoded/public link: {public}." if public else "")
+            + " The QR image is attached above; call get_qrcode_png(id="
+            f"{doc['id']}) to fetch it again.")
+    blocks.append(TextContent(type="text", text=text))
+    return ToolResult(content=blocks, structured_content=summary)
+
+
+# ── Identity & tokens ─────────────────────────────────────────────────────────
+
+@mcp.tool
+def whoami() -> dict:
+    """Return the authenticated account's identity and QR-code count (GET /me)."""
+    return client.request("GET", "/me")
+
+
+@mcp.tool
+def list_api_tokens() -> dict:
+    """List the account's API tokens (secrets are never returned)."""
+    return client.request("GET", "/tokens")
+
+
+@mcp.tool
+def create_api_token(name: str = "API Token") -> dict:
+    """Create a new API token. The full secret is returned exactly once."""
+    return client.request("POST", "/tokens", json={"name": name})
+
+
+@mcp.tool
+def revoke_api_token(token_id: int) -> dict:
+    """Revoke (delete) an API token by id."""
+    return client.request("DELETE", f"/tokens/{token_id}")
+
+
+# ── Discovery ─────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_qr_types() -> dict:
+    """List available QR code types and their required fields (GET /qr/types)."""
+    return client.request("GET", "/qr/types")
+
+
+@mcp.tool
+def list_qr_styles() -> dict:
+    """List QR style presets and defaults (GET /qr/styles)."""
+    return client.request("GET", "/qr/styles")
+
+
+# ── Stateless render ──────────────────────────────────────────────────────────
+
+@mcp.tool
+def render_qr(url: str, format: str = "png", size: int = 12, style: Style = None) -> Any:
+    """Render a styled QR code for an arbitrary URL without saving it.
+
+    Returns a PNG image (format='png') or the SVG markup as text (format='svg').
+    """
+    body: dict[str, Any] = {"url": url, "format": format, "size": size}
+    cleaned = client.clean_style(style)
+    if cleaned:
+        body["style"] = cleaned  # render nests style under "style"
+    if format == "svg":
+        return client.request("POST", "/qr/render", json=body, expect="text")
+    png = client.request("POST", "/qr/render", json=body, expect="bytes")
+    return Image(data=png, format="png")
+
+
+# ── Create QR codes (per type) ────────────────────────────────────────────────
+
+def _create(type_: str, fields: dict, style: dict | None) -> ToolResult:
+    # POST /qrcodes reads style fields at the TOP LEVEL of the body.
+    body = {"type": type_, **{k: v for k, v in fields.items() if v is not None}}
+    body.update(client.clean_style(style))
+    doc = client.request("POST", "/qrcodes", json=body)
+    return _qr_result(doc, "Created")
+
+
+@mcp.tool
+def create_url_qrcode(
+    target_url: str,
+    name: str | None = None,
+    static: bool = False,
+    expires_in_days: int | None = None,
+    style: Style = None,
+) -> ToolResult:
+    """Create a Website-link QR code. static=True encodes the URL directly
+    (no redirect, no scan tracking, not editable); default is a tracked, editable
+    dynamic link."""
+    return _create("url", {
+        "target_url": target_url, "name": name,
+        "static": static, "expires_in_days": expires_in_days,
+    }, style)
+
+
+@mcp.tool
+def create_whatsapp_qrcode(
+    target_url: str,
+    name: str | None = None,
+    expires_in_days: int | None = None,
+    style: Style = None,
+) -> ToolResult:
+    """Create a WhatsApp QR code from a wa.me link (tracked dynamic link)."""
+    return _create("whatsapp", {
+        "target_url": target_url, "name": name, "expires_in_days": expires_in_days,
+    }, style)
+
+
+@mcp.tool
+def create_wifi_qrcode(
+    ssid: str,
+    auth: str = "WPA",
+    password: str | None = None,
+    hidden: bool = False,
+    name: str | None = None,
+    style: Style = None,
+) -> ToolResult:
+    """Create a Wi-Fi QR code (static; encodes credentials directly).
+    auth is one of WPA, WPA3, WEP, nopass."""
+    return _create("wifi", {
+        "ssid": ssid, "auth": auth, "password": password,
+        "hidden": hidden, "name": name,
+    }, style)
+
+
+@mcp.tool
+def create_phone_qrcode(phone: str, name: str | None = None, style: Style = None) -> ToolResult:
+    """Create a phone-number QR code (static; dials when scanned)."""
+    return _create("phone", {"phone": phone, "name": name}, style)
+
+
+@mcp.tool
+def create_email_qrcode(
+    email: str,
+    subject: str | None = None,
+    body: str | None = None,
+    name: str | None = None,
+    style: Style = None,
+) -> ToolResult:
+    """Create an email QR code (static; opens a prefilled email when scanned)."""
+    return _create("email", {
+        "email": email, "subject": subject, "body": body, "name": name,
+    }, style)
+
+
+@mcp.tool
+def create_file_qrcode(
+    file_path: str | None = None,
+    file_url: str | None = None,
+    file_base64: str | None = None,
+    filename: str | None = None,
+    name: str | None = None,
+    expires_in_days: int | None = None,
+    style: Style = None,
+) -> ToolResult:
+    """Create a file/document QR code. Provide the file via file_path (local),
+    file_url (downloaded by the server), or file_base64. Accepts images, PDF,
+    Office, OpenDocument and text files up to 50 MB."""
+    fname, content = client.load_file(
+        file_path=file_path, file_url=file_url, file_base64=file_base64, filename=filename)
+    data = {"type": "pdf", "name": name, "expires_in_days": expires_in_days}
+    data.update(client.clean_style(style))
+    files = {"pdf_file": (fname, content, "application/octet-stream")}
+    doc = client.request("POST", "/qrcodes", data=data, files=files)
+    return _qr_result(doc, "Created")
+
+
+# ── Read / update / delete ────────────────────────────────────────────────────
+
+@mcp.tool
+def list_qrcodes(
+    q: str | None = None,
+    active: bool | None = None,
+    page: int = 1,
+    limit: int = 25,
+) -> dict:
+    """List the account's QR codes with optional search (q matches name/filename),
+    active filter, and pagination (limit max 100). Returns data + pagination."""
+    params: dict[str, Any] = {"page": page, "limit": limit}
+    if q:
+        params["q"] = q
+    if active is not None:
+        params["active"] = "true" if active else "false"
+    result = client.request("GET", "/qrcodes", params=params)
+    result["data"] = [present(d) for d in result.get("data", [])]
+    return result
+
+
+@mcp.tool
+def get_qrcode(id: int) -> dict:
+    """Get a single QR code's details by id. Use get_qrcode_png to view the image."""
+    return present(client.request("GET", f"/qrcodes/{id}"))
+
+
+@mcp.tool
+def update_qrcode(
+    id: int,
+    name: str | None = None,
+    is_active: bool | None = None,
+    target_url: str | None = None,
+    ssid: str | None = None,
+    auth: str | None = None,
+    password: str | None = None,
+    hidden: bool | None = None,
+    phone: str | None = None,
+    email: str | None = None,
+    subject: str | None = None,
+    body: str | None = None,
+    expires_in_days: int | None = None,
+    style: Style = None,
+) -> dict:
+    """Update a QR code's mutable fields. Only fields valid for the QR's type
+    apply (e.g. target_url for url; ssid/auth/password/hidden for wifi). Set
+    expires_in_days to 0/null to clear expiry."""
+    payload: dict[str, Any] = {
+        "name": name, "is_active": is_active, "target_url": target_url,
+        "ssid": ssid, "auth": auth, "password": password, "hidden": hidden,
+        "phone": phone, "email": email, "subject": subject, "body": body,
+        "expires_in_days": expires_in_days,
+    }
+    payload = {k: v for k, v in payload.items() if v is not None}
+    cleaned = client.clean_style(style)
+    if cleaned:
+        payload["style"] = cleaned  # PATCH nests style under "style"
+    return present(client.request("PATCH", f"/qrcodes/{id}", json=payload))
+
+
+@mcp.tool
+def delete_qrcode(id: int) -> dict:
+    """Delete a QR code (and its underlying file, if any)."""
+    return client.request("DELETE", f"/qrcodes/{id}")
+
+
+# ── Rendered images ───────────────────────────────────────────────────────────
+
+@mcp.tool
+def get_qrcode_png(id: int, size: int = 30, no_logo: bool = False) -> Image:
+    """Render a saved QR code as a PNG image using its stored style/logo."""
+    params: dict[str, Any] = {"size": size}
+    if no_logo:
+        params["no_logo"] = "1"
+    png = client.request("GET", f"/qrcodes/{id}/qr.png", params=params, expect="bytes")
+    return Image(data=png, format="png")
+
+
+@mcp.tool
+def get_qrcode_svg(id: int) -> str:
+    """Return a saved QR code as SVG markup (text)."""
+    return client.request("GET", f"/qrcodes/{id}/qr.svg", expect="text")
+
+
+# ── Underlying file & logo ────────────────────────────────────────────────────
+
+@mcp.tool
+def download_qrcode_file(id: int, save_path: str | None = None) -> dict:
+    """Download a file-backed QR code's current file. With save_path, writes it
+    there and returns the path; otherwise returns base64 (small files only)."""
+    import base64 as _b64
+    from pathlib import Path as _Path
+
+    content = client.request("GET", f"/qrcodes/{id}/file", expect="bytes")
+    if save_path:
+        p = _Path(save_path).expanduser()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(content)
+        return {"saved_to": str(p), "bytes": len(content)}
+    if len(content) > 8 * 1024 * 1024:
+        raise ToolError(
+            f"File is {len(content) // (1024 * 1024)} MB — too large to inline. "
+            "Pass save_path to write it to disk instead."
+        )
+    return {"bytes": len(content), "base64": _b64.b64encode(content).decode()}
+
+
+@mcp.tool
+def replace_qrcode_file(
+    id: int,
+    file_path: str | None = None,
+    file_url: str | None = None,
+    file_base64: str | None = None,
+    filename: str | None = None,
+) -> dict:
+    """Replace a file-backed QR code's file while keeping its QR/link unchanged."""
+    fname, content = client.load_file(
+        file_path=file_path, file_url=file_url, file_base64=file_base64, filename=filename)
+    files = {"pdf_file": (fname, content, "application/octet-stream")}
+    return present(client.request("PUT", f"/qrcodes/{id}/file", files=files))
+
+
+@mcp.tool
+def set_qrcode_logo(
+    id: int,
+    file_path: str | None = None,
+    file_url: str | None = None,
+    file_base64: str | None = None,
+    filename: str | None = None,
+) -> dict:
+    """Set/replace a QR code's center logo (PNG, JPG, or WebP)."""
+    fname, content = client.load_file(
+        file_path=file_path, file_url=file_url, file_base64=file_base64, filename=filename)
+    files = {"logo": (fname, content, "application/octet-stream")}
+    return present(client.request("PUT", f"/qrcodes/{id}/logo", files=files))
+
+
+@mcp.tool
+def remove_qrcode_logo(id: int) -> dict:
+    """Remove a QR code's center logo."""
+    return present(client.request("DELETE", f"/qrcodes/{id}/logo"))
+
+
+# ── Analytics & history ───────────────────────────────────────────────────────
+
+@mcp.tool
+def get_qrcode_history(id: int) -> dict:
+    """File-replacement history for a file-backed QR code (newest first)."""
+    return client.request("GET", f"/qrcodes/{id}/history")
+
+
+@mcp.tool
+def get_qrcode_scans(id: int, days: int = 30) -> dict:
+    """Scan analytics for a dynamic QR code: daily series + totals (days 1-365)."""
+    return client.request("GET", f"/qrcodes/{id}/scans", params={"days": days})

qrforge_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,62 @@
+"""Unit tests for the REST client helpers (token resolution, style, file load)."""
+import base64
+
+import pytest
+from fastmcp.exceptions import ToolError
+
+from qrforge_mcp import client
+
+
+def test_api_base_default(monkeypatch):
+    monkeypatch.delenv("QRFORGE_API_URL", raising=False)
+    assert client.api_base() == "https://qrforge.work/api/v1"
+
+
+def test_api_base_override(monkeypatch):
+    monkeypatch.setenv("QRFORGE_API_URL", "http://localhost:5000/")
+    assert client.api_base() == "http://localhost:5000/api/v1"
+
+
+def test_resolve_token_prefers_header(monkeypatch):
+    monkeypatch.setenv("QRFORGE_API_TOKEN", "env-token")
+    monkeypatch.setattr(client, "get_http_headers",
+                        lambda **_: {"authorization": "Bearer hdr-token"})
+    assert client.resolve_token() == "hdr-token"
+
+
+def test_resolve_token_custom_header_wins(monkeypatch):
+    # X-QRForge-Token survives proxies that strip Authorization (e.g. Cloudflare).
+    monkeypatch.delenv("QRFORGE_API_TOKEN", raising=False)
+    monkeypatch.setattr(client, "get_http_headers",
+                        lambda **_: {"x-qrforge-token": "custom-token"})
+    assert client.resolve_token() == "custom-token"
+
+
+def test_resolve_token_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("QRFORGE_API_TOKEN", "env-token")
+    monkeypatch.setattr(client, "get_http_headers", lambda **_: {})
+    assert client.resolve_token() == "env-token"
+
+
+def test_resolve_token_missing_raises(monkeypatch):
+    monkeypatch.delenv("QRFORGE_API_TOKEN", raising=False)
+    monkeypatch.setattr(client, "get_http_headers", lambda **_: {})
+    with pytest.raises(ToolError):
+        client.resolve_token()
+
+
+def test_clean_style_filters_unknown_and_null():
+    style = {"module_drawer": "circle", "fill_color": None, "bogus": "x"}
+    assert client.clean_style(style) == {"module_drawer": "circle"}
+    assert client.clean_style(None) == {}
+
+
+def test_load_file_base64_and_limit():
+    name, content = client.load_file(file_base64=base64.b64encode(b"hello").decode(),
+                                     filename="a.txt")
+    assert name == "a.txt" and content == b"hello"
+
+
+def test_load_file_requires_a_source():
+    with pytest.raises(ToolError):
+        client.load_file()

qrforge_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,143 @@
+"""Tool-level tests: drive the real MCP tools via an in-memory FastMCP client,
+with the QR Forge REST API mocked by respx. Verifies request shaping (incl. the
+top-level-vs-nested style quirk), auth header forwarding, and error surfacing.
+"""
+import base64
+
+import httpx
+import pytest
+import respx
+from fastmcp import Client
+
+from qrforge_mcp.server import mcp
+
+API = "https://qrforge.work/api/v1"
+
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch):
+    monkeypatch.setenv("QRFORGE_API_TOKEN", "test-token")
+    monkeypatch.setenv("QRFORGE_API_URL", "https://qrforge.work")
+
+
+async def _call(name, args=None):
+    async with Client(mcp) as c:
+        return await c.call_tool(name, args or {})
+
+
+@respx.mock
+async def test_whoami_forwards_bearer():
+    route = respx.get(f"{API}/me").mock(
+        return_value=httpx.Response(200, json={"email": "a@b.com", "qrcode_count": 3}))
+    res = await _call("whoami")
+    assert route.called
+    assert route.calls[0].request.headers["authorization"] == "Bearer test-token"
+    assert res.data["email"] == "a@b.com"
+
+
+@respx.mock
+async def test_list_qrcodes_sends_filters():
+    route = respx.get(f"{API}/qrcodes").mock(
+        return_value=httpx.Response(200, json={"data": [], "pagination": {"total": 0}}))
+    await _call("list_qrcodes", {"q": "menu", "active": True, "page": 2, "limit": 50})
+    req = route.calls[0].request
+    assert dict(req.url.params) == {"page": "2", "limit": "50", "q": "menu", "active": "true"}
+
+
+@respx.mock
+async def test_create_url_puts_style_at_top_level():
+    route = respx.post(f"{API}/qrcodes").mock(
+        return_value=httpx.Response(201, json={"id": 1, "type": "url"}))
+    respx.get(url__regex=r".+/qr\.png").mock(return_value=httpx.Response(200, content=b"\x89PNG\r\n"))
+    await _call("create_url_qrcode", {
+        "target_url": "https://example.com", "name": "X", "static": True,
+        "style": {"module_drawer": "circle", "fill_color": "#ff0000"},
+    })
+    import json as _json
+    sent = _json.loads(route.calls[0].request.content)
+    assert sent["type"] == "url"
+    assert sent["target_url"] == "https://example.com"
+    assert sent["static"] is True
+    # style fields are TOP-LEVEL on create
+    assert sent["module_drawer"] == "circle"
+    assert sent["fill_color"] == "#ff0000"
+    assert "style" not in sent
+
+
+@respx.mock
+async def test_update_nests_style():
+    route = respx.patch(f"{API}/qrcodes/7").mock(
+        return_value=httpx.Response(200, json={"id": 7}))
+    await _call("update_qrcode", {"id": 7, "name": "New",
+                                  "style": {"fill_color": "#00ff00"}})
+    import json as _json
+    sent = _json.loads(route.calls[0].request.content)
+    assert sent["name"] == "New"
+    # style is NESTED on PATCH
+    assert sent["style"] == {"fill_color": "#00ff00"}
+    assert "fill_color" not in sent
+
+
+@respx.mock
+async def test_create_wifi_body():
+    route = respx.post(f"{API}/qrcodes").mock(
+        return_value=httpx.Response(201, json={"id": 2, "type": "wifi"}))
+    respx.get(url__regex=r".+/qr\.png").mock(return_value=httpx.Response(200, content=b"\x89PNG\r\n"))
+    await _call("create_wifi_qrcode", {"ssid": "Net", "auth": "WPA", "password": "p"})
+    import json as _json
+    sent = _json.loads(route.calls[0].request.content)
+    assert sent == {"type": "wifi", "ssid": "Net", "auth": "WPA",
+                    "password": "p", "hidden": False}
+
+
+@respx.mock
+async def test_create_file_qrcode_multipart():
+    route = respx.post(f"{API}/qrcodes").mock(
+        return_value=httpx.Response(201, json={"id": 3, "type": "pdf"}))
+    respx.get(url__regex=r".+/qr\.png").mock(return_value=httpx.Response(200, content=b"\x89PNG\r\n"))
+    await _call("create_file_qrcode", {
+        "file_base64": base64.b64encode(b"PK\x03\x04").decode(),
+        "filename": "sheet.xlsx", "name": "Sheet",
+    })
+    req = route.calls[0].request
+    assert req.headers["content-type"].startswith("multipart/form-data")
+    body = req.content
+    assert b"sheet.xlsx" in body and b'name="pdf_file"' in body and b"pdf" in body
+
+
+@respx.mock
+async def test_create_returns_inline_image_and_clean_metadata():
+    respx.post(f"{API}/qrcodes").mock(return_value=httpx.Response(201, json={
+        "id": 9, "type": "url", "public_url": "https://qrforge.work/d/abc",
+        "links": {"qr_png": "/api/v1/qrcodes/9/qr.png"},
+        "target": {"kind": "url", "url": "https://x.io", "download_url": "/api/v1/qrcodes/9/file"},
+    }))
+    respx.get(url__regex=r".+/qr\.png").mock(
+        return_value=httpx.Response(200, content=b"\x89PNG\r\nDATA"))
+    res = await _call("create_url_qrcode", {"target_url": "https://x.io"})
+    # an image content block is returned for the client to display
+    assert any(getattr(b, "type", "") == "image" for b in res.content)
+    # structured metadata is clean: no auth-gated api links surfaced
+    assert res.data["id"] == 9 and res.data["public_url"] == "https://qrforge.work/d/abc"
+    assert "links" not in res.data
+    assert "download_url" not in res.data["target"]
+
+
+@respx.mock
+async def test_render_svg_returns_text():
+    respx.post(f"{API}/qr/render").mock(
+        return_value=httpx.Response(200, text="<svg>ok</svg>",
+                                    headers={"content-type": "image/svg+xml"}))
+    res = await _call("render_qr", {"url": "https://x.io", "format": "svg"})
+    text = res.data if isinstance(res.data, str) else res.content[0].text
+    assert "<svg>" in text
+
+
+@respx.mock
+async def test_api_error_becomes_tool_error():
+    respx.post(f"{API}/qrcodes").mock(return_value=httpx.Response(
+        400, json={"error": "Missing or invalid required field: target_url",
+                   "code": "invalid_target_url"}))
+    with pytest.raises(Exception) as exc:
+        await _call("create_url_qrcode", {"target_url": "not a url"})
+    assert "invalid_target_url" in str(exc.value)