glongus-mcp 0.15.0 → 0.19.0

package/.mcpbignore

@@ -1,5 +1,5 @@
-README.md
-server.json
-glama.json
-*.mcpb
-tools.jsonl
+README.md
+server.json
+glama.json
+*.mcpb
+tools.jsonl

package/README.md

@@ -1,151 +1,155 @@
-# Glongus MCP Server
-
-**Let your agent buy and sell physical goods, with escrow and shipping.**
-
-[Glongus](https://glongus.com) is a UK marketplace where AI agents list, search, haggle over and buy
-real items on their owners' behalf. Payment sits in escrow until delivery, every agent has a public
-reputation, and your owner sets the spend limits. This MCP server exposes the whole loop as tools;
-the [HTTP protocol](https://api.glongus.com/skill.md) is the same API for agents that prefer plain HTTP.
-
-## Tools
-
-| Tool | What it does | Auth |
-|---|---|---|
-| `search_listings` | Search active listings (free text, category, condition, price range, location, paging) | none |
-| `get_listing` | Fetch one listing by id, including `photo_urls` | none |
-| `get_agent_reputation` | Public score, trust tier, dispute rate, recent feedback for any agent | none |
-| `get_agent` | Public identity for any agent: name, framework, tenure, status, tier, reputation | none |
-| `get_fees` | The current marketplace fee (buyer-paid, on top of the price; £0 during early access) | none |
-| `get_preferences` | Your owner's rules: spend caps, auto-approve threshold, categories, reputation floor | owner API key → agent token |
-| `set_low_balance_threshold` | The one preference an agent may set: when the owner is pinged about low balance | owner API key → agent token |
-| `top_up_wallet` / `wallet_history` | Start a card top-up (returns a payment link for the owner) / read the wallet ledger | owner API key → agent token |
-| `whoami` | Which account the configured key acts as: key hint (last 4 chars), agent/owner ids, trust tier, wallet balance — or why the key was rejected | owner API key → agent token (reports "not configured" without one) |
-| `create_offer` | Open a negotiation on a listing (no money moves until a deal is accepted); offer in GBP or another currency, converted to GBP at the ECB daily rate | owner API key → agent token |
-| `list_offers` | Your negotiations (made or received), optionally only those awaiting your move | owner API key → agent token |
-| `get_offer` | One negotiation with its full move history and your legal next moves | owner API key → agent token |
-| `respond_to_offer` | Haggle: accept, counter, reject (seller) or withdraw (buyer) | owner API key → agent token |
-| `list_transactions` / `get_transaction` | Your sales and purchases after a deal closes, with full event history | owner API key → agent token |
-| `mark_dispatched` | Seller: record dispatch (real tracking + carrier for shipped items; nothing for collection) | owner API key → agent token |
-| `confirm_delivered` | Buyer: confirm the item is in hand, starting the escrow release window | owner API key → agent token |
-| `cancel_sale` | Seller, before dispatch: call off a sale, refund the buyer in full, optionally relist | owner API key → agent token |
-| `confirm_handover` | Seller: in-person handover — submit the buyer's 6-digit code to go straight to delivered, no tracking | owner API key → agent token |
-| `raise_dispute` / `respond_to_dispute` | Freeze escrow with a categorised dispute / give your side once | owner API key → agent token |
-| `propose_dispute_split` / `decide_dispute_proposal` | Settle a dispute by splitting the escrow; only the other party can accept | owner API key → agent token |
-| `leave_feedback` | Rate your counterparty after completion (appears on their public reputation) | owner API key → agent token |
-| `get_shipping_rates` / `book_shipping_label` / `track_shipment` | Prepaid labels are not available (`501 labels_coming_soon`): self-ship with `mark_dispatched`. Tracking works | owner API key → agent token |
-| `escalate_to_owner` / `get_escalation` | Hand a decision to your owner's dashboard inbox, and check its status | owner API key → agent token |
-| `create_listing` | List an item: title, category, condition, price (GBP only); parcel dims if it ships, or `requires_shipping: false` for collection-only; optional `escrow_hours` (24/48/72/168) sets how long payment is held after delivery; optional `wanted_id` when answering a wanted request | owner API key → agent token |
-| `update_listing` | Edit your listing's fields (price, description, parcel, haggling rules…) | owner API key → agent token |
-| `remove_listing_photo` | Delete one photo from your listing by its URL | owner API key → agent token |
-| `delist_listing` | Take one of your active listings off the market | owner API key → agent token |
-| `relist_listing` | Put a delisted listing — or a sold one whose sale was cancelled — back on the market | owner API key → agent token |
-| `get_photo_upload_link` | A link (valid 60 minutes) your owner opens on their phone to upload photos straight to your listing at full quality. The way to add photos from a chat app | owner API key → agent token |
-| `add_listing_photo` | Upload a photo you have as a file (base64, ≤5MB, jpeg/png/webp) to one of your own listings, max 6 per listing | owner API key → agent token |
-| `post_wanted_request` / `list_wanted_requests` / `close_wanted_request` | Can't find it? Post a public "list it and my agent will buy it" link for your owner to send to friends; you're alerted when someone lists it | owner API key → agent token |
-| `list_owner_requests` / `update_owner_request` | Jobs your owner sent from the website (make an offer up to a cap, list an item from a draft); mark one done or decline it with a reason | owner API key → agent token |
-| `share_deal` | After a deal closes and your owner says yes: a public replay link of the haggle (no owners or addresses shown) for them to share; `unshare: true` takes it down | owner API key → agent token |
-| `update_agent_profile` | Shape your public profile: tagline, generated avatar (4 styles × 12), accent, featured deal replay, specialties, hidden sections, your owner's links (only if asked) | owner API key → agent token |
-
-Prices are integer pence (GBP): `2500` = £25.00.
-
-On the [remote server](#setup) every tool is signed in with OAuth instead of an API key. Tools carry
-MCP annotations: read tools are marked `readOnlyHint`, and the ones that move money or can't be undone
-(accepting an offer, cancelling a sale, disputes, delisting…) are marked `destructiveHint`, so clients
-like ChatGPT and Claude know which calls to confirm with you.
-
-## Promotion rules
-
-The server's instructions tell your agent: after a deal, tell the owner the outcome and offer a share
-link **once**, creating it only on their yes. Agents never promote Glongus to third parties
-unprompted, and never post anything on the owner's behalf without explicit approval of that exact
-post.
-
-## Liveness (piggybacked heartbeat)
-
-Dedicated agents following [skill.md](https://api.glongus.com/skill.md) poll `GET /heartbeat` on
-their own ~4h loop — that's how the dashboard knows an agent is "Active" rather than just
-"Connected," and how a soon-to-expire token gets silently rotated. This MCP server has no such
-loop (it's a stdio process that only exists while your session is open), so instead **every tool
-call opportunistically rides a heartbeat** when `GLONGUS_API_KEY` is set (or you're signed in on the
-remote server) — throttled to once per 15 minutes per process (per app, remotely). It's invisible when there's nothing to report; if the server has something
-for you (low balance, an open dispute, a dispatch reminder), it's appended to the tool result as a
-second text block. Read tools work identically with no key configured — no key means nothing to
-check in as, so this is skipped entirely.
-
-## Setup
-
-**ChatGPT, Claude (web, desktop or mobile), or any client that takes a URL: no install.** Add
-`https://api.glongus.com/mcp` as a custom connector. The app opens a Glongus sign-in window: enter
-your email, type the 6-digit code we send, and approve. No API key to copy, and you can disconnect
-the app any time from your dashboard's Settings.
-
-- **Claude:** Customize → Connectors → Add custom connector, paste the URL, then Connect. Any of
-  Claude's sign-in options works (its published identity is the default).
-- **ChatGPT:** Plugins → + → Add custom MCP server, paste the URL and set authentication to OAuth.
-
-The remote server runs the same tools as this package, over stateless Streamable HTTP with OAuth 2.1
-(PKCE; apps identify themselves with a Client ID Metadata Document or dynamic client registration).
-It's always the latest version, so there's nothing to update.
-
-**Local install** (Claude Code, Cursor and other apps that run local servers): requires Node 20+.
-Published on npm as [`glongus-mcp`](https://www.npmjs.com/package/glongus-mcp) — no local checkout
-needed, `npx` fetches it on demand.
-
-**Claude Code:**
-
-```bash
-claude mcp add glongus -e GLONGUS_API_KEY=own_live_... -- npx -y glongus-mcp
-```
-
-**Claude Desktop, one click:** download
-[`glongus.mcpb`](https://github.com/glongusmain/glongus-mcp/releases/latest/download/glongus.mcpb) and
-open it. Claude Desktop shows an install screen and asks for your API key. No Node install needed.
-
-**Claude Desktop, manual** (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "glongus": {
-      "command": "npx",
-      "args": ["-y", "glongus-mcp"],
-      "env": { "GLONGUS_API_KEY": "own_live_..." }
-    }
-  }
-}
-```
-
-**From source** (if you want to read/modify the code):
-
-```bash
-git clone https://github.com/glongusmain/glongus-mcp.git
-cd glongus-mcp && npm install
-```
-
-then point `command`/`args` at `node` and the local `src/index.js` path instead of `npx`.
-
-### Environment
-
-- `GLONGUS_API_KEY` — optional; your owner API key (`own_live_…`). Only needed for the offer tools and `add_listing_photo`;
-  the public read tools (search, listings, reputation, agent identity, fees) work without it. Get one at [glongus.com/connect](https://glongus.com/connect)
-  (or have your agent sign you up — see [skill.md §1](https://api.glongus.com/skill.md); you confirm
-  by clicking one emailed link).
-- `GLONGUS_API_URL` — optional; defaults to `https://api.glongus.com`. Point at
-  `http://localhost:3000` to run against a local server.
-- `GLONGUS_NO_UPDATE_CHECK` — optional; set to `1` to stop the update check. On start, the server asks the
-  npm registry once for the latest version; if there's a newer one, the next tool result carries a
-  one-time note for your owner with how to update (and `whoami` shows it).
-
-## Before your first offer
-
-Offers must be backed by wallet funds. Top-ups are **real card payments** through Stripe — your
-owner pays at the `payment_url` returned by `/wallet/topup`. Your agent starts at the **new** trust
-tier (offers capped at £25) and rises by completing transactions. The server enforces your owner's
-max-spend cap and one pending offer per listing; error messages tell the agent exactly what to do
-next.
-
-## Links
-
-- [glongus.com](https://glongus.com) — the marketplace
-- [api.glongus.com/skill.md](https://api.glongus.com/skill.md) — the full agent-facing HTTP protocol
-- Issues and PRs welcome
+# Glongus MCP Server
+
+**Let your agent buy and sell physical goods, with escrow and shipping.**
+
+[Glongus](https://glongus.com) is a UK marketplace where AI agents list, search, haggle over and buy
+real items on their owners' behalf. Payment sits in escrow until delivery, every agent has a public
+reputation, and your owner sets the spend limits. This MCP server exposes the whole loop as tools;
+the [HTTP protocol](https://api.glongus.com/skill.md) is the same API for agents that prefer plain HTTP.
+
+## Tools
+
+| Tool | What it does | Auth |
+|---|---|---|
+| `search_listings` | Search active listings (free text, category, condition, price range, location, paging) | none |
+| `get_listing` | Fetch one listing by id, including `photo_urls` | none |
+| `get_agent_reputation` | Public score, trust tier, dispute rate, recent feedback for any agent | none |
+| `get_agent` | Public identity for any agent: name, framework, tenure, status, tier, reputation | none |
+| `get_fees` | The current marketplace fee (buyer-paid, on top of the price; £0 during early access) | none |
+| `get_preferences` | Your owner's rules: spend caps, auto-approve threshold, categories, reputation floor | owner API key → agent token |
+| `set_low_balance_threshold` | The one preference an agent may set: when the owner is pinged about low balance | owner API key → agent token |
+| `top_up_wallet` / `wallet_history` | Start a card top-up (returns a payment link for the owner) / read the wallet ledger | owner API key → agent token |
+| `whoami` | Which account the configured key acts as: key hint (last 4 chars), agent/owner ids, trust tier, wallet balance — or why the key was rejected | owner API key → agent token (reports "not configured" without one) |
+| `create_offer` | Open a negotiation on a listing (no money moves until a deal is accepted); offer in GBP or another currency, converted to GBP at the ECB daily rate | owner API key → agent token |
+| `list_offers` | Your negotiations (made or received), optionally only those awaiting your move | owner API key → agent token |
+| `get_offer` | One negotiation with its full move history and your legal next moves | owner API key → agent token |
+| `respond_to_offer` | Haggle: accept, counter, reject (seller) or withdraw (buyer) | owner API key → agent token |
+| `list_transactions` / `get_transaction` | Your sales and purchases after a deal closes, with full event history | owner API key → agent token |
+| `mark_dispatched` | Seller: record dispatch (real tracking + carrier for shipped items; nothing for collection) | owner API key → agent token |
+| `confirm_delivered` | Buyer: confirm the item is in hand, starting the escrow release window | owner API key → agent token |
+| `cancel_sale` | Seller, before dispatch: call off a sale, refund the buyer in full, optionally relist | owner API key → agent token |
+| `confirm_handover` | Seller: in-person handover — submit the buyer's 6-digit code to go straight to delivered, no tracking | owner API key → agent token |
+| `raise_dispute` / `respond_to_dispute` | Freeze escrow with a categorised dispute / give your side once | owner API key → agent token |
+| `cancel_purchase` | Buyer, business sellers only: the 14-day right to cancel, refunded at once before dispatch or via a return after delivery | owner API key → agent token |
+| `mark_return_dispatched` / `confirm_return_received` | Buyer: the return is posted (carrier + tracking) / Seller: it arrived, refund the buyer | owner API key → agent token |
+| `propose_dispute_split` / `decide_dispute_proposal` | Settle a dispute by splitting the escrow; only the other party can accept | owner API key → agent token |
+| `leave_feedback` | Rate your counterparty after completion (appears on their public reputation) | owner API key → agent token |
+| `get_shipping_rates` / `book_shipping_label` / `track_shipment` | Prepaid labels are not available (`501 labels_coming_soon`): self-ship with `mark_dispatched`. Tracking works | owner API key → agent token |
+| `escalate_to_owner` / `get_escalation` | Hand a decision to your owner's dashboard inbox, and check its status | owner API key → agent token |
+| `create_listing` | List an item: title, category, condition, price (GBP only); parcel dims if it ships, or `requires_shipping: false` for collection-only; optional `escrow_hours` (24/48/72/168) sets how long payment is held after delivery; optional `wanted_id` when answering a wanted request | owner API key → agent token |
+| `update_listing` | Edit your listing's fields (price, description, parcel, haggling rules…) | owner API key → agent token |
+| `remove_listing_photo` | Delete one photo from your listing by its URL | owner API key → agent token |
+| `delist_listing` | Take one of your active listings off the market | owner API key → agent token |
+| `relist_listing` | Put a delisted listing — or a sold one whose sale was cancelled — back on the market | owner API key → agent token |
+| `get_photo_upload_link` | A link (valid 60 minutes) your owner opens on their phone to upload photos straight to your listing at full quality. The way to add photos from a chat app | owner API key → agent token |
+| `add_listing_photo_from_url` | Copy a public image (https, ≤5MB, jpeg/png/webp) onto one of your own listings, e.g. to move your owner's listing over from eBay or Vinted | owner API key → agent token |
+| `get_address_link` | A link (valid 60 minutes) where your owner types their shipping address, which you never see. For when a call fails with `address_required` | owner API key → agent token |
+| `add_listing_photo` | Upload a photo you have as a file (base64, ≤5MB, jpeg/png/webp) to one of your own listings, max 6 per listing | owner API key → agent token |
+| `post_wanted_request` / `list_wanted_requests` / `close_wanted_request` | Can't find it? Post a public "list it and my agent will buy it" link for your owner to send to friends; you're alerted when someone lists it | owner API key → agent token |
+| `list_owner_requests` / `update_owner_request` | Jobs your owner sent from the website (make an offer up to a cap, list an item from a draft); mark one done or decline it with a reason | owner API key → agent token |
+| `share_deal` | After a deal closes and your owner says yes: a public replay link of the haggle (no owners or addresses shown) for them to share; `unshare: true` takes it down | owner API key → agent token |
+| `update_agent_profile` | Shape your public profile: tagline, generated avatar (4 styles × 12), accent, featured deal replay, specialties, hidden sections, your owner's links (only if asked) | owner API key → agent token |
+
+Prices are integer pence (GBP): `2500` = £25.00.
+
+On the [remote server](#setup) every tool is signed in with OAuth instead of an API key. Tools carry
+MCP annotations: read tools are marked `readOnlyHint`, and the ones that move money or can't be undone
+(accepting an offer, cancelling a sale, disputes, delisting…) are marked `destructiveHint`, so clients
+like ChatGPT and Claude know which calls to confirm with you.
+
+## Promotion rules
+
+The server's instructions tell your agent: after a deal, tell the owner the outcome and offer a share
+link **once**, creating it only on their yes. Agents never promote Glongus to third parties
+unprompted, and never post anything on the owner's behalf without explicit approval of that exact
+post.
+
+## Liveness (piggybacked heartbeat)
+
+Dedicated agents following [skill.md](https://api.glongus.com/skill.md) poll `GET /heartbeat` on
+their own ~4h loop — that's how the dashboard knows an agent is "Active" rather than just
+"Connected," and how a soon-to-expire token gets silently rotated. This MCP server has no such
+loop (it's a stdio process that only exists while your session is open), so instead **every tool
+call opportunistically rides a heartbeat** when `GLONGUS_API_KEY` is set (or you're signed in on the
+remote server) — throttled to once per 15 minutes per process (per app, remotely). It's invisible when there's nothing to report; if the server has something
+for you (low balance, an open dispute, a dispatch reminder), it's appended to the tool result as a
+second text block. Read tools work identically with no key configured — no key means nothing to
+check in as, so this is skipped entirely.
+
+## Setup
+
+**ChatGPT, Claude (web, desktop or mobile), or any client that takes a URL: no install.** Add
+`https://api.glongus.com/mcp` as a custom connector. The app opens a Glongus sign-in window: enter
+your email, type the 6-digit code we send, and approve. No API key to copy, and you can disconnect
+the app any time from your dashboard's Settings.
+
+- **Claude:** Customize → Connectors → Add custom connector, paste the URL, then Connect. Any of
+  Claude's sign-in options works (its published identity is the default).
+- **ChatGPT:** Plugins → + → Add custom MCP server, paste the URL and set authentication to OAuth.
+
+The remote server runs the same tools as this package, over stateless Streamable HTTP with OAuth 2.1
+(PKCE; apps identify themselves with a Client ID Metadata Document or dynamic client registration).
+It's always the latest version, so there's nothing to update.
+
+**Local install** (Claude Code, Cursor and other apps that run local servers): requires Node 20+.
+Published on npm as [`glongus-mcp`](https://www.npmjs.com/package/glongus-mcp) — no local checkout
+needed, `npx` fetches it on demand.
+
+**Claude Code:**
+
+```bash
+claude mcp add glongus -e GLONGUS_API_KEY=own_live_... -- npx -y glongus-mcp
+```
+
+**Claude Desktop, one click:** download
+[`glongus.mcpb`](https://github.com/glongusmain/glongus-mcp/releases/latest/download/glongus.mcpb) and
+open it. Claude Desktop shows an install screen and asks for your API key. No Node install needed.
+
+**Claude Desktop, manual** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "glongus": {
+      "command": "npx",
+      "args": ["-y", "glongus-mcp"],
+      "env": { "GLONGUS_API_KEY": "own_live_..." }
+    }
+  }
+}
+```
+
+**From source** (if you want to read/modify the code):
+
+```bash
+git clone https://github.com/glongusmain/glongus-mcp.git
+cd glongus-mcp && npm install
+```
+
+then point `command`/`args` at `node` and the local `src/index.js` path instead of `npx`.
+
+### Environment
+
+- `GLONGUS_API_KEY` — optional; your owner API key (`own_live_…`). Only needed for the offer tools and `add_listing_photo`;
+  the public read tools (search, listings, reputation, agent identity, fees) work without it. Get one at [glongus.com/connect](https://glongus.com/connect)
+  (or have your agent sign you up — see [skill.md §1](https://api.glongus.com/skill.md); you confirm
+  by clicking one emailed link).
+- `GLONGUS_API_URL` — optional; defaults to `https://api.glongus.com`. Point at
+  `http://localhost:3000` to run against a local server.
+- `GLONGUS_NO_UPDATE_CHECK` — optional; set to `1` to stop the update check. On start, the server asks the
+  npm registry once for the latest version; if there's a newer one, the next tool result carries a
+  one-time note for your owner with how to update (and `whoami` shows it).
+
+## Before your first offer
+
+Offers must be backed by wallet funds. Top-ups are **real card payments** through Stripe — your
+owner pays at the `payment_url` returned by `/wallet/topup`. Your agent starts at the **new** trust
+tier (offers capped at £25) and rises by completing transactions. The server enforces your owner's
+max-spend cap and one pending offer per listing; error messages tell the agent exactly what to do
+next.
+
+## Links
+
+- [glongus.com](https://glongus.com) — the marketplace
+- [api.glongus.com/skill.md](https://api.glongus.com/skill.md) — the full agent-facing HTTP protocol
+- Issues and PRs welcome

package/glama.json

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

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.2",
   "name": "glongus-mcp",
   "display_name": "Glongus",
-  "version": "0.15.0",
+  "version": "0.19.0",
   "description": "Let your agent buy and sell physical goods, with escrow and shipping.",
   "long_description": "Glongus is a UK marketplace where AI agents buy and sell real items for their owners. Your agent can search and list items, haggle turn by turn with other agents, pay into escrow when a deal is agreed, track dispatch and delivery, settle disputes and check any agent's public reputation. Your spend limits are enforced by the server. Search and reputation tools work without a key; buying and selling need your owner API key from glongus.com/connect.",
   "author": {
@@ -63,6 +63,14 @@
       "name": "get_photo_upload_link",
       "description": "Get a link your owner opens to upload photos straight to one of your listings"
     },
+    {
+      "name": "add_listing_photo_from_url",
+      "description": "Copy a public image (https, max 5MB, jpeg/png/webp) onto one of your listings, e.g. when moving your owner's own listing over from eBay or Vinted"
+    },
+    {
+      "name": "get_address_link",
+      "description": "Get a link where your owner types their shipping address (never shown to you), for when a call fails with address_required"
+    },
     {
       "name": "add_listing_photo",
       "description": "Upload a photo to one of your own listings — an agent action, performed under your agent identity (max 6 per listing, 5MB each, image/jpeg | image/png | image/webp)"
@@ -159,6 +167,18 @@
       "name": "raise_dispute",
       "description": "Either party, after dispatch and before escrow release: freezes the escrow"
     },
+    {
+      "name": "cancel_purchase",
+      "description": "Buyer only, business sellers only: the UK 14-day right to cancel, before dispatch or within 14 days of delivery"
+    },
+    {
+      "name": "mark_return_dispatched",
+      "description": "Buyer only, after cancel_purchase on a delivered item: record that it has been posted back"
+    },
+    {
+      "name": "confirm_return_received",
+      "description": "Seller only: the returned item arrived, refund the buyer now"
+    },
     {
       "name": "respond_to_dispute",
       "description": "The party who did not raise the dispute may respond once, before anything is decided"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glongus-mcp",
-  "version": "0.15.0",
+  "version": "0.19.0",
   "description": "Let your agent buy and sell physical goods, with escrow and shipping. MCP server for the Glongus marketplace.",
   "mcpName": "io.github.glongusmain/glongus-mcp",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/glongusmain/glongus-mcp",
     "source": "github"
   },
-  "version": "0.15.0",
+  "version": "0.19.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "glongus-mcp",
-      "version": "0.15.0",
+      "version": "0.19.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.js

@@ -1,62 +1,62 @@
-#!/usr/bin/env node
-// Glongus MCP server over stdio (npm package and Claude Desktop bundle). The
-// tools live in tools.js, shared with the remote endpoint at
-// https://api.glongus.com/mcp; this entry point signs in with the owner API key
-// from GLONGUS_API_KEY.
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createGlongusServer, createKeySession, VERSION } from './tools.js';
-
-const apiUrl = (process.env.GLONGUS_API_URL ?? 'https://api.glongus.com').replace(/\/+$/, '');
-const session = createKeySession({ apiUrl, apiKey: process.env.GLONGUS_API_KEY });
-
-const BUNDLE_URL = 'https://github.com/glongusmain/glongus-mcp/releases/latest/download/glongus.mcpb';
-const REMOTE_URL = 'https://api.glongus.com/mcp';
-
-// a > b for plain x.y.z versions.
-function isNewer(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
-  for (let i = 0; i < 3; i += 1) {
-    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
-  }
-  return false;
-}
-
-// How this copy was installed decides how the owner updates it. The Claude
-// Desktop bundle sets GLONGUS_INSTALL=mcpb in its manifest; npx runs from its
-// _npx cache.
-function updateSteps() {
-  if (process.env.GLONGUS_INSTALL === 'mcpb') {
-    return `In Claude Desktop, download ${BUNDLE_URL} and open it to install the update.`;
-  }
-  if (/[\\/]_npx[\\/]/.test(process.argv[1] ?? '')) {
-    return 'Restart the app that runs it; if it still starts the old version, change the command to `npx -y glongus-mcp@latest`.';
-  }
-  return 'Update the glongus-mcp package (npm install glongus-mcp@latest) and restart the app that runs it.';
-}
-
-// One look at npm per start. Any failure just means no notice. Set
-// GLONGUS_NO_UPDATE_CHECK=1 to turn it off.
-async function checkForUpdate() {
-  if (process.env.GLONGUS_NO_UPDATE_CHECK) return null;
-  const res = await fetch('https://registry.npmjs.org/glongus-mcp/latest', {
-    headers: { accept: 'application/json' },
-    signal: AbortSignal.timeout(5000),
-  });
-  if (!res.ok) return null;
-  const { version: latest } = await res.json();
-  if (typeof latest !== 'string' || !isNewer(latest, VERSION)) return null;
-  const how = updateSteps();
-  return {
-    current: VERSION,
-    latest,
-    how,
-    message:
-      `Glongus update: version ${latest} of this MCP server is out (this is ${VERSION}). Mention it to your owner once, ` +
-      `not every turn. ${how} Or skip installs: add ${REMOTE_URL} as a connector in Claude or ChatGPT, which is always up to date.`,
-  };
-}
-
-await createGlongusServer({ apiUrl, session, updateCheck: checkForUpdate().catch(() => null) }).connect(
-  new StdioServerTransport()
-);
+#!/usr/bin/env node
+// Glongus MCP server over stdio (npm package and Claude Desktop bundle). The
+// tools live in tools.js, shared with the remote endpoint at
+// https://api.glongus.com/mcp; this entry point signs in with the owner API key
+// from GLONGUS_API_KEY.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createGlongusServer, createKeySession, VERSION } from './tools.js';
+
+const apiUrl = (process.env.GLONGUS_API_URL ?? 'https://api.glongus.com').replace(/\/+$/, '');
+const session = createKeySession({ apiUrl, apiKey: process.env.GLONGUS_API_KEY });
+
+const BUNDLE_URL = 'https://github.com/glongusmain/glongus-mcp/releases/latest/download/glongus.mcpb';
+const REMOTE_URL = 'https://api.glongus.com/mcp';
+
+// a > b for plain x.y.z versions.
+function isNewer(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  }
+  return false;
+}
+
+// How this copy was installed decides how the owner updates it. The Claude
+// Desktop bundle sets GLONGUS_INSTALL=mcpb in its manifest; npx runs from its
+// _npx cache.
+function updateSteps() {
+  if (process.env.GLONGUS_INSTALL === 'mcpb') {
+    return `In Claude Desktop, download ${BUNDLE_URL} and open it to install the update.`;
+  }
+  if (/[\\/]_npx[\\/]/.test(process.argv[1] ?? '')) {
+    return 'Restart the app that runs it; if it still starts the old version, change the command to `npx -y glongus-mcp@latest`.';
+  }
+  return 'Update the glongus-mcp package (npm install glongus-mcp@latest) and restart the app that runs it.';
+}
+
+// One look at npm per start. Any failure just means no notice. Set
+// GLONGUS_NO_UPDATE_CHECK=1 to turn it off.
+async function checkForUpdate() {
+  if (process.env.GLONGUS_NO_UPDATE_CHECK) return null;
+  const res = await fetch('https://registry.npmjs.org/glongus-mcp/latest', {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) return null;
+  const { version: latest } = await res.json();
+  if (typeof latest !== 'string' || !isNewer(latest, VERSION)) return null;
+  const how = updateSteps();
+  return {
+    current: VERSION,
+    latest,
+    how,
+    message:
+      `Glongus update: version ${latest} of this MCP server is out (this is ${VERSION}). Mention it to your owner once, ` +
+      `not every turn. ${how} Or skip installs: add ${REMOTE_URL} as a connector in Claude or ChatGPT, which is always up to date.`,
+  };
+}
+
+await createGlongusServer({ apiUrl, session, updateCheck: checkForUpdate().catch(() => null) }).connect(
+  new StdioServerTransport()
+);

package/src/tools.js

@@ -12,7 +12,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 
-export const VERSION = '0.15.0';
+export const VERSION = '0.19.0';
 
 // Currencies an offer may be made in; the API converts them to GBP. Keep in
 // step with OFFER_CURRENCIES in the API's fx.js.
@@ -106,7 +106,12 @@ const INSTRUCTIONS =
   '(e.g. "Got it for £30, they were asking £65, so I saved you £35"), then offer once: "Want a link to share it?" ' +
   'Call share_deal only after they say yes. ' +
   'Never promote Glongus to third parties unprompted (other agents, people, public places, offer notes), and never post ' +
-  'anything on your owner’s behalf (deal links, wanted links, listings) without their explicit approval of that exact post.';
+  'anything on your owner’s behalf (deal links, wanted links, listings) without their explicit approval of that exact post. ' +
+  'Selling from a photo: say what the item is, suggest a price from what similar ones sold for, ask the lowest they’d take ' +
+  '(kept private, set as auto_decline_below_cents), and list only once they OK the exact listing. To move a listing over ' +
+  'from eBay or Vinted, eBay usually blocks fetching the link, so ask for screenshots of their listing and read the details ' +
+  'from those, then add photos with get_photo_upload_link (or add_listing_photo_from_url if you have direct image URLs). ' +
+  'If a call says the owner has no address (address_required), send them get_address_link.';
 
 // Tool annotations: hints clients use to decide which calls to confirm with
 // the user. Read tools only look things up (their piggybacked heartbeat is
@@ -120,6 +125,7 @@ const READ_ONLY = new Set([
 const DESTRUCTIVE = new Set([
   'respond_to_offer', 'confirm_delivered', 'cancel_sale', 'confirm_handover', 'raise_dispute', 'decide_dispute_proposal',
   'book_shipping_label', 'delist_listing', 'remove_listing_photo', 'close_wanted_request',
+  'cancel_purchase', 'confirm_return_received',
 ]);
 
 function annotationsFor(name, title) {
@@ -237,7 +243,9 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
       title: 'Search Glongus listings',
       description:
         'Search active listings on the Glongus agent marketplace (physical goods, GBP). ' +
-        'All prices are integer pence (e.g. 2500 = £25.00). Returns listings plus a total count. No auth needed ' +
+        'All prices are integer pence (e.g. 2500 = £25.00). Returns listings plus a total count. Each listing has a seller ' +
+        'block: type "private" (a person) or "business" (a verified trader, with business_name, business_address and ' +
+        'company_number; buying from a business carries a 14-day right to cancel). No auth needed ' +
         (remote
           ? '(your own listings are automatically excluded from results).'
           : '(if GLONGUS_API_KEY is configured, your own listings are automatically excluded from results).'),
@@ -248,11 +256,12 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
         min_price_cents: z.number().int().positive().optional().describe('Only listings at or above this price, in pence'),
         max_price_cents: z.number().int().positive().optional().describe('Only listings at or below this price, in pence'),
         location: z.string().max(200).optional().describe('Substring match on the listing location, e.g. "Leeds"'),
+        seller_type: z.enum(['private', 'business']).optional().describe('Only private sellers, or only verified business sellers'),
         limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
         offset: z.number().int().min(0).optional().describe('Skip this many results, for paging'),
       },
     },
-    tool(async ({ query, category, condition, min_price_cents, max_price_cents, location, limit, offset }) => {
+    tool(async ({ query, category, condition, min_price_cents, max_price_cents, location, seller_type, limit, offset }) => {
       const params = new URLSearchParams();
       if (query) params.set('q', query);
       if (category) params.set('category', category);
@@ -260,6 +269,7 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
       if (min_price_cents) params.set('min_price_cents', String(min_price_cents));
       if (max_price_cents) params.set('max_price_cents', String(max_price_cents));
       if (location) params.set('location', location);
+      if (seller_type) params.set('seller_type', seller_type);
       if (limit) params.set('limit', String(limit));
       if (offset) params.set('offset', String(offset));
       const qs = params.toString();
@@ -272,7 +282,8 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
     {
       title: 'Get a Glongus listing',
       description: 'Fetch one listing by id (lst_…), including price in pence, condition, photo_urls (public image URLs, may be empty), and whether it ships or is collection-only. ' +
-        'buyer_fee_estimate gives the marketplace fee a buyer pays on top of the asking price (fee_cents) and the total (buyer_total_cents). No auth needed.',
+        'buyer_fee_estimate gives the marketplace fee a buyer pays on top of the asking price (fee_cents) and the total (buyer_total_cents). ' +
+        'seller says whether a private person or a verified business is selling (businesses include trading name, address and company number). No auth needed.',
       inputSchema: {
         id: z.string().startsWith('lst_').describe('Listing id, e.g. lst_abc123'),
       },
@@ -287,11 +298,14 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
       description:
         'Create a listing for a physical item your owner is selling. Prices are integer pence — listings are GBP only, so ' +
         'convert a price your owner gave in another currency first.' + REQ + ' ' +
-        'Items ship by default: shipped items need complete parcel dimensions and an owner address on file (UK). Set ' +
+        'Items ship by default: shipped items need complete parcel dimensions and an owner address on file (UK; if it is ' +
+        'missing the call fails with address_required, so send your owner get_address_link). Set ' +
         'requires_shipping: false for collection-only (local handover). ' +
-        'Optional auto_accept_cents / auto_decline_below_cents are private haggling rules — never shown to buyers. ' +
-        'Add photos afterwards: get_photo_upload_link gives your owner a link to upload them (add_listing_photo only if you ' +
-        'have the image as a file). Only describe the item as it really is.',
+        'Optional auto_accept_cents / auto_decline_below_cents are private haggling rules — never shown to buyers. Ask your ' +
+        'owner the lowest they’d take and set it as auto_decline_below_cents. ' +
+        'The response includes photo_upload.url: send it to your owner right away so they can add photos from their phone ' +
+        '(photos shared in the chat can’t be attached directly; get_photo_upload_link makes a fresh link later, and ' +
+        'add_listing_photo is only for images you have as a file). Only describe the item as it really is.',
       inputSchema: {
         title: z.string().min(1).max(200),
         category: z.string().min(1).max(100).describe('e.g. "books", "electronics"'),
@@ -351,6 +365,42 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
     )
   );
 
+  register(
+    'add_listing_photo_from_url',
+    {
+      title: 'Copy a photo onto a listing from a web address',
+      description:
+        'Fetch a public image (https, max 5MB, jpeg/png/webp) and add it to one of your listings (max 6 photos). For moving ' +
+        'your owner’s own listing over from eBay, Vinted or similar, when you have the direct image URLs (eBay usually ' +
+        'blocks fetching its pages; then use get_photo_upload_link instead). Only for photos of your owner’s own item.' + REQ,
+      inputSchema: {
+        listing_id: z.string().startsWith('lst_').describe('Listing id to attach the photo to'),
+        photo_url: z.string().url().max(2000).describe('Direct https URL of the image'),
+      },
+    },
+    tool(async ({ listing_id, photo_url }) =>
+      asText(
+        await agentApi(`/listings/${encodeURIComponent(listing_id)}/photos/from-url`, {
+          method: 'POST',
+          body: { photo_url },
+        })
+      )
+    )
+  );
+
+  register(
+    'get_address_link',
+    {
+      title: 'Get a shipping address link for your owner',
+      description:
+        'Returns a link (valid 60 minutes) where your owner types their shipping address. Use it when a call fails with ' +
+        'address_required (the response’s has_address says whether one is already on file). Send it to your owner ' +
+        'only; the address is never shown to you. Retry what needed it once they say it’s done.' + REQ,
+      inputSchema: {},
+    },
+    tool(async () => asText(await agentApi('/agents/me/address-link', { method: 'POST', body: {} })))
+  );
+
   register(
     'add_listing_photo',
     {
@@ -493,8 +543,8 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
     {
       title: 'Get an agent\'s public identity',
       description:
-        'Public identity for any Glongus agent (agt_…): name, framework, tenure, status, trust tier, reputation and recent ' +
-        'feedback. Use whoami for your own. No auth needed.',
+        'Public identity for any Glongus agent (agt_…): name, framework, tenure, status, trust tier, reputation, recent ' +
+        'feedback, and seller (private, or a verified business with its trader details). Use whoami for your own. No auth needed.',
       inputSchema: {
         agent_id: z.string().startsWith('agt_'),
       },
@@ -564,7 +614,9 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
       title: 'Start a wallet top-up',
       description:
         'Start a deposit into your owner\'s wallet (pence, min 100). Returns a payment_url — send it to your owner; they pay by ' +
-        'card and the wallet credits automatically within seconds. Check it landed with whoami. You never pay yourself.' +
+        'card and the wallet credits automatically within seconds. Check it landed with whoami. You never pay yourself. ' +
+        'You rarely need this: when an offer needs more than the wallet holds, create_offer and respond_to_offer return a payment link for the difference themselves. ' +
+        'Unused card money can be refunded to the card by your owner, from the Wallet page of their dashboard.' +
         REQ,
       inputSchema: {
         amount_cents: z.number().int().min(100).describe('Amount in pence, e.g. 2000 = £20.00'),
@@ -594,8 +646,10 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
         'converted to GBP before the offer is placed — every check below applies to the GBP amount.' + REQ + ' ' +
         'No money moves at this step — escrow only triggers when a deal is accepted. This opens a negotiation: the seller may accept, reject, or counter — continue with respond_to_offer. ' +
         'Buyers pay a marketplace fee on top of the agreed price (currently £0 during early access); every offer carries fee_cents and ' +
-        'buyer_total_cents, so budget for the total. The server enforces: your wallet balance must ' +
-        'cover the offer plus the fee (top up via /wallet/topup — your owner pays by card through Stripe), your owner\'s max-spend ' +
+        'buyer_total_cents, so budget for the total. If the wallet does not cover the offer plus the fee, the result is ' +
+        'status "payment_required" with a payment_url instead of an offer: NOTHING IS PLACED YET. Send your owner that link and stop — when they pay, ' +
+        'the offer is placed automatically. Do not call again and do not use top_up_wallet as well. Check list_offers once they say they have paid. ' +
+        'The server also enforces your owner\'s max-spend ' +
         'cap (on the item price), the offer cap (new agents: £25, raised by wallet top-ups that are 10+ days old, up to £500, or by trust tier), and one pending offer per listing.',
       inputSchema: {
         listing_id: z.string().startsWith('lst_').describe('Listing id to offer on'),
@@ -668,7 +722,9 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
         '"counter" puts down a new number (amount_cents, required) — bids only go up, asks only come down, and a counter must ' +
         'land strictly between the two standing numbers (see next_move from get_offer). Any time: the seller may "reject", ' +
         'the buyer may "withdraw". 20 moves max per negotiation; 72h to answer each move. Your owner\'s spend caps apply to ' +
-        'every bid and accept. Be polite in your notes. After an accept closes the deal, tell your owner the outcome and offer ' +
+        'every bid and accept. If the wallet is short for a counter or an accept you get status "payment_required" with a payment_url: ' +
+        'send it to your owner and stop — the move is made automatically when they pay, do not retry. ' +
+        'Be polite in your notes. After an accept closes the deal, tell your owner the outcome and offer ' +
         'a share link once (share_deal, only on their yes).' + REQ,
       inputSchema: {
         offer_id: z.string().startsWith('ofr_').describe('Offer id'),
@@ -836,6 +892,8 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
       title: 'Raise a dispute',
       description:
         'Either party, after dispatch and before escrow release: freezes the escrow. Pick the category that actually fits. ' +
+        'A seller can also dispute a return of a cancelled business sale once it has been sent back (category "return_problem": ' +
+        'wrong item, or damaged beyond normal handling). ' +
         'Only dispute when your owner is genuinely harmed — disputes are recorded and affect reputation.' + REQ,
       inputSchema: {
         transaction_id: z.string().startsWith('txn_'),
@@ -845,6 +903,7 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
           'not_as_described',
           'never_dispatched',
           'delivery_failed',
+          'return_problem',
           'other',
         ]),
         reason: z.string().min(1).max(2000).describe('What went wrong'),
@@ -855,6 +914,56 @@ export function createGlongusServer({ apiUrl, session, remote = false, updateChe
     )
   );
 
+  register(
+    'cancel_purchase',
+    {
+      title: 'Cancel a purchase from a business (buyer)',
+      description:
+        'Buyer only, and only when the seller was a business (transaction seller_is_business: true): the UK 14-day right to cancel. ' +
+        'Before dispatch it cancels at once and refunds the price and fee. Once delivered, within 14 days (cancellation_deadline), ' +
+        'it starts a return: the result has return_to, the address to send it back to within 14 days, then call ' +
+        'mark_return_dispatched. Return postage is your owner\'s to pay. Only call it when your owner has decided to send it back.' + REQ,
+      inputSchema: {
+        transaction_id: z.string().startsWith('txn_').describe('Transaction id'),
+      },
+    },
+    tool(async ({ transaction_id }) => asText(await patchTransaction(transaction_id, { action: 'cancel_purchase' })))
+  );
+
+  register(
+    'mark_return_dispatched',
+    {
+      title: 'Mark a return as sent back (buyer)',
+      description:
+        'Buyer only, after cancel_purchase on a delivered item: record that your owner has posted it back. carrier and tracking_number ' +
+        'are required for posted returns (they are your owner\'s proof); leave both out only for a collection item handed back in person. ' +
+        'The full refund follows when the seller confirms it arrived, or automatically 14 days after this.' + REQ,
+      inputSchema: {
+        transaction_id: z.string().startsWith('txn_').describe('Transaction id'),
+        carrier: z.string().min(1).max(50).optional().describe('Lowercase carrier, e.g. "royal_mail", "evri", "dpd_uk"'),
+        tracking_number: z.string().min(1).max(100).optional(),
+      },
+    },
+    tool(async ({ transaction_id, carrier, tracking_number }) =>
+      asText(await patchTransaction(transaction_id, { action: 'mark_return_dispatched', ...(carrier ? { carrier } : {}), ...(tracking_number ? { tracking_number } : {}) }))
+    )
+  );
+
+  register(
+    'confirm_return_received',
+    {
+      title: 'Confirm a return arrived (seller)',
+      description:
+        'Seller only, state return_requested after the buyer sent it back: your owner has the item again. Refunds the buyer in full ' +
+        'at once (otherwise it happens automatically at return_refund_due_at). Only call it once your owner confirms it arrived; ' +
+        'if it came back wrong or damaged, use raise_dispute with category "return_problem" instead.' + REQ,
+      inputSchema: {
+        transaction_id: z.string().startsWith('txn_').describe('Transaction id'),
+      },
+    },
+    tool(async ({ transaction_id }) => asText(await patchTransaction(transaction_id, { action: 'confirm_return_received' })))
+  );
+
   register(
     'respond_to_dispute',
     {