apiguru-mcp 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apiguru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# apiguru-mcp (npm)
+
+Live Amazon marketplace data for AI agents as MCP tools: product details,
+reviews, keyword search, best-sellers, deals, live offers and stock, and seller
+profiles across 20 country marketplaces. Eleven read-only tools with prices and
+retry rules in their descriptions.
+
+```bash
+npx -y apiguru-mcp
+```
+
+That is the whole install. Node 18+ is the only requirement: no Python, no
+`uv`, no account, no API key.
+
+<!-- mcp-name: app.apiguru/amazon-data -->
+
+## What it runs
+
+`npx apiguru-mcp` is a stdio bridge to the hosted server at
+`https://mcp.apiguru.app/mcp`: your MCP client talks stdio to the bridge, the
+bridge talks streamable HTTP to the server, and every JSON-RPC message passes
+through untouched. You get exactly the tools `uvx apiguru-mcp` (the Python
+package) serves locally, because that package is itself a thin HTTP client over
+the same gateway.
+
+Free probes are counted per caller, since the connection to the gateway comes
+from your machine rather than from a shared vendor address.
+
+Prefer to run the server itself? `npx apiguru-mcp --local` runs the Python
+package through `uvx` (needs [uv](https://docs.astral.sh/uv/)).
+
+## Client setup
+
+**Claude Code**
+
+```bash
+claude mcp add apiguru -- npx -y apiguru-mcp
+# or remote, nothing to run locally:
+claude mcp add --transport http apiguru https://mcp.apiguru.app/mcp
+```
+
+**Codex CLI**
+
+```bash
+codex mcp add apiguru -- npx -y apiguru-mcp
+```
+
+**Cursor, Windsurf, Claude Desktop, Hermes, OpenClaw, any stdio client**
+
+```json
+{
+  "mcpServers": {
+    "apiguru": {
+      "command": "npx",
+      "args": ["-y", "apiguru-mcp"],
+      "env": { "APIGURU_API_KEY": "optional-key-here" }
+    }
+  }
+}
+```
+
+Drop the `env` block to run keyless.
+
+**VS Code** (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "apiguru": { "type": "stdio", "command": "npx", "args": ["-y", "apiguru-mcp"] }
+  }
+}
+```
+
+**claude.ai, Claude Desktop connectors, ChatGPT**: no bridge needed. Add
+`https://mcp.apiguru.app/account` as a connector and sign in; calls bill your
+Apiguru account.
+
+## Paying for calls
+
+Without a key you get 3 free calls per 24 hours per machine. After that a tool
+call returns a structured error carrying an HTTP 402 payment challenge (x402,
+USDC on Base mainnet). Either:
+
+- set `APIGURU_API_KEY` from https://dash.apiguru.app so calls bill your
+  account at your plan's rates, or
+- have an x402-capable HTTP client pay the challenge against the REST gateway
+  at `https://agent.apiguru.app/agent/v1/...` directly. The full guide is in
+  `https://agent.apiguru.app/llms.txt`.
+
+## Options
+
+| Flag / variable | Meaning |
+|---|---|
+| `--url <url>` / `APIGURU_MCP_URL` | Bridge to another streamable-HTTP MCP server (default `https://mcp.apiguru.app/mcp`) |
+| `--local [args...]` | Run the Python server via `uvx apiguru-mcp` instead; remaining arguments are passed through |
+| `APIGURU_API_KEY` | Sent as `X-API-KEY`; bills that Apiguru account instead of using the keyless path |
+| `APIGURU_MCP_DEBUG` | Log transport noise to stderr |
+| `--version`, `--help` | |
+
+## Tools
+
+| Tool | Does | Price |
+|---|---|---|
+| `list_capabilities` | Endpoints, prices, marketplaces, your access mode | **free**, offline |
+| `product_details` | Full record for one ASIN | $0.01 |
+| `product_details_batch` | Up to 20 ASINs at once | $0.008/item |
+| `product_reviews` | Reviews, rating, "customers say" | $0.01 |
+| `search` | Keyword search with filters and sorting | $0.01 |
+| `offers_stock` | Offers, buy box, live stock (≤10 ASINs) | $0.015/item |
+| `best_sellers` | Category rankings | $0.01 |
+| `deals` | Current discounts with filters | $0.01 |
+| `seller_profile_batch` | Seller profiles (≤10 IDs) | $0.012/item |
+| `seller_products` | A seller's catalogue | $0.01 |
+| `seller_reviews` | Seller feedback | $0.01 |
+
+Every tool is annotated `readOnlyHint: true`; nothing here writes anywhere.
+
+## Links
+
+- Source, skill and plugin: https://github.com/apiguru-app/agent-kit
+- Python package: https://pypi.org/project/apiguru-mcp/
+- API docs: https://dash.apiguru.app/docs
+- Support: support@apiguru.app

package/bin/apiguru-mcp.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * apiguru-mcp: the Apiguru Amazon Data MCP server from npx, with nothing but
+ * Node installed.
+ *
+ *   npx apiguru-mcp                  # stdio <-> https://mcp.apiguru.app/mcp
+ *   npx apiguru-mcp --url <mcp url>  # bridge to another streamable-HTTP server
+ *   npx apiguru-mcp --local          # run the Python server via uvx (needs uv)
+ *
+ * The default mode is a transparent stdio-to-streamable-HTTP bridge. Every
+ * JSON-RPC message from the local client is POSTed to the hosted server and
+ * every reply is written back, so the client sees exactly the 11 tools that
+ * `uvx apiguru-mcp` would serve locally. The Python package is a thin HTTP
+ * client over the same gateway anyway, so nothing is lost by running it on
+ * our side instead of yours.
+ *
+ * Free probes are counted per caller, because the connection to the gateway
+ * originates from THIS machine, not from a shared vendor address.
+ *
+ * Environment:
+ *   APIGURU_API_KEY   optional; sent as X-API-KEY so calls bill that account
+ *                     instead of using the free-probe-then-402 path
+ *   APIGURU_MCP_URL   optional; same as --url
+ *   APIGURU_MCP_DEBUG set to anything to log transport noise to stderr
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+const DEFAULT_URL = "https://mcp.apiguru.app/mcp";
+const ACCOUNT_URL = "https://mcp.apiguru.app/account";
+
+const argv = process.argv.slice(2);
+const has = (flag) => argv.includes(flag);
+const valueOf = (flag) => {
+  const i = argv.indexOf(flag);
+  if (i === -1) return undefined;
+  const v = argv[i + 1];
+  if (v === undefined || v.startsWith("--")) fail(`${flag} needs a value`);
+  return v;
+};
+
+function fail(message, code = 2) {
+  process.stderr.write(`apiguru-mcp: ${message}\n`);
+  process.exit(code);
+}
+
+if (has("--help") || has("-h")) {
+  process.stdout.write(
+    [
+      `apiguru-mcp ${version}`,
+      "",
+      "Usage:",
+      `  apiguru-mcp                 bridge stdio to ${DEFAULT_URL}`,
+      "  apiguru-mcp --url <url>     bridge stdio to another MCP streamable-HTTP URL",
+      "  apiguru-mcp --local [...]   run the Python server with uvx instead (needs uv;",
+      "                              extra arguments are passed through to it)",
+      "",
+      "Environment:",
+      "  APIGURU_API_KEY   bill an Apiguru account (sent as X-API-KEY); omit to stay keyless",
+      "  APIGURU_MCP_URL   default for --url",
+      "",
+      "Docs: https://github.com/apiguru-app/agent-kit",
+      "",
+    ].join("\n"),
+  );
+  process.exit(0);
+}
+if (has("--version") || has("-V")) {
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+
+if (has("--local")) {
+  runLocal(argv.filter((a) => a !== "--local"));
+} else {
+  await runBridge();
+}
+
+// ---------------------------------------------------------------------------
+
+function runLocal(args) {
+  const child = spawn("uvx", ["apiguru-mcp", ...args], { stdio: "inherit" });
+  child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+      fail(
+        "`uvx` was not found. Install uv (https://docs.astral.sh/uv/) or drop " +
+          "--local to use the hosted server, which needs nothing else.",
+        127,
+      );
+    }
+    fail(err.message, 1);
+  });
+  child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => child.kill(sig));
+  }
+}
+
+async function runBridge() {
+  let url;
+  try {
+    url = new URL(valueOf("--url") || process.env.APIGURU_MCP_URL || DEFAULT_URL);
+  } catch {
+    fail("--url must be an absolute http(s) URL");
+  }
+
+  const headers = {
+    "User-Agent": `apiguru-mcp-npm/${version} node/${process.versions.node}`,
+  };
+  const apiKey = (process.env.APIGURU_API_KEY || "").trim();
+  if (apiKey) headers["X-API-KEY"] = apiKey;
+
+  const remote = new StreamableHTTPClientTransport(url, { requestInit: { headers } });
+  const local = new StdioServerTransport();
+
+  let closing = false;
+  const shutdown = async (code = 0) => {
+    if (closing) return;
+    closing = true;
+    await Promise.allSettled([remote.close(), local.close()]);
+    process.exit(code);
+  };
+
+  // Server -> client: responses and server notifications pass straight through.
+  remote.onmessage = (message) => {
+    local.send(message).catch((err) => {
+      process.stderr.write(`apiguru-mcp: cannot write to client: ${err.message}\n`);
+      shutdown(1);
+    });
+  };
+  remote.onerror = (err) => {
+    // Transport noise that is not tied to a request, e.g. the optional GET
+    // stream that a stateless server answers with 405. Failing requests are
+    // answered individually below, so this is only logged on demand.
+    if (process.env.APIGURU_MCP_DEBUG) {
+      process.stderr.write(`apiguru-mcp: remote: ${err.message}\n`);
+    }
+  };
+  remote.onclose = () => shutdown(0);
+
+  // Client -> server: a request that cannot reach the server gets a JSON-RPC
+  // error back instead of leaving the client waiting forever.
+  local.onmessage = async (message) => {
+    try {
+      await remote.send(message);
+    } catch (err) {
+      const isRequest =
+        message && typeof message === "object" && "method" in message && "id" in message;
+      const detail = describe(err, url);
+      if (isRequest) {
+        await local
+          .send({ jsonrpc: "2.0", id: message.id, error: { code: -32000, message: detail } })
+          .catch(() => {});
+      } else {
+        process.stderr.write(`apiguru-mcp: ${detail}\n`);
+      }
+    }
+  };
+  local.onerror = (err) => process.stderr.write(`apiguru-mcp: stdio: ${err.message}\n`);
+  local.onclose = () => shutdown(0);
+
+  for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => shutdown(0));
+
+  await remote.start();
+  await local.start();
+}
+
+function describe(err, url) {
+  const msg = err && err.message ? err.message : String(err);
+  if (err && err.name === "UnauthorizedError") {
+    return (
+      `${url.host} requires a sign-in this bridge cannot perform. Use the keyless ` +
+      `${DEFAULT_URL}, or add ${ACCOUNT_URL} as a connector in a client that supports OAuth.`
+    );
+  }
+  if (/ENOTFOUND|ECONNREFUSED|EAI_AGAIN|fetch failed/i.test(msg)) {
+    return `cannot reach ${url.host}: ${msg}. Check the network, or run with --local to use the Python server via uvx.`;
+  }
+  return `bridge to ${url.host} failed: ${msg}`;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "apiguru-mcp",
+  "version": "1.1.1",
+  "description": "Live Amazon marketplace data for AI agents as MCP tools: product details, reviews, keyword search, best-sellers, deals, live offers and stock, and seller profiles across 20 countries. `npx apiguru-mcp` needs only Node 18+ - no Python, no uv, no API key.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "mcp-server",
+    "amazon",
+    "ecommerce",
+    "product-data",
+    "scraping",
+    "x402",
+    "agent",
+    "claude",
+    "cursor",
+    "codex"
+  ],
+  "homepage": "https://apiguru.app",
+  "bugs": {
+    "url": "https://github.com/apiguru-app/agent-kit/issues",
+    "email": "support@apiguru.app"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apiguru-app/agent-kit.git",
+    "directory": "npm"
+  },
+  "license": "MIT",
+  "author": "Apiguru <support@apiguru.app> (https://apiguru.app)",
+  "type": "module",
+  "bin": {
+    "apiguru-mcp": "bin/apiguru-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "mcpName": "app.apiguru/amazon-data"
+}