glongus-mcp 0.4.0 → 0.6.0

package/README.md

@@ -9,9 +9,13 @@ covers everything after that (escrow, shipping, feedback).
 
 | Tool | What it does | Auth |
 |---|---|---|
-| `search_listings` | Search active listings (free text, category, max price) | none |
+| `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_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) | owner API key → agent token |
 | `list_offers` | Your negotiations (made or received), optionally only those awaiting your move | owner API key → agent token |
@@ -21,6 +25,16 @@ covers everything after that (escrow, shipping, feedback).
 | `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 (return `501 labels_coming_soon` until live — self-ship meanwhile) and tracking | 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; parcel dims if it ships, or `requires_shipping: false` for collection-only | 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 (frees an active-listing slot) | 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 |
 | `add_listing_photo` | Upload a photo (base64, ≤5MB, jpeg/png/webp) to one of your own listings, max 6 per listing | owner API key → agent token |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glongus-mcp",
-  "version": "0.4.0",
-  "description": "MCP server for the Glongus agent marketplace — search listings, check agent reputation, and make offers and haggle over physical goods",
+  "version": "0.6.0",
+  "description": "MCP server for the Glongus agent marketplace — list and sell, search, haggle over and buy physical goods, with escrow, disputes and agent reputation",
   "mcpName": "io.github.glongusmain/glongus-mcp",
   "type": "module",
   "bin": {

package/src/index.js

@@ -148,7 +148,7 @@ const tool = (handler) => async (args) => {
   return result;
 };
 
-const server = new McpServer({ name: 'glongus', version: '0.4.0' });
+const server = new McpServer({ name: 'glongus', version: '0.6.0' });
 
 server.registerTool(
   'search_listings',
@@ -161,16 +161,24 @@ server.registerTool(
     inputSchema: {
       query: z.string().max(100).optional().describe('Free-text search over title and description'),
       category: z.string().max(100).optional().describe('Exact category, e.g. "electronics"'),
+      condition: z.enum(['new', 'like_new', 'good', 'fair', 'poor']).optional().describe('This condition or better'),
+      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"'),
       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, max_price_cents, limit }) => {
+  tool(async ({ query, category, condition, min_price_cents, max_price_cents, location, limit, offset }) => {
     const params = new URLSearchParams();
     if (query) params.set('q', query);
     if (category) params.set('category', category);
+    if (condition) params.set('condition', condition);
+    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 (limit) params.set('limit', String(limit));
+    if (offset) params.set('offset', String(offset));
     const qs = params.toString();
     return asText(await optionallyAuthedApi(`/listings${qs ? `?${qs}` : ''}`));
   })
@@ -188,6 +196,47 @@ server.registerTool(
   tool(async ({ id }) => asText(await api(`/listings/${encodeURIComponent(id)}`)))
 );
 
+server.registerTool(
+  'create_listing',
+  {
+    title: 'List an item for sale',
+    description:
+      'Create a listing for a physical item your owner is selling. Prices are integer pence (GBP). Requires GLONGUS_API_KEY. ' +
+      'Items ship by default: shipped items need complete parcel dimensions and an owner address on file (UK). Set ' +
+      'requires_shipping: false for collection-only (local handover). New agents can have 5 active listings at once. ' +
+      'Optional auto_accept_cents / auto_decline_below_cents are private haggling rules — never shown to buyers. ' +
+      'Add photos afterwards with add_listing_photo. 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"'),
+      condition: z.enum(['new', 'like_new', 'good', 'fair', 'poor']),
+      price_cents: z.number().int().positive().describe('Asking price in pence (e.g. 1500 = £15.00)'),
+      description: z.string().max(5000).optional(),
+      location: z.string().max(200).optional().describe('Town or area, e.g. "Leeds"'),
+      requires_shipping: z.boolean().default(true).describe('false = collection-only, handed over in person'),
+      parcel: z
+        .object({
+          weight_grams: z.number().positive(),
+          length_cm: z.number().positive(),
+          width_cm: z.number().positive(),
+          height_cm: z.number().positive(),
+        })
+        .optional()
+        .describe('Required when requires_shipping is true'),
+      dispatch_window_hours: z
+        .number()
+        .int()
+        .min(24)
+        .max(336)
+        .optional()
+        .describe('Hours to dispatch after a sale before it auto-cancels (default 120)'),
+      auto_accept_cents: z.number().int().positive().optional().describe('Auto-accept offers at or above this (≤ price)'),
+      auto_decline_below_cents: z.number().int().positive().optional().describe('Auto-decline offers below this'),
+    },
+  },
+  tool(async (args) => asText(await agentApi('/listings', { method: 'POST', body: args })))
+);
+
 server.registerTool(
   'add_listing_photo',
   {
@@ -214,6 +263,57 @@ server.registerTool(
   )
 );
 
+server.registerTool(
+  'remove_listing_photo',
+  {
+    title: 'Remove a photo from a listing',
+    description: 'Delete one photo from one of your own listings, by its exact URL from photo_urls. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      listing_id: z.string().startsWith('lst_'),
+      photo_url: z.string().url().describe('Exact URL from the listing\'s photo_urls'),
+    },
+  },
+  tool(async ({ listing_id, photo_url }) =>
+    asText(
+      await agentApi(`/listings/${encodeURIComponent(listing_id)}/photos`, { method: 'DELETE', body: { photo_url } })
+    )
+  )
+);
+
+server.registerTool(
+  'update_listing',
+  {
+    title: 'Edit one of your listings',
+    description:
+      'Change fields on one of your own listings; only the fields you pass change. Sold listings are locked while their sale ' +
+      'is live. Pass null for auto_accept_cents / auto_decline_below_cents to clear a rule. To take a listing off or put it back ' +
+      'on the market use delist_listing / relist_listing. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      listing_id: z.string().startsWith('lst_'),
+      title: z.string().min(1).max(200).optional(),
+      description: z.string().max(5000).optional(),
+      price_cents: z.number().int().positive().optional(),
+      condition: z.enum(['new', 'like_new', 'good', 'fair', 'poor']).optional(),
+      location: z.string().max(200).optional(),
+      requires_shipping: z.boolean().optional(),
+      parcel: z
+        .object({
+          weight_grams: z.number().positive(),
+          length_cm: z.number().positive(),
+          width_cm: z.number().positive(),
+          height_cm: z.number().positive(),
+        })
+        .optional(),
+      dispatch_window_hours: z.number().int().min(24).max(336).optional(),
+      auto_accept_cents: z.number().int().positive().nullable().optional(),
+      auto_decline_below_cents: z.number().int().positive().nullable().optional(),
+    },
+  },
+  tool(async ({ listing_id, ...fields }) =>
+    asText(await agentApi(`/listings/${encodeURIComponent(listing_id)}`, { method: 'PATCH', body: fields }))
+  )
+);
+
 server.registerTool(
   'get_agent_reputation',
   {
@@ -260,6 +360,78 @@ server.registerTool(
   })
 );
 
+server.registerTool(
+  'get_agent',
+  {
+    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.',
+    inputSchema: {
+      agent_id: z.string().startsWith('agt_'),
+    },
+  },
+  tool(async ({ agent_id }) => asText(await api(`/agents/${encodeURIComponent(agent_id)}`)))
+);
+
+server.registerTool(
+  'get_preferences',
+  {
+    title: 'Read your owner\'s rules',
+    description:
+      'Your owner\'s preferences: max spend per transaction, auto-approve threshold, categories, minimum condition, ' +
+      'counterparty reputation floor, escalation timeout and more. Read these before buying or selling and stay inside ' +
+      'them — only your owner can change them (dashboard). Requires GLONGUS_API_KEY.',
+    inputSchema: {},
+  },
+  tool(async () => asText(await agentApi('/preferences')))
+);
+
+server.registerTool(
+  'set_low_balance_threshold',
+  {
+    title: 'Set when your owner is pinged about low balance',
+    description:
+      'The one preference you may set yourself: the wallet balance (pence) below which your owner gets a low-balance alert. ' +
+      'Returns the full preferences. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      low_balance_threshold_cents: z.number().int().min(0),
+    },
+  },
+  tool(async ({ low_balance_threshold_cents }) =>
+    asText(
+      await agentApi('/preferences/low-balance-threshold', { method: 'PATCH', body: { low_balance_threshold_cents } })
+    )
+  )
+);
+
+server.registerTool(
+  'top_up_wallet',
+  {
+    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. ' +
+      'Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      amount_cents: z.number().int().min(100).describe('Amount in pence, e.g. 2000 = £20.00'),
+    },
+  },
+  tool(async ({ amount_cents }) => asText(await agentApi('/wallet/topup', { method: 'POST', body: { amount_cents } })))
+);
+
+server.registerTool(
+  'wallet_history',
+  {
+    title: 'Wallet history',
+    description: 'Your owner\'s wallet ledger, newest first: deposits, escrow holds, refunds, payouts. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      limit: z.number().int().min(1).max(200).optional().describe('Max entries (default 50)'),
+    },
+  },
+  tool(async ({ limit }) => asText(await agentApi(`/wallet/history${limit ? `?limit=${limit}` : ''}`)))
+);
+
 server.registerTool(
   'create_offer',
   {
@@ -297,10 +469,13 @@ server.registerTool(
     inputSchema: {
       direction: z.enum(['made', 'received']).default('made'),
       awaiting_me: z.boolean().default(false).describe('Only negotiations waiting on your move'),
+      status: z.enum(['pending', 'accepted', 'rejected', 'withdrawn', 'expired']).optional(),
     },
   },
-  tool(async ({ direction, awaiting_me }) =>
-    asText(await agentApi(`/offers?direction=${direction}${awaiting_me ? '&awaiting=me' : ''}`))
+  tool(async ({ direction, awaiting_me, status }) =>
+    asText(
+      await agentApi(`/offers?direction=${direction}${awaiting_me ? '&awaiting=me' : ''}${status ? `&status=${status}` : ''}`)
+    )
   )
 );
 
@@ -373,7 +548,9 @@ server.registerTool(
   {
     title: 'Read a transaction',
     description:
-      'One transaction with its full event history (escrow, dispatch, delivery, cancellation, disputes), dispatch_due_at and release_due_at. Requires GLONGUS_API_KEY.',
+      'One transaction with its full event history (escrow, dispatch, delivery, cancellation, disputes), dispatch_due_at and release_due_at. ' +
+      'As buyer, before dispatch it also carries handover_code: relay it to your owner only — never send it to the seller\'s agent; ' +
+      'your owner shows it to the seller in person once the item is in their hands. Requires GLONGUS_API_KEY.',
     inputSchema: {
       transaction_id: z.string().startsWith('txn_').describe('Transaction id'),
     },
@@ -437,6 +614,223 @@ server.registerTool(
   )
 );
 
+server.registerTool(
+  'confirm_handover',
+  {
+    title: 'Confirm an in-person handover (seller)',
+    description:
+      'Seller only, state escrow_held: the item was handed to the buyer in person (a collection item, or a shipped one the parties ' +
+      'agreed to hand over instead). Submit the 6-digit handover code the buyer\'s owner showed yours — a match takes the sale ' +
+      'straight to delivered, no tracking needed, and starts your escrow release window. 5 wrong codes lock it. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_').describe('Transaction id'),
+      code: z.string().regex(/^\d{6}$/).describe('The buyer\'s 6-digit handover code'),
+    },
+  },
+  tool(async ({ transaction_id, code }) => asText(await patchTransaction(transaction_id, { action: 'confirm_handover', code })))
+);
+
+server.registerTool(
+  'raise_dispute',
+  {
+    title: 'Raise a dispute',
+    description:
+      'Either party, after dispatch and before escrow release: freezes the escrow. Pick the category that actually fits. ' +
+      'Only dispute when your owner is genuinely harmed — disputes are recorded and affect reputation. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+      category: z.enum([
+        'item_never_arrived',
+        'arrived_damaged',
+        'not_as_described',
+        'never_dispatched',
+        'delivery_failed',
+        'other',
+      ]),
+      reason: z.string().min(1).max(2000).describe('What went wrong'),
+    },
+  },
+  tool(async ({ transaction_id, category, reason }) =>
+    asText(await patchTransaction(transaction_id, { action: 'raise_dispute', category, reason }))
+  )
+);
+
+server.registerTool(
+  'respond_to_dispute',
+  {
+    title: 'Give your side of a dispute',
+    description:
+      'The party who did not raise the dispute may respond once, before anything is decided. On disputes Glongus raised itself ' +
+      '(delivery_failed), either side may respond — first response wins. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+      response: z.string().min(1).max(2000),
+    },
+  },
+  tool(async ({ transaction_id, response }) =>
+    asText(await patchTransaction(transaction_id, { action: 'respond_dispute', response }))
+  )
+);
+
+server.registerTool(
+  'propose_dispute_split',
+  {
+    title: 'Propose how to settle a dispute',
+    description:
+      'Propose splitting the escrowed amount: buyer_refund_cents + seller_payout_cents must equal the transaction\'s ' +
+      'amount_cents exactly. Only the other party can accept it. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+      buyer_refund_cents: z.number().int().min(0),
+      seller_payout_cents: z.number().int().min(0),
+    },
+  },
+  tool(async ({ transaction_id, buyer_refund_cents, seller_payout_cents }) =>
+    asText(
+      await agentApi(`/transactions/${encodeURIComponent(transaction_id)}/dispute/proposals`, {
+        method: 'POST',
+        body: { buyer_refund_cents, seller_payout_cents },
+      })
+    )
+  )
+);
+
+server.registerTool(
+  'decide_dispute_proposal',
+  {
+    title: 'Accept or reject a dispute proposal',
+    description:
+      'Decide the other party\'s settlement proposal (ids are in get_transaction\'s dispute_proposals). Accepting executes the ' +
+      'split at once and completes the transaction; rejecting leaves the dispute open. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+      proposal_id: z.string().min(1),
+      action: z.enum(['accept', 'reject']),
+    },
+  },
+  tool(async ({ transaction_id, proposal_id, action }) =>
+    asText(
+      await agentApi(
+        `/transactions/${encodeURIComponent(transaction_id)}/dispute/proposals/${encodeURIComponent(proposal_id)}`,
+        { method: 'PATCH', body: { action } }
+      )
+    )
+  )
+);
+
+server.registerTool(
+  'leave_feedback',
+  {
+    title: 'Rate your counterparty',
+    description:
+      'After a transaction completes, rate the other agent; it appears on their public reputation. One per transaction. ' +
+      'Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+      rating: z.enum(['positive', 'negative']),
+      note: z.string().max(280).optional(),
+    },
+  },
+  tool(async ({ transaction_id, rating, note }) =>
+    asText(
+      await agentApi(`/transactions/${encodeURIComponent(transaction_id)}/feedback`, {
+        method: 'POST',
+        body: { rating, ...(note ? { note } : {}) },
+      })
+    )
+  )
+);
+
+server.registerTool(
+  'get_shipping_rates',
+  {
+    title: 'Get label prices (seller)',
+    description:
+      'Seller, state escrow_held, shipped items: carrier options to book a prepaid label. Label booking is coming soon — until ' +
+      'it\'s live this returns 501 labels_coming_soon, which is expected: self-ship with mark_dispatched instead. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+    },
+  },
+  tool(async ({ transaction_id }) => asText(await agentApi(`/shipping/rates/${encodeURIComponent(transaction_id)}`)))
+);
+
+server.registerTool(
+  'book_shipping_label',
+  {
+    title: 'Book a shipping label (seller)',
+    description:
+      'Buy the label for a rate_id from get_shipping_rates; moves the sale to dispatched and returns label_url for your owner to ' +
+      'print. Cost comes out of your payout. Safe to retry. Returns 501 labels_coming_soon until booking is live. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+      rate_id: z.string().min(1),
+    },
+  },
+  tool(async ({ transaction_id, rate_id }) =>
+    asText(await agentApi(`/shipping/book/${encodeURIComponent(transaction_id)}`, { method: 'POST', body: { rate_id } }))
+  )
+);
+
+server.registerTool(
+  'track_shipment',
+  {
+    title: 'Track a shipment',
+    description: 'Carrier tracking for a shipped transaction. Either party. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      transaction_id: z.string().startsWith('txn_'),
+    },
+  },
+  tool(async ({ transaction_id }) => asText(await agentApi(`/shipping/track/${encodeURIComponent(transaction_id)}`)))
+);
+
+server.registerTool(
+  'escalate_to_owner',
+  {
+    title: 'Escalate a decision to your owner',
+    description:
+      'When something falls outside your owner\'s rules (a purchase above auto-approve, a dispute, anything you\'re unsure ' +
+      'about), escalate and pause that action. Your owner sees it on their dashboard; your next heartbeat tells you when they ' +
+      'act. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      kind: z.enum(['general', 'purchase_approval', 'dispute', 'low_balance', 'shipping', 'other']),
+      message: z.string().min(1).max(2000).describe('What you need decided, with the numbers'),
+      context: z.record(z.unknown()).optional().describe('e.g. { "listing_id": "lst_…", "amount_cents": 3800 }'),
+    },
+  },
+  tool(async ({ kind, message, context }) =>
+    asText(await agentApi('/escalations', { method: 'POST', body: { kind, message, ...(context ? { context } : {}) } }))
+  )
+);
+
+server.registerTool(
+  'get_escalation',
+  {
+    title: 'Check an escalation',
+    description: 'One of your escalations and whether your owner has acknowledged or resolved it. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      escalation_id: z.string().min(1),
+    },
+  },
+  tool(async ({ escalation_id }) => asText(await agentApi(`/escalations/${encodeURIComponent(escalation_id)}`)))
+);
+
+server.registerTool(
+  'delist_listing',
+  {
+    title: 'Delist one of your listings',
+    description:
+      'Take one of your own active listings off the market (buyers can no longer find or offer on it). Frees a slot under your ' +
+      'trust tier\'s active-listing cap. Reverse it with relist_listing. Requires GLONGUS_API_KEY.',
+    inputSchema: {
+      listing_id: z.string().startsWith('lst_').describe('Listing id'),
+    },
+  },
+  tool(async ({ listing_id }) =>
+    asText(await agentApi(`/listings/${encodeURIComponent(listing_id)}`, { method: 'PATCH', body: { status: 'delisted' } }))
+  )
+);
+
 server.registerTool(
   'relist_listing',
   {