# Amazon Product Research MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
gives an AI assistant (e.g. Claude Code) tools to search and inspect Amazon
product data, over stdio.

## Features

- **`search_products`** — search products by keyword.
- **`get_product`** — fetch full details for a single product by ID.
- Written in strict TypeScript, validated at runtime with [Zod](https://zod.dev).
- Unit tested with [Vitest](https://vitest.dev).
- Linted with [ESLint](https://eslint.org) (`typescript-eslint`) and formatted
  with [Prettier](https://prettier.io).

## Project structure

```
src/
├── index.ts              # Entry point: wires the server to a stdio transport
├── server.ts              # Registers MCP tools on the McpServer instance
├── types/
│   └── product.ts         # Shared Product type
└── tools/
    ├── product-data.ts     # In-memory product catalog (mock data)
    ├── search-products.ts  # search_products tool: input schema + handler
    └── get-product.ts      # get_product tool: input schema + handler
tests/
├── search-products.test.ts
└── get-product.test.ts
```

## Requirements

- Node.js 20+
- npm

## Getting started

```bash
npm install
npm run dev
```

This starts the server over stdio using `tsx`, ready to be connected to by an
MCP client.

### Connecting from Claude Code

```bash
claude mcp add amazon-research -- npx tsx /absolute/path/to/amazon-product-research-mcp/src/index.ts
```

## Scripts

| Command                | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `npm run dev`          | Run the server directly from TypeScript source. |
| `npm run build`        | Type-check and compile to `dist/`.              |
| `npm start`            | Run the compiled server from `dist/`.           |
| `npm test`             | Run the unit test suite (Vitest).               |
| `npm run lint`         | Lint the codebase with ESLint.                  |
| `npm run format`       | Format the codebase with Prettier.              |
| `npm run format:check` | Check formatting without writing changes.       |

## Tools reference

### `search_products`

Search Amazon products by keyword (matches against the product name,
case-insensitive).

**Input**

```json
{ "query": "kindle" }
```

**Output**

```json
[
  {
    "id": "kindle-paperwhite",
    "name": "Kindle Paperwhite",
    "price": 169.99,
    "currency": "USD",
    "rating": 4.7,
    "reviewCount": 12543,
    "description": "A high-resolution e-reader designed for reading comfortably indoors and outdoors."
  }
]
```

### `get_product`

Get full details for a single product by its ID.

**Input**

```json
{ "product_id": "kindle-paperwhite" }
```

**Output**: a single `Product` object, or `null` if no product matches.

## Data

Product data currently lives in a small in-memory mock catalog
(`src/tools/product-data.ts`) rather than a live Amazon API — this keeps the
project self-contained and safe to run without any credentials. `.env.example`
documents the environment variables a real API integration would need.

## License

[MIT](./LICENSE) © Ludovic Delot Bravo