brmarket-mcp

# brmarket-mcp

MCP server for **Brazilian marketplace product search**, paid automatically with
[x402](https://x402.org) micropayments (USDC on **Base** or **Solana**).

One call searches **Mercado Livre, Shopee and AliExpress** together and returns a
single normalized shape: BRL prices in integer cents, canonical + affiliate links,
and a per-marketplace `sources` state so a degraded marketplace is never silent.
A free **import-tax calculator** turns a price into the real *landed price* — the
honest "best value **with** Brazilian import tax" comparison.

> **Status: not published yet.** `brmarket-mcp@0.1.0` is built and ready; publishing
> to npm and the MCP registry is a manual step. See *Publishing* below.

## Tools

| Tool | Price | What it does |
|---|---|---|
| `search_products` | $0.01 | Mercado Livre + Shopee + AliExpress in one call. Normalized BRL prices (integer cents), canonical + affiliate links, free shipping, rating, sold count, seller id/name/official-store, `dataAsOf`. |
| `search_by_image` | $0.05 | Same, but from a **product photo**. Returns `interpreted_query` so you can see what was actually searched. |
| `search_products_preview` | **free** | One result, canonical link only, no affiliate link. |
| `calculate_import_taxes` | **free** | Brazilian import tax + landed price of a cross-border purchase (Import Tax 0% ≤ US$50 else 30% − US$20, ICMS por-dentro by state, Bacen PTAX rate). BRL cents or USD in; pass `uf` on `search_products` too for per-offer `landed_price_estimate`. |

### Always read `sources`

Every response reports each marketplace as `ok` / `error` / `timeout` /
`not_configured`. A short result list may mean a marketplace was **down**, not that
the market is thin. Never present a degraded page as the whole market.

## Install

```bash
npx brmarket-mcp
```

Claude Desktop / Claude Code (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "brmarket": {
      "command": "npx",
      "args": ["-y", "brmarket-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x…"
      }
    }
  }
}
```

The free preview tool works with no wallet at all.

## Environment

| Variable | Required | Description |
|---|---|---|
| `EVM_PRIVATE_KEY` | no | `0x…` key of a **dedicated** wallet holding USDC on Base. |
| `SOLANA_PRIVATE_KEY` | no | base58 or JSON-array secret key of a **dedicated** Solana wallet holding USDC. |
| `SOLANA_RPC_URL` | no | RPC override used to build the Solana payment (e.g. a Helius URL). |
| `BRMARKET_BASE_URL` | no | Defaults to `https://brmarket.thomenz.me`. |
| `X402_NETWORK` | no | `base` (default) or `base-sepolia`. |

Configure either rail, or both — the x402 layer settles on whichever the server's
402 advertises. Without any key, paid tools fail with HTTP 402.

> **⚠️ These keys spend real money.** Use dedicated wallets with small balances,
> never a personal or treasury key. Anything that can read this process'
> environment can spend from them.

## Develop

```bash
npm install
npm run build          # tsc -> dist/
npm run typecheck
npm run version:check  # all FIVE version sites must agree
```

## Publishing (manual — Thiago only)

```bash
npm run version:check   # wired into prepublishOnly too
npm publish
```

Then verify **the tarball from the registry**, not the local build:

```bash
npm pack brmarket-mcp@<version> --registry https://registry.npmjs.org
tar -xzOf brmarket-mcp-<version>.tgz package/dist/index.js | grep -o 'version: "[^"]*"'
```

A green build proves nothing about what was published — brdata-mcp 0.3.4 shipped
from a stale source copy and its MCP handshake reported `0.3.2` while npm said
`0.3.4`. Check the tarball.

For the MCP registry, `server.json` carries the full `environmentVariables` block.
Do not drop it: brdata-mcp 0.3.3 published without it and the registry entry lost
every variable.

## License

MIT © Thiago Menzinger