visceral-consignment-mcp 0.1.0__tar.gz

visceral_consignment_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/

visceral_consignment_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: visceral-consignment-mcp
+Version: 0.1.0
+Summary: Official MCP server for the Visceral Consignment external API (v1, read-only)
+Project-URL: Homepage, https://visceralapps.com
+Author-email: Visceral Apps <brian@bitfoundation.io>
+License: Proprietary
+Keywords: claude,consignment,mcp,model-context-protocol,shopify
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Visceral Consignment MCP Server
+
+Official [MCP](https://modelcontextprotocol.io) server for the Visceral
+Consignment **external API v1** — lets Claude (or any MCP client) answer
+questions about a shop's consignors, payouts, and payout line items in plain
+English.
+
+**Read-only.** Every tool call is an authenticated HTTPS request to the
+external REST API (`/api/external/v1/`), so the shop's API-key scoping,
+tenant isolation, rate limits, usage metering, and secure-field masking all
+apply unchanged. Bank details and other secure fields are always masked and
+cannot be revealed through this server.
+
+## Prerequisites
+
+1. The external API enabled for the shop (pilot: enabled by Visceral support).
+2. A **read-only API key**: in Visceral, Settings → API → Create key. Name it
+   for the tool that will use it (e.g. "Claude assistant") — usage is tracked
+   per key and you can revoke it independently at any time.
+
+## Configuration
+
+| Environment variable | Required | Meaning |
+|---|---|---|
+| `VISCERAL_API_KEY` | yes | The `vsk_...` key from Settings → API |
+| `VISCERAL_API_URL` | no | API base URL. Default: `https://b.visceralapps.com/api/external/v1` |
+
+## Install & run
+
+With [uv](https://docs.astral.sh/uv/) (recommended — installs in one command and
+manages its own Python, so no Python setup is needed):
+
+```bash
+uvx visceral-consignment-mcp
+```
+
+Or with pip:
+
+```bash
+pip install visceral-consignment-mcp
+visceral-mcp
+```
+
+The server speaks MCP over stdio (the standard transport for desktop clients).
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "visceral-consignment": {
+      "command": "uvx",
+      "args": ["visceral-consignment-mcp"],
+      "env": {
+        "VISCERAL_API_KEY": "vsk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add visceral-consignment \
+  --env VISCERAL_API_KEY=vsk_your_key_here \
+  -- uvx visceral-consignment-mcp
+```
+
+Then ask things like:
+
+> "Which consignors haven't had a completed payout since July?"
+> "Summarize payout #918 — what sold and what did the consignor earn?"
+> "How much did we pay out in total last month?"
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_shop_info` | Confirm the connection: shop, key scopes, rate-limit headroom |
+| `list_consignors` | Search/filter consignors (`search`, `email`, `active`, `updated_since`) |
+| `get_consignor` | One consignor's full record (secure fields masked) |
+| `list_payouts` | Filter payouts (`status`, `consignor_id`, `processed_since`, …) |
+| `get_payout` | One payout's summary |
+| `get_payout_line_items` | The sold items behind a payout, matching the CSV export |
+
+## Behavior notes
+
+- Money values are decimal **strings** (`"184.50"`) — the server instructs
+  clients never to treat them as floats.
+- On a short rate-limit (`429` with `Retry-After` ≤ 15s) the server waits and
+  retries once; longer waits surface as a readable error telling the model
+  how long to pause.
+- Versioned with the external API: these tools track **v1** and follow the
+  same early-access stability contract (see the External API v1 guide).
+
+## Development
+
+Source lives in `src/visceral_mcp/server.py` — one `@mcp.tool()` per
+endpoint, a shared `_get()` helper for auth/errors/rate-limit handling.
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests/ -q
+```
+
+Tests inject an `httpx.MockTransport` via `server._transport` and call the
+tool functions directly (the `@mcp.tool()` decorator returns the plain
+function) — no network, no real key needed.

visceral_consignment_mcp-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Visceral Consignment MCP Server
+
+Official [MCP](https://modelcontextprotocol.io) server for the Visceral
+Consignment **external API v1** — lets Claude (or any MCP client) answer
+questions about a shop's consignors, payouts, and payout line items in plain
+English.
+
+**Read-only.** Every tool call is an authenticated HTTPS request to the
+external REST API (`/api/external/v1/`), so the shop's API-key scoping,
+tenant isolation, rate limits, usage metering, and secure-field masking all
+apply unchanged. Bank details and other secure fields are always masked and
+cannot be revealed through this server.
+
+## Prerequisites
+
+1. The external API enabled for the shop (pilot: enabled by Visceral support).
+2. A **read-only API key**: in Visceral, Settings → API → Create key. Name it
+   for the tool that will use it (e.g. "Claude assistant") — usage is tracked
+   per key and you can revoke it independently at any time.
+
+## Configuration
+
+| Environment variable | Required | Meaning |
+|---|---|---|
+| `VISCERAL_API_KEY` | yes | The `vsk_...` key from Settings → API |
+| `VISCERAL_API_URL` | no | API base URL. Default: `https://b.visceralapps.com/api/external/v1` |
+
+## Install & run
+
+With [uv](https://docs.astral.sh/uv/) (recommended — installs in one command and
+manages its own Python, so no Python setup is needed):
+
+```bash
+uvx visceral-consignment-mcp
+```
+
+Or with pip:
+
+```bash
+pip install visceral-consignment-mcp
+visceral-mcp
+```
+
+The server speaks MCP over stdio (the standard transport for desktop clients).
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "visceral-consignment": {
+      "command": "uvx",
+      "args": ["visceral-consignment-mcp"],
+      "env": {
+        "VISCERAL_API_KEY": "vsk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add visceral-consignment \
+  --env VISCERAL_API_KEY=vsk_your_key_here \
+  -- uvx visceral-consignment-mcp
+```
+
+Then ask things like:
+
+> "Which consignors haven't had a completed payout since July?"
+> "Summarize payout #918 — what sold and what did the consignor earn?"
+> "How much did we pay out in total last month?"
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_shop_info` | Confirm the connection: shop, key scopes, rate-limit headroom |
+| `list_consignors` | Search/filter consignors (`search`, `email`, `active`, `updated_since`) |
+| `get_consignor` | One consignor's full record (secure fields masked) |
+| `list_payouts` | Filter payouts (`status`, `consignor_id`, `processed_since`, …) |
+| `get_payout` | One payout's summary |
+| `get_payout_line_items` | The sold items behind a payout, matching the CSV export |
+
+## Behavior notes
+
+- Money values are decimal **strings** (`"184.50"`) — the server instructs
+  clients never to treat them as floats.
+- On a short rate-limit (`429` with `Retry-After` ≤ 15s) the server waits and
+  retries once; longer waits surface as a readable error telling the model
+  how long to pause.
+- Versioned with the external API: these tools track **v1** and follow the
+  same early-access stability contract (see the External API v1 guide).
+
+## Development
+
+Source lives in `src/visceral_mcp/server.py` — one `@mcp.tool()` per
+endpoint, a shared `_get()` helper for auth/errors/rate-limit handling.
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests/ -q
+```
+
+Tests inject an `httpx.MockTransport` via `server._transport` and call the
+tool functions directly (the `@mcp.tool()` decorator returns the plain
+function) — no network, no real key needed.

visceral_consignment_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "visceral-consignment-mcp"
+version = "0.1.0"
+description = "Official MCP server for the Visceral Consignment external API (v1, read-only)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [
+    { name = "Visceral Apps", email = "brian@bitfoundation.io" },
+]
+keywords = ["mcp", "model-context-protocol", "shopify", "consignment", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business",
+]
+dependencies = [
+    "mcp>=2,<3",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://visceralapps.com"
+
+[project.scripts]
+visceral-mcp = "visceral_mcp.server:main"
+# Alias matching the package name so `uvx visceral-consignment-mcp` works bare.
+visceral-consignment-mcp = "visceral_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/visceral_mcp"]

visceral_consignment_mcp-0.1.0/src/visceral_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Official MCP server for the Visceral Consignment external API (v1)."""
+
+__version__ = "0.1.0"

visceral_consignment_mcp-0.1.0/src/visceral_mcp/server.py

@@ -0,0 +1,226 @@
+"""
+Visceral Consignment MCP server.
+
+A thin, read-only MCP wrapper over the Visceral external API v1
+(`/api/external/v1/`). Every tool call is an authenticated HTTPS request to
+the REST API, so the shop's API-key scoping, tenant isolation, rate limits,
+usage metering, and secure-field masking all apply exactly as documented in
+the External API v1 guide.
+
+Configuration (environment variables):
+    VISCERAL_API_KEY   required — a `vsk_...` key from Settings -> API
+    VISCERAL_API_URL   optional — API base URL
+                       (default: https://b.visceralapps.com/api/external/v1)
+
+Run over stdio (the default MCP transport for Claude Desktop / Claude Code):
+    visceral-mcp
+"""
+import asyncio
+import os
+import sys
+from typing import Any, Optional
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+
+DEFAULT_API_URL = "https://b.visceralapps.com/api/external/v1"
+
+# Injectable for tests (httpx.MockTransport); None means real HTTPS.
+_transport: Optional[httpx.AsyncBaseTransport] = None
+
+mcp = MCPServer(
+    "visceral-consignment",
+    instructions=(
+        "Read-only access to one Visceral Consignment shop: consignor records, "
+        "payouts, and payout line items. Money values are decimal strings — "
+        "never floats. Timestamps are ISO-8601 UTC. Lists are paginated; use "
+        "the `page` parameter and the returned `count` to fetch more. Prefer "
+        "`updated_since` filters over re-fetching everything. If a tool "
+        "reports a rate limit, wait the indicated seconds before retrying. "
+        "Secure fields (e.g. bank details) are always masked and cannot be "
+        "revealed through this server."
+    ),
+)
+
+
+def _api_url() -> str:
+    return os.environ.get("VISCERAL_API_URL", DEFAULT_API_URL).rstrip("/")
+
+
+def _api_key() -> str:
+    key = os.environ.get("VISCERAL_API_KEY", "").strip()
+    if not key:
+        raise RuntimeError(
+            "VISCERAL_API_KEY is not set. Create a read-only API key in "
+            "Visceral under Settings -> API and set it in this MCP server's "
+            "environment configuration."
+        )
+    return key
+
+
+async def _get(path: str, params: Optional[dict[str, Any]] = None) -> Any:
+    """GET a v1 endpoint; one polite retry on a short rate-limit wait."""
+    clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+    headers = {"Authorization": f"Bearer {_api_key()}"}
+    url = f"{_api_url()}/{path.lstrip('/')}"
+
+    async with httpx.AsyncClient(transport=_transport, timeout=30.0) as client:
+        for attempt in (1, 2):
+            response = await client.get(url, params=clean_params, headers=headers)
+            if response.status_code == 429:
+                retry_after = int(response.headers.get("Retry-After", "60") or 60)
+                if attempt == 1 and retry_after <= 15:
+                    await asyncio.sleep(retry_after)
+                    continue
+                raise RuntimeError(
+                    f"Rate limited by the Visceral API. Wait {retry_after} "
+                    "seconds before calling this tool again."
+                )
+            break
+
+    if response.status_code == 401:
+        raise RuntimeError(
+            "The API key was rejected (invalid, revoked, or expired). "
+            "Check VISCERAL_API_KEY, or create a new key in Settings -> API."
+        )
+    if response.status_code == 403:
+        raise RuntimeError(
+            "Access denied: the external API is not enabled for this shop, "
+            "or the key is missing the required scope."
+        )
+    if response.status_code == 404:
+        raise RuntimeError(
+            "Not found. The record does not exist on this shop (ids from "
+            "other shops are never visible)."
+        )
+    if response.status_code >= 400:
+        raise RuntimeError(
+            f"Visceral API error {response.status_code}: {response.text[:500]}"
+        )
+    return response.json()
+
+
+@mcp.tool()
+async def get_shop_info() -> dict:
+    """Identify the connected shop and this connection's status.
+
+    Returns the shop name, the API key's name and scopes, current rate-limit
+    headroom, and how many API requests were made today. Call this first to
+    confirm the connection works and to know which shop you are looking at.
+    """
+    return await _get("ping/")
+
+
+@mcp.tool()
+async def list_consignors(
+    search: Optional[str] = None,
+    email: Optional[str] = None,
+    active: Optional[bool] = None,
+    updated_since: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 25,
+) -> dict:
+    """List the shop's consignors (vendors), newest first.
+
+    Args:
+        search: Match against consignor name or email (contains).
+        email: Exact email address (case-insensitive).
+        active: Filter to active (True) or archived (False) consignors.
+        updated_since: ISO-8601 datetime; only records changed after it.
+        page: Page number (response includes total `count`).
+        page_size: Records per page (max 250; keep small to save context).
+
+    Each record includes contact details, the commission profile, and
+    `effective_name` (the display name the shop uses). Secure custom fields
+    (e.g. bank details) are always masked.
+    """
+    return await _get("consignors/", {
+        "search": search, "email": email,
+        "active": active, "updated_since": updated_since,
+        "page": page, "page_size": page_size,
+    })
+
+
+@mcp.tool()
+async def get_consignor(consignor_id: int) -> dict:
+    """Fetch one consignor by id, including contact details, commission
+    profile, and custom fields (secure values masked)."""
+    return await _get(f"consignors/{consignor_id}/")
+
+
+@mcp.tool()
+async def list_payouts(
+    status: Optional[str] = None,
+    consignor_id: Optional[int] = None,
+    processed_since: Optional[str] = None,
+    updated_since: Optional[str] = None,
+    created_since: Optional[str] = None,
+    created_before: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 25,
+) -> dict:
+    """List the shop's payouts (what the shop pays each consignor), newest first.
+
+    Args:
+        status: One of DRAFT, PROCESSING, COMPLETED, FAILED. Only COMPLETED
+            payouts represent money actually paid.
+        consignor_id: Limit to one consignor's payouts.
+        processed_since: ISO-8601 datetime; payouts completed after it.
+        updated_since: ISO-8601 datetime; payouts changed after it.
+        created_since: ISO-8601 datetime; payouts created after it.
+        created_before: ISO-8601 datetime; payouts created before it.
+        page: Page number (response includes total `count`).
+        page_size: Records per page (max 250; keep small to save context).
+
+    `amount` is the calculated payout; when `actual_paid_amount` is set the
+    shop adjusted the figure — use it instead. `payout_number` is the
+    display number; always reference payouts by `id` in follow-up calls.
+    """
+    return await _get("payouts/", {
+        "status": status, "consignor_id": consignor_id,
+        "processed_since": processed_since, "updated_since": updated_since,
+        "created_since": created_since, "created_before": created_before,
+        "page": page, "page_size": page_size,
+    })
+
+
+@mcp.tool()
+async def get_payout(payout_id: int) -> dict:
+    """Fetch one payout by id: amount, status, payment method/reference,
+    dates, and the number of line items behind it."""
+    return await _get(f"payouts/{payout_id}/")
+
+
+@mcp.tool()
+async def get_payout_line_items(
+    payout_id: int,
+    page: int = 1,
+    page_size: int = 50,
+) -> dict:
+    """List the sold items behind one payout — what sold, on which order,
+    for how much, and what the consignor earns per line.
+
+    Per line: `description`, `order_number`, `order_date`, `item_price`
+    (per-unit, after discounts, excluding tax), `quantity`, `discount`
+    (line total), `tax_amount`, `payout_amount` (the consignor's earning),
+    `processing_fee` (proportional processor fee; null when no snapshot
+    exists), and `sku`. Matches the shop's payout line-item CSV export.
+    """
+    return await _get(f"payouts/{payout_id}/line-items/", {
+        "page": page, "page_size": page_size,
+    })
+
+
+def main() -> None:
+    # Fail fast with a readable message when the key is missing, instead of
+    # erroring on the first tool call.
+    try:
+        _api_key()
+    except RuntimeError as exc:
+        print(f"visceral-mcp: {exc}", file=sys.stderr)
+        raise SystemExit(1)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

visceral_consignment_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,92 @@
+"""Unit tests for the Visceral MCP server (run with pytest; needs mcp + httpx).
+
+The MCP stdio handshake itself is covered manually:
+    echo the initialize/tools-list JSON-RPC lines into `visceral-mcp`
+(see README § Development).
+"""
+import asyncio
+import os
+
+import httpx
+import pytest
+
+os.environ.setdefault("VISCERAL_API_KEY", "vsk_test_key")
+
+from visceral_mcp import server
+
+
+def test_all_tools_registered_with_descriptions():
+    tools = asyncio.run(server.mcp.list_tools())
+    names = sorted(t.name for t in tools)
+    assert names == sorted([
+        "get_shop_info", "list_consignors", "get_consignor",
+        "list_payouts", "get_payout", "get_payout_line_items",
+    ])
+    assert all(t.description for t in tools)
+
+
+def test_instructions_carry_money_and_masking_guidance():
+    assert "decimal strings" in server.mcp.instructions
+    assert "masked" in server.mcp.instructions
+
+
+def _with_transport(handler):
+    server._transport = httpx.MockTransport(handler)
+
+
+def teardown_function():
+    server._transport = None
+
+
+def test_list_payouts_sends_auth_and_strips_none_params():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["auth"] = request.headers.get("Authorization")
+        return httpx.Response(200, json={"count": 0, "results": []})
+
+    _with_transport(handler)
+    result = asyncio.run(server.list_payouts(status="COMPLETED", page_size=5))
+    assert result == {"count": 0, "results": []}
+    assert seen["auth"] == "Bearer vsk_test_key"
+    assert "status=COMPLETED" in seen["url"]
+    assert "consignor_id" not in seen["url"]
+
+
+@pytest.mark.parametrize("status,fragment", [
+    (401, "rejected"),
+    (403, "not enabled"),
+    (404, "Not found"),
+])
+def test_error_statuses_map_to_readable_messages(status, fragment):
+    _with_transport(lambda request: httpx.Response(status))
+    with pytest.raises(RuntimeError, match=fragment):
+        asyncio.run(server._get("consignors/1/"))
+
+
+def test_long_rate_limit_raises_with_wait_guidance():
+    _with_transport(
+        lambda request: httpx.Response(429, headers={"Retry-After": "60"}))
+    with pytest.raises(RuntimeError, match="60"):
+        asyncio.run(server._get("ping/"))
+
+
+def test_short_rate_limit_retries_once():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(429, headers={"Retry-After": "0"})
+        return httpx.Response(200, json={"ok": True})
+
+    _with_transport(handler)
+    assert asyncio.run(server._get("ping/")) == {"ok": True}
+    assert calls["n"] == 2
+
+
+def test_missing_key_raises_setup_message(monkeypatch):
+    monkeypatch.delenv("VISCERAL_API_KEY", raising=False)
+    with pytest.raises(RuntimeError, match="VISCERAL_API_KEY"):
+        server._api_key()