Metadata-Version: 2.4
Name: mcp-shopee-seller
Version: 0.5.0
Summary: MCP server para vendedores Shopee (Open Platform API v2) — pedidos, produtos, finanças, promoções, chat e ads via agentes de IA. Roda 100% local.
License-Expression: MIT
Keywords: ai-agent,e-commerce,marketplace,mcp,shopee
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: marketplace-mcp-core>=0.1.0
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.1
Description-Content-Type: text/markdown

# mcp-shopee-seller

Servidor [MCP](https://modelcontextprotocol.io) para a **Shopee Open Platform API v2**.
Permite que agentes de IA (Claude Code, Codex, Cursor, Antigravity etc.) administrem
sua loja Shopee: pedidos, produtos/estoque, logística, finanças, promoções, chat e ads.

**Roda 100% no seu computador** — os dados da loja trafegam direto entre o seu PC e a
Shopee; tokens ficam salvos localmente no seu perfil de usuário.

## Tools (42)

| Módulo | Tools |
|--------|-------|
| Conexão de loja | `connect_shop`, `connect_status`, `connect_shop_manual`, `disconnect_shop`, `list_authorized_shops` |
| Pedidos | `list_orders`, `get_order_details` |
| Produtos & estoque | `list_products`, `get_product_details`, `update_stock`, `update_price` |
| Catálogo (criar/editar anúncios) | `upload_product_image`, `search_categories`, `get_category_requirements`, `create_product`, `update_product`, `set_product_status` |
| Relatórios analíticos | `get_sales_performance_report`, `get_unsold_products_report` |
| Logística | `get_shipping_parameter`, `ship_order`, `get_tracking_info`, `get_logistics_channels` |
| Finanças | `get_payout_detail`, `list_wallet_transactions` |
| Promoções (vouchers) | `list_vouchers`, `get_voucher`, `create_voucher`, `end_voucher` |
| Chat (atendimento) | `list_conversations`, `get_messages`, `send_message` |
| Shopee Ads | `get_ads_balance`, `get_ads_shop_info`, `get_ads_daily_performance`, `get_recommended_keywords`, `create_ads_campaign`, `pause_ads`, `resume_ads`, `delete_ads` |
| Genérico / diagnóstico | `shopee_api_call`, `shopee_status` |

## Instalação

Pré-requisito único: [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).

**Claude Code:**
```bash
claude mcp add shopee --env MCP_BROKER_URL=... --env MCP_LICENSE_KEY=... -- uvx mcp-shopee-seller
```

**Claude Desktop / Cursor / Antigravity** (JSON de MCP servers):
```json
{
  "mcpServers": {
    "shopee": {
      "command": "uvx",
      "args": ["mcp-shopee-seller"],
      "env": { "MCP_BROKER_URL": "...", "MCP_LICENSE_KEY": "..." }
    }
  }
}
```

**Codex** (`~/.codex/config.toml`):
```toml
[mcp_servers.shopee]
command = "uvx"
args = ["mcp-shopee-seller"]
env = { MCP_BROKER_URL = "...", MCP_LICENSE_KEY = "..." }
```

## Modos de operação

| Modo | Variáveis | Para quem |
|------|-----------|-----------|
| **broker** (padrão) | `MCP_BROKER_URL` + `MCP_LICENSE_KEY` | Usuário final. A assinatura HMAC vem do serviço de licença; **somente metadados** (path, timestamp, shop_id) são enviados a ele — pedidos, produtos e valores nunca passam pelo broker. |
| **local** (avançado) | `SHOPEE_PARTNER_ID` + `SHOPEE_PARTNER_KEY` | Quem tem App próprio em [open.shopee.com](https://open.shopee.com). Tudo 100% local, zero serviços de terceiros. |

Variáveis opcionais: `SHOPEE_ENV` (`live` padrão | `sandbox`), `SHOPEE_HOST` (host regional),
`SHOPEE_SHOP_ID` (loja padrão), `SHOPEE_AUTH_PORT` (porta do callback, padrão 38473),
`SHOPEE_TOKEN_FILE`, `SHOPEE_REDIRECT_URL`.

## Conectando sua loja (login)

Basta pedir ao agente: **"conecte minha loja Shopee"**.

1. A tool `connect_shop` abre o navegador na página de autorização da Shopee.
2. Você entra como vendedor e autoriza (a senha nunca passa pelo MCP).
3. O agente chama `connect_status` e a loja fica pronta.

Os tokens ficam em `~/Library/Application Support/marketplace-mcp/shopee/` (macOS),
`%APPDATA%\marketplace-mcp\shopee\` (Windows) ou `~/.config/marketplace-mcp/shopee/`
(Linux), com renovação automática do access token (4h). Multi-loja: repita
`connect_shop` para cada conta; use `shop_id` nas tools para escolher a loja.

Sem navegador (SSH/headless): autorize em outra máquina e cole a URL de redirect na
tool `connect_shop_manual` (ou use o CLI `shopee-authorize`).

## Desenvolvimento

Este pacote faz parte do monorepo (workspace uv) junto com
[`marketplace-mcp-core`](../core). Na raiz do repositório:

```bash
uv sync                                   # cria o venv do workspace
uv run mcp-shopee-seller                  # roda o servidor (stdio)
uv run shopee-authorize --list            # CLI de autorização
```

**Modo local no dev:** crie um `.env` com `SHOPEE_PARTNER_ID`, `SHOPEE_PARTNER_KEY` e
`SHOPEE_ENV=sandbox`, e registre `http://127.0.0.1:38473/callback` como Redirect URL
no painel do seu App.
