io.github.Tomalarrrr/cyclesite-mcp-server

Check whether a UK bike's frame (serial) number matches a theft report held by Cyclesite. Live data, checked on every call. Rate-limited per serial number (3 an hour) to prevent enumeration. Example: 'does frame number WTU123456 match a theft report?'. Someone who has found a bike, rather than bought one, can check the frame number and leave the owner a message at https://www.cyclesite.co.uk/stolen-bikes/found.

Side-by-side comparison of up to 3 bikes (each by brand+model[+year]). Returns spec sheets and valuations together, from the same measured UK data as the single-bike spec sheets and valuations. Example: 'compare a Trek Domane SL 6 against a Specialized Roubaix Comp'.

Sell-side helper: turn a seller's raw facts into a polished Cyclesite listing draft (title, description, suggested price, photo plan). Does not publish anything: publishing needs a signed-in account (OAuth). Useful for previewing what a listing would look like. Example: 'help me draft a listing for my 2021 Specialized Allez, very good condition, in Bristol'.

OpenAI deep-research / company-knowledge compatibility. Fetch the full document for one Cyclesite listing id. Returns { id, title, text, url, metadata }, where text is a plain-prose summary of the listing's description and specs, suitable for direct quoting in deep-research answers.

Given a Cyclesite listing slug, return up to 5 similar active listings (same category, ±25% price, same brand or frame size weighted higher), as alternatives to one bike. Example: 'show me bikes like that one'.

Search Cyclesite's expert buying guides (24+ articles by cycling-journalism authors). Returns up to 3 matching guides with title, excerpt, difficulty, reading time, and URL. Covers educational questions that don't need live inventory. Example: 'how do I choose a bike size?', 'tips for buying a used e-bike'.

Brands ranked by how well (or poorly) they hold their value, from Cyclesite's measured UK used-price data. Returns top N brands by % retained vs new RRP. Example: 'which bike brands hold their value best?'.

Full details for a specific bike listing on Cyclesite: specs, condition, frame number presence, photos, delivery, seller's city. Takes the URL slug from a listing result. Example: 'tell me more about that 2022 Trek Domane'. The marketplace is not the seller: contact goes through the route in `howToContactSeller`, delivery terms are only what `delivery.summary` states, and no seller has agreed a price or delivery through this tool.

Buyer's-vs-seller's market signal for the UK used-bike market — should the user buy or sell now? Composite indicator from days-to-sell, asking-vs-sold-price spread, and inventory levels. Example: 'is now a good time to buy a road bike?'. Refreshed nightly.

Current UK used-bike market prices by category, from Cyclesite's nightly index. Returns median + range per category (road, mtb, gravel, e-bike, etc.). Example: 'how does the UK used-bike market look right now?'. Refreshed nightly from real UK market prices.

Cyclesite catalogue entry for a brand+model: category, year range, model description, key specs, market summary. Reference data — refreshed when models are added or specs change. Example: 'tell me about the Specialized Allez'.

Show the messages buyers have sent about the authenticated user's Cyclesite listings, newest first. Each enquiry is one buyer's conversation: its id, the listing, the buyer's latest message, the unread count and whether the seller has replied. The seller can answer an enquiry by its id. Requires OAuth scope `listings:read`. Example: 'any messages about my Trek?'.

Read the buyer's own Cyclesite message threads and any seller replies. With no arguments it lists the buyer's conversations; with a threadId it returns that thread's messages. Enquiries the buyer has sent to sellers appear here. Requires OAuth scope `listings:read`. Example: 'did the seller of that Trek reply yet?'.

UK used-bike price trends over the last N months by category, from Cyclesite's index series. Example: 'how have road-bike prices changed in 2026?'. Monthly data, refreshed at month-end.

What's new on Cyclesite right now: up to 10 of the freshest active UK listings, refreshed every 15 minutes. Suited to questions like 'what's new today?' or 'any new road bikes this week?' rather than a specific filter. Optional category + maxPrice filters. Live data.

Frame-size recommendation for a rider's height and bike category, the same chart Cyclesite publishes at /bike-size-calculator (height to inside leg to seat tube), refined by real UK listing data where riders' declared heights are available. Children are sized by wheel diameter instead and the tool says so. Example: 'I'm 178cm — what road-bike size do I need?'.

Aggregated spec sheet for a brand+model[+year], derived from Cyclesite's live UK inventory plus the catalogue record. Returns the most-common frame material, wheel size, groupset, brakes, weight, and (for e-bikes) motor and battery specs. Example: 'what groupset does a Canyon Endurace usually have?'.

What a used UK bike is worth right now, Cyclesite's flagship tool. Returns median, range, a measured price-by-model-year curve, confidence level, and comparable active listings. When `year` is given, the answer is resolved against that model year's own measured median and confidence interval, instead of the all-years median. Sourced from real UK sold prices, refreshed nightly. Example: 'what's a 2022 Trek Domane SL 6 worth?'.

Categorical quality grade for a Cyclesite listing (excellent / good / fair / weak) plus up to 2 wins and 2 flags. Helps a buyer assess trustworthiness; helps a seller self-audit. Example: 'is this listing trustworthy?' (provide the slug). Note: returns the *categorical* judgement only, not the underlying score (intentional to avoid gaming).

Paginated UK bike-brand catalogue from Cyclesite, ordered by stock level, for checking a brand name, listing the options or paging through the catalogue. Stock counts are returned as bands (none / 1-5 / 6-25 / 26-100 / 100+); Cyclesite doesn't expose precise per-brand inventory. Example: 'what brands of e-bike are available?'.

Models for a brand on Cyclesite (paginated). Returns model names, year ranges, in-stock flag. Example: "what Trek road bikes are available?" (brandSlug "trek", category "road").

Show the authenticated user's Cyclesite listings (draft / active / sold). Requires OAuth scope `listings:read`. Example: 'how are my listings doing?'.

Send an enquiry to a Cyclesite seller on the buyer's behalf. It's saved to the buyer's Cyclesite inbox, where the seller's reply also arrives, and the seller is notified. Per-buyer-per-listing daily cap (2/day) prevents spam. Requires OAuth scope `enquiries:respond` (the scope name is shared with seller-side replies). Example: 'message the seller of that Trek and ask whether it has had a service this year and if Saturday collection in Manchester works'.

Mark a Cyclesite listing as sold, optionally with the final sale price, where it sold and the date it sold. Requires OAuth scope `listings:manage`. Example: 'mark my Trek Domane as sold for £1,750 on Facebook last Saturday'.

Publish a Cyclesite listing on the user's behalf. Multi-step: the first call (no draftId) returns step:'photos_required' with a phone-friendly photo upload URL for the seller. Once 3+ photos are uploaded, a call with the same draftId returns either step:'live' (listing is free, no payment needed) or step:'payment_required' with a checkout URL. Idempotent: each call with the same draftId returns the current step. Requires OAuth scope `listings:publish`. When the listing goes live the seller receives a confirmation email with a 24h undo link. Example: 'sell my Trek Domane'.

Curated picks from Cyclesite's live UK inventory for a budget and intent. Prefers higher-engagement listings. Returns up to 5 picks with a one-line rationale each. Example queries: 'a road bike for £1,500 for weekend rides', 'best e-MTB I can buy under £3,000', 'commuter bike in London under £400'.

Step-by-step guidance for reporting a stolen UK bike: police, insurance, listing alerts. Returns a 5-step checklist plus the official Cyclesite report URL. Example: 'my bike was just stolen, what do I do?'.

Hold a Cyclesite listing for 24 hours so other buyers can't claim it while the user decides. The hold is free and advisory: the seller isn't obligated to honour it. We never take a deposit or any payment for a bike; the buyer and seller arrange payment between them. Requires OAuth scope `listings:manage`. Example: 'put a hold on that Trek for me, I want to view it Saturday'.

Send the seller's reply to a buyer who messaged about one of the authenticated user's listings. Takes the id of one of the seller's enquiries. The buyer is notified, and the message tells them an AI assistant sent it on the seller's behalf. Requires OAuth scope `enquiries:respond`. Example: 'reply to my latest enquiry saying it's still available, collection only'.

Subscribe the user to email alerts for Cyclesite listings matching a filter. We email them when a matching bike is listed or drops in price, instantly or in a daily digest, depending on their email preferences. Requires OAuth scope `listings:read` (read-only on data, but this is technically a write: it creates a SavedSearch row on the user's account). Examples: 'let me know when a Trek Domane SL 6 in Manchester under £2,000 appears', 'alert me to any e-MTB drops below £2,500 in Yorkshire'. Each user is capped at 50 active alerts.

OpenAI deep-research / company-knowledge compatibility. Search Cyclesite's active UK used-bike listings by free-text query (matches title, brand, model). Returns the canonical OpenAI shape: { results: [{ id, title, url }] }. Each result id is a listing id.

Search live UK used-bike listings on Cyclesite (the UK's used bicycle marketplace). Filter by brand, category, city, price range, and condition. Returns up to 5 active listings with specs and listing URLs. Live data — refreshed continuously as new bikes are listed. Example queries: 'a Trek Domane in Manchester under £2,000', 'gravel bike, very good condition, near Bristol'.

Find Cyclesite listings within a radius of a UK town, city or postcode district (the first half of a postcode, e.g. 'BS1', 'M20'). A full postcode is cut to its district; coordinates are not accepted. Radius capped at 50 miles. Returns up to 10 listings ordered by distance, rounded to the mile, and `searchedFrom` naming the place measured from. Live UK marketplace data. Example: 'used bikes within 25 miles of Leicester' or 'road bikes near LE10'.

For a seller about to list: suggested ask, floor, and ceiling for their bike's brand+model[+year][+condition] on the UK market. Same measured UK used-price data as the valuations, framed as seller guidance. When `year` is given, the ask is anchored on that model year's own median rather than the all-years median. Example: 'I'm selling a 2021 Specialized Allez in good condition, what should I ask?'.