# eanscan-cli

A CLI **and** an [MCP](https://modelcontextprotocol.io) server that turn an EAN/UPC
barcode into a localized product description (title, description, features, price,
images) using the [Eanscan](https://eanscan.com) API.

- `eanscan` — command-line tool
- `eanscan-mcp` — Model Context Protocol server (stdio), usable from Claude
  (Desktop / Code) and GitHub Copilot (VS Code).

## Install

```bash
# from the repo
pnpm install
pnpm build

# or, once published
npm install -g eanscan-cli
```

## Configuration

| Env var            | Default                     | Purpose                                   |
| ------------------ | --------------------------- | ----------------------------------------- |
| `EANSCAN_API_URL`    | `https://api.eanscan.com` | API base URL                             |
| `EANSCAN_API_KEY`    | _(unset)_                 | Optional, sent as the `x-api-key` header |
| `EANSCAN_TIMEOUT_MS` | `120000`                  | Per-request timeout used by the MCP tool |

Copy `.env.example` to `.env` to set them locally, or pass `--api-url` / `--api-key`
on the CLI.

## CLI usage

```bash
eanscan 5449000000996                 # English description (default)
eanscan 5449000000996 -l fr           # French
eanscan 5449000000996 --all           # every available locale
eanscan 5449000000996 --json          # raw product JSON
eanscan 5449000000996 -f description   # just the description text
eanscan 5449000000996 -f title -l de  # German title only

# Batch: pass several EANs at once (looked up concurrently)
eanscan 5449000000996 4006381333931 --json
eanscan 5449000000996 4006381333931 -c 10   # up to 10 in flight

# Bound how long a single request may take
eanscan 5449000000996 --timeout 30000        # 30s
```

Flags: `--timeout <ms>` (default `120000`) caps each request;
`--concurrency <n>` (default `5`) limits parallel lookups in batch mode.

With multiple EANs, `--json` emits an array of `{ ean, data, error? }`.

Exit codes: `0` all found · `1` any error (bad input, network, API, timeout) ·
`2` any EAN had no product.

## MCP server

The server speaks MCP over stdio and exposes one tool:

**`lookup_ean`** — params: `ean` (12–14 digit string), `locale` (`fr` | `en` |
`es` | `de`, default `en`). Returns a human-readable description plus the full
product object as `structuredContent`.

### Claude Code

```bash
claude mcp add eanscan -- node /absolute/path/to/eanscan-cli/dist/mcp.js
```

### Claude Desktop

Edit `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "eanscan": {
      "command": "node",
      "args": ["/absolute/path/to/eanscan-cli/dist/mcp.js"],
      "env": {
        "EANSCAN_API_URL": "https://api.eanscan.com"
      }
    }
  }
}
```

### GitHub Copilot (VS Code)

Add to `.vscode/mcp.json` in your workspace (or the global MCP settings):

```json
{
  "servers": {
    "eanscan": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/eanscan-cli/dist/mcp.js"]
    }
  }
}
```

Then in Copilot Chat (agent mode) you can ask: _"Look up EAN 5449000000996 in French."_

## Development

```bash
pnpm dev:cli 5449000000996   # run the CLI from source (tsx)
pnpm dev:mcp                 # run the MCP server from source
pnpm typecheck
```