@scavio/mcp-server 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/dist/tools/amazon.js +57 -56
- package/dist/tools/amazon.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
|
|
5
5
|
|
|
6
|
-
[Scavio](https://scavio.dev) is a unified [Web Search API](https://scavio.dev/docs/search-api) and MCP server that connects AI agents to Google, YouTube, Amazon, Walmart, TikTok, Instagram, Reddit, X, LinkedIn, and TikTok Shop.
|
|
6
|
+
[Scavio](https://scavio.dev) is a unified [Web Search API](https://scavio.dev/docs/search-api) and MCP server that connects AI agents to Google, YouTube, Amazon, Walmart, TikTok, Instagram, Reddit, X, LinkedIn, and TikTok Shop. 99 tools for web search, product lookup, video discovery, and social media data through a single [Search API](https://scavio.dev/docs/search-api) endpoint.
|
|
7
7
|
|
|
8
8
|
## Remote MCP Server
|
|
9
9
|
|
|
@@ -236,8 +236,9 @@ Add to settings (`Cmd+,`):
|
|
|
236
236
|
|
|
237
237
|
| Tool | Description |
|
|
238
238
|
|------|-------------|
|
|
239
|
-
| `search_amazon` | Search product listings
|
|
239
|
+
| `search_amazon` | Search product listings across 22 marketplaces (no sort option) |
|
|
240
240
|
| `get_amazon_product` | Get full product details by ASIN |
|
|
241
|
+
| `get_amazon_offers` | List every seller offering an ASIN, with buy-box winner |
|
|
241
242
|
|
|
242
243
|
### [Walmart API](https://scavio.dev/docs/walmart-api)
|
|
243
244
|
|
package/dist/tools/amazon.js
CHANGED
|
@@ -1,6 +1,37 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
2
|
import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
|
|
3
3
|
import { ApiError } from "../lib/errors.js";
|
|
4
|
+
// Amazon moved to a new upstream provider and now returns a normalized shape
|
|
5
|
+
// instead of the old raw passthrough. Two consequences for these tool schemas:
|
|
6
|
+
//
|
|
7
|
+
// 1. Eleven params were removed because the current upstream has no equivalent:
|
|
8
|
+
// sort_by, pages, category_id, merchant_id, language, currency, device,
|
|
9
|
+
// zip_code, autoselect_variant, and the domain/start_page aliases. sort_by is
|
|
10
|
+
// the one worth calling out - the marketplace accepts every sort value and
|
|
11
|
+
// returns the identical unordered result set, so it was a filter that did
|
|
12
|
+
// nothing. Leaving it in a tool schema would be worse than removing it: a
|
|
13
|
+
// model reads the schema as a promise and would plan "get the cheapest" as a
|
|
14
|
+
// single call. The API still accepts `domain` and `start_page` as deprecated
|
|
15
|
+
// aliases; they are absent here because there is no reason to offer a model
|
|
16
|
+
// two spellings of one param.
|
|
17
|
+
//
|
|
18
|
+
// 2. Locale is now a single `country` param carrying a TWO-LETTER country code
|
|
19
|
+
// (us, gb, de), not an Amazon domain suffix (com, co.uk) and not a ZIP.
|
|
20
|
+
//
|
|
21
|
+
// All three tools cost 1 credit.
|
|
22
|
+
// Kept in one place so search, product and offers cannot drift. `gb` is spelled
|
|
23
|
+
// out because `uk` is the mistake a model makes here, and an unknown code
|
|
24
|
+
// silently falls back to `us` rather than erroring, which would be invisible.
|
|
25
|
+
const COUNTRY_DESCRIPTION = "Marketplace country code, ISO 3166-1 alpha-2, lowercase. Defaults to us. Valid: us, ae, au, be, br, ca, cn, de, eg, es, fr, gb, in, it, jp, mx, nl, pl, sa, se, sg, tr. Note the UK is 'gb'. An unrecognised code falls back to us instead of failing, so a typo silently returns US results.";
|
|
26
|
+
const countryField = z
|
|
27
|
+
.string()
|
|
28
|
+
.regex(/^[A-Za-z]{2}$/)
|
|
29
|
+
.optional()
|
|
30
|
+
.describe(COUNTRY_DESCRIPTION);
|
|
31
|
+
const asinField = z
|
|
32
|
+
.string()
|
|
33
|
+
.length(10)
|
|
34
|
+
.describe("Amazon ASIN - the 10-character product id, e.g. 'B09V3KXJPB'. Extract it from the product URL (/dp/ASIN).");
|
|
4
35
|
function handleApiError(err) {
|
|
5
36
|
if (err instanceof ApiError) {
|
|
6
37
|
if (err.status === 429)
|
|
@@ -12,67 +43,37 @@ function handleApiError(err) {
|
|
|
12
43
|
throw new McpError(ErrorCode.InternalError, String(err));
|
|
13
44
|
}
|
|
14
45
|
export function registerAmazonTools(server, getClient) {
|
|
15
|
-
|
|
16
|
-
query: z.string().min(1).max(500)
|
|
17
|
-
.describe("Product search query, e.g. 'wireless noise cancelling headphones'."),
|
|
18
|
-
domain: z.string().default("com")
|
|
19
|
-
.describe("Amazon domain suffix, e.g. 'com' (US), 'co.uk' (UK), 'de' (Germany), 'co.jp' (Japan)."),
|
|
20
|
-
country: z.string().optional()
|
|
21
|
-
.describe("Country code for localization."),
|
|
22
|
-
language: z.string().optional()
|
|
23
|
-
.describe("Language code."),
|
|
24
|
-
currency: z.string().optional()
|
|
25
|
-
.describe("Currency code (ISO 4217, e.g. 'USD')."),
|
|
26
|
-
device: z.enum(["desktop", "mobile", "tablet"]).optional()
|
|
27
|
-
.describe("Device to emulate."),
|
|
28
|
-
sort_by: z.enum(["most_recent", "price_low_to_high", "price_high_to_low", "featured", "average_review", "bestsellers"]).default("featured")
|
|
29
|
-
.describe("Sort order for results."),
|
|
30
|
-
start_page: z.number().int().min(1).default(1)
|
|
31
|
-
.describe("Starting page number."),
|
|
32
|
-
pages: z.number().int().optional()
|
|
33
|
-
.describe("Number of pages to fetch."),
|
|
34
|
-
category_id: z.string().optional()
|
|
35
|
-
.describe("Amazon category id."),
|
|
36
|
-
merchant_id: z.string().optional()
|
|
37
|
-
.describe("Filter to a specific merchant."),
|
|
38
|
-
zip_code: z.string().optional()
|
|
39
|
-
.describe("ZIP/postal code for localized pricing."),
|
|
40
|
-
autoselect_variant: z.boolean().optional()
|
|
41
|
-
.describe("Auto-select the default variant."),
|
|
42
|
-
}, async (params) => {
|
|
43
|
-
try {
|
|
44
|
-
const data = await getClient().post("/api/v1/amazon/search", params);
|
|
45
|
-
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
46
|
-
}
|
|
47
|
-
catch (err) {
|
|
48
|
-
return handleApiError(err);
|
|
49
|
-
}
|
|
50
|
-
});
|
|
51
|
-
server.tool("get_amazon_product", `Get detailed information for an Amazon product by its ASIN. Returns title, full description, price, rating, review count, images, variants, and seller info. Use when the user has a specific Amazon product URL or ASIN and wants full details.`, {
|
|
52
|
-
query: z.string().length(10)
|
|
53
|
-
.describe("Amazon ASIN — the 10-character product ID, e.g. 'B09V3KXJPB'. Extract from the Amazon URL (/dp/ASIN)."),
|
|
54
|
-
domain: z.string().default("com")
|
|
55
|
-
.describe("Amazon domain suffix, e.g. 'com', 'co.uk', 'de'."),
|
|
56
|
-
country: z.string().optional()
|
|
57
|
-
.describe("Country code for localization."),
|
|
58
|
-
language: z.string().optional()
|
|
59
|
-
.describe("Language code."),
|
|
60
|
-
currency: z.string().optional()
|
|
61
|
-
.describe("Currency code (ISO 4217, e.g. 'USD')."),
|
|
62
|
-
device: z.enum(["desktop", "mobile", "tablet"]).optional()
|
|
63
|
-
.describe("Device to emulate."),
|
|
64
|
-
zip_code: z.string().optional()
|
|
65
|
-
.describe("ZIP/postal code for localized pricing."),
|
|
66
|
-
autoselect_variant: z.boolean().optional()
|
|
67
|
-
.describe("Auto-select the default variant."),
|
|
68
|
-
}, async (params) => {
|
|
46
|
+
const call = (path) => async (params) => {
|
|
69
47
|
try {
|
|
70
|
-
const data = await getClient().post(
|
|
48
|
+
const data = await getClient().post(path, params);
|
|
71
49
|
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
72
50
|
}
|
|
73
51
|
catch (err) {
|
|
74
52
|
return handleApiError(err);
|
|
75
53
|
}
|
|
76
|
-
}
|
|
54
|
+
};
|
|
55
|
+
server.tool("search_amazon", `Search an Amazon marketplace and return the product grid as JSON: query, page, total_results, count, products, filters and related_searches. Each product has asin, title, url, image, price (number) with currency, rating, reviews_count, is_sponsored, position, badge, sales_volume and delivery { is_free, date, fastest_date }. Use it to find products, compare prices or collect ASINs to pass to get_amazon_product and get_amazon_offers.
|
|
56
|
+
|
|
57
|
+
There is NO sort option. The marketplace ignores every sort value and always returns its default relevance ranking, so results are unordered with respect to price, rating and date. To answer "the cheapest" or "the best rated", fetch the results and sort them yourself; do not expect the API to do it. There is also no category, merchant or price-range filter - filters[] carries the marketplace's own refinement URLs for reference only, and cannot be sent back as a param.
|
|
58
|
+
|
|
59
|
+
Two fields to read carefully: reviews_count is derived from Amazon's rounded display value, so anything above 1000 is approximate (a page showing "1.3K" returns 1300); position is Amazon's grid slot index including ad and carousel slots, so it starts above 1 and has gaps. Costs 1 credit per page.`, {
|
|
60
|
+
query: z.string().min(1).max(500)
|
|
61
|
+
.describe("Product search query, e.g. 'wireless noise cancelling headphones'."),
|
|
62
|
+
country: countryField,
|
|
63
|
+
page: z.number().int().min(1).optional()
|
|
64
|
+
.describe("Results page, 1-based. One page per call, 1 credit each; there is no multi-page fetch."),
|
|
65
|
+
}, call("/api/v1/amazon/search"));
|
|
66
|
+
server.tool("get_amazon_product", `Get the full product page for an Amazon ASIN as JSON: title, brand, url, description, features, price, list_price, currency, rating, reviews_count, is_prime, has_buy_box, availability (free text such as "In Stock"), max_quantity, sold_by, other_sellers_count, sales_volume, climate_pledge_friendly, image, images, videos, best_sellers_rank, categories, specifications, variants and shipping { is_prime, zipcode, options }. Use it when you have a specific ASIN or Amazon product URL and need details, pricing or specs.
|
|
67
|
+
|
|
68
|
+
Caveats worth knowing: price is the current buy-box price and other_sellers_count only counts the rest - call get_amazon_offers for the actual competing sellers and their prices. reviews[] carries review metadata only (id, author, date, verified_purchase); there is no review text and no per-review rating anywhere in the response. availability is marketplace- and language-specific free text, so match on the ASIN's own wording rather than parsing it for stock status. Costs 1 credit.`, {
|
|
69
|
+
asin: asinField,
|
|
70
|
+
country: countryField,
|
|
71
|
+
}, call("/api/v1/amazon/product"));
|
|
72
|
+
server.tool("get_amazon_offers", `List every seller currently offering an Amazon ASIN, as JSON: asin, title, image, rating, reviews_count, note, count, total_offers, has_more_pages, page and offers. Each offer has condition (New, Used - Like New, ...), seller_id, seller_name, ships_from, is_fulfilled_by_amazon, is_buy_box_winner, is_prime, is_national_prime, price with currency, list_price, shipping_price, discount_percentage, discount_amount, quantity, delivery { min_hours, max_hours, date, is_free } and prime_delivery { date, order_deadline }. Use it to find the cheapest seller for a known ASIN, to check who holds the buy box, to compare new against used pricing, or to see whether a third-party seller undercuts Amazon.
|
|
73
|
+
|
|
74
|
+
This returns the first page of the offer list only - has_more_pages may be true, and there is no way to request the next page. An ASIN sold only by Amazon returns an empty offers list plus an explanatory note, which is a normal answer, not an error. Costs 1 credit.`, {
|
|
75
|
+
asin: asinField,
|
|
76
|
+
country: countryField,
|
|
77
|
+
}, call("/api/v1/amazon/offers"));
|
|
77
78
|
}
|
|
78
79
|
//# sourceMappingURL=amazon.js.map
|
package/dist/tools/amazon.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"amazon.js","sourceRoot":"","sources":["../../src/tools/amazon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,
|
|
1
|
+
{"version":3,"file":"amazon.js","sourceRoot":"","sources":["../../src/tools/amazon.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@scavio/mcp-server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"mcpName": "io.github.scavio-ai/scavio-mcp",
|
|
5
|
-
"description": "MCP server connecting AI agents to Google, YouTube, Amazon, Walmart, TikTok, Instagram, Reddit, X, LinkedIn, and TikTok Shop.
|
|
5
|
+
"description": "MCP server connecting AI agents to Google, YouTube, Amazon, Walmart, TikTok, Instagram, Reddit, X, LinkedIn, and TikTok Shop. 99 tools for web search, product lookup, video discovery, and social media analysis.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"license": "MIT",
|
|
8
8
|
"author": "Scavio",
|