bestprice-mcp

# BestPrice MCP

[![CI](https://github.com/TheBestCo/bestprice-mcp/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/TheBestCo/bestprice-mcp/actions/workflows/test.yml)
[![Glama score](https://glama.ai/mcp/servers/TheBestCo/bestprice-mcp/badges/score.svg)](https://glama.ai/mcp/servers/TheBestCo/bestprice-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

The official [Model Context Protocol](https://modelcontextprotocol.io/) server for
[BestPrice.gr](https://www.bestprice.gr/), Greece's price-comparison service. It gives AI
assistants read-only access to shopping decisions, live product search, offer comparison,
and price history. No account or API key is needed.

![BestPrice MCP: products, offers and price history for AI assistants](https://www.bestprice.gr/extra/mcpLanding/assets/bestprice-mcp-share.png)

## Start shopping

- [Open BestPrice in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a8d8ed6e2bc8191b3caaf7214f3c981) and add the published plugin.
- [Connect BestPrice to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=BestPrice&connectorUrl=https%3A%2F%2Fmcp.bestprice.gr%2Fmcp) using the prefilled connector form.
- See the [shopping guide](https://www.bestprice.gr/en/mcp) for examples and other assistants.

For developer integrations, the public endpoint is:

```text
https://mcp.bestprice.gr/mcp
```

- Transport: Streamable HTTP over HTTPS; anonymous shopping, optional OAuth for Events
- Official Registry ID: `gr.bestprice/mcp`
- Server version: `1.8.3`
- Public guide: <https://www.bestprice.gr/mcp>
- Support: <https://www.bestprice.gr/contact>

This repository holds everything that lives outside the hosted service: the install
manifests for each AI client, a local stdio bridge for hosts that cannot speak HTTP, and
the browser-native WebMCP layer. The server itself is not in this repository.

The [current release matrix](submission/current-release-matrix.md) records the
live gateway, UI, OAuth/Events, plugin review and separate ACP qualification.

## Tools

| Tool | What it does | Key arguments |
| --- | --- | --- |
| `get_shopping_decision` | Runs the BestPrice Shopping Brain: an evidence-backed recommendation, need-based comparison, or read-only basket plan with reasons, tradeoffs, and unknowns. | `message` (the need in Greek or English, including any budget), optional `postal_code` (required for a completed basket plan), optional `evidence_detail` (`summary`, the default: only the evidence the answer cites; `full`: every claim and source) |
| `search_products` | Finds canonical products in the catalog. Returns product IDs and the catalog minimum price before shipping. | `query` (2–200 characters: a name, model, category, or a bare GTIN/EAN barcode), optional `price_min`, `price_max`, `required_features`, `sort` (`relevance`, `price_asc`, `price_desc`), `limit` (1–8) |
| `compare_offers` | Compares current merchant offers for one exact product, separating item price, shipping, and delivered total. | `product_id` from a previous result, optional `postal_code` (a Greek postcode, 10000–85999, for delivered totals), `objective`, `in_stock_only`, `minimum_merchant_rating`, `limit` (1–10) |
| `get_price_history` | Summarises how a product's price moved over time, against its 180-day median. | `product_id`, optional `period_days` (30, 90 or 180) |

All four tools are read-only. They never place orders, create alerts, or read account
data. Results link to a BestPrice product page, never directly to a merchant. Unknown
shipping is reported as unknown, not as free. Search covers safe physical products;
digital goods, services, and age-restricted categories are excluded.

## Protocol details

Measured against the live endpoint on 24 September 2026.

- **Versions.** `initialize` negotiates `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`
  and `2024-10-07`; a client that asks for any other version is answered with `2025-11-25`.
  The `2026-07-28` per-request revision is also served: send the `MCP-Protocol-Version`,
  `Mcp-Method` (and, for `tools/call`, `Mcp-Name`) headers, and put
  `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in
  every request's `_meta`. A request that names the revision without that envelope is refused
  with `-32602`.
- **Stateless.** No `MCP-Session-Id` is issued and none is required; `DELETE` answers `405`.
  A `GET` with `Accept: text/event-stream` opens a keep-alive stream, but the server never sends
  requests or notifications on it, so a client loses nothing by not opening it.
- **Capabilities.** `tools` and `resources` are available to compatible clients. The
  resource surface contains the optional MCP Apps UI at `ui://bestprice/shopping-results-v1.html`,
  the server card at `mcp://server-card.json`, and the canonical
  `skill://bestprice-shopping/SKILL.md`. On MCP `2026-07-28` the server also declares the
  final `io.modelcontextprotocol/skills` extension: `skills/list` and `skills/get` return the
  one BestPrice Shopping Skill with its SHA-256 digest and byte size, and `resources/read`
  returns the exact markdown bytes. Older clients simply see the Skill as an ordinary resource.
  There are no prompts, completions or logging; those methods answer `-32601`.
- **Responses.** A client that accepts both `application/json` and `text/event-stream` gets a
  one-event SSE response. `Accept: application/json`, `*/*` or no `Accept` header gets a single
  JSON body. Every tool returns `structuredContent` that validates against its `outputSchema`,
  plus the same result as text for clients that do not pass structured content to the model.
- **Errors.** An unknown tool is a JSON-RPC error (`-32602`). Invalid arguments and service
  failures such as an unknown product are tool results with `isError: true`, so the model can
  read and correct them.
- **Limits.** JSON request bodies up to 256 KiB (`413` above that), a 12-second request
  deadline, and per-client rate limits answered with HTTP `429`, JSON-RPC error `-32029` and a
  `Retry-After` header. JSON-RPC batch arrays are refused with `400`.
- **Browsers.** Desktop, CLI and server-side clients send no `Origin` header and are not
  affected. A browser page may call the endpoint from an allowlisted AI-host origin, from
  bestprice.gr, or from `localhost` (so MCP Inspector works in direct mode); any other origin
  gets `403`.
- **Authentication.** The four shopping tools work without an account. Optional account
  linking is scoped to `events:subscribe`; protected-resource metadata is available at
  `/.well-known/oauth-protected-resource` and `/mcp/oauth-protected-resource`.
  Events remains disabled during end-to-end qualification.

## Developer quick start

Every client below connects to the same endpoint. Detailed, provider-specific
instructions including OpenAI, Grok, GitHub Copilot, and Microsoft Copilot Studio are in
[`docs/provider-setup.md`](docs/provider-setup.md).

### Claude

[Connect BestPrice to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=BestPrice&connectorUrl=https%3A%2F%2Fmcp.bestprice.gr%2Fmcp)
opens the custom-connector flow with the endpoint prefilled. For Claude Code:

```sh
claude mcp add --transport http bestprice-shopping https://mcp.bestprice.gr/mcp
```

The bundled [`.mcp.json`](.mcp.json) is the equivalent project-scoped configuration.

### Cursor

[Add BestPrice to Cursor](https://cursor.com/install-mcp?name=bestprice-shopping&config=eyJ1cmwiOiJodHRwczovL21jcC5iZXN0cHJpY2UuZ3IvbWNwIn0%3D)
shows the decoded configuration before adding it. The [`.cursor-plugin/`](.cursor-plugin/)
directory holds the marketplace plugin and an agent skill.

### VS Code

[Add BestPrice to VS Code](vscode:mcp/install?%7B%22name%22%3A%22bestprice-shopping%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.bestprice.gr%2Fmcp%22%7D)

### Gemini CLI and Qwen Code

```sh
gemini extensions install https://github.com/TheBestCo/bestprice-mcp
qwen extensions install https://github.com/TheBestCo/bestprice-mcp --consent
```

Both extensions restrict the imported tools to the four listed above.

### Codex, Claude plugins, and Agent Skill hosts

The root [`plugin.json`](plugin.json), [`mcp.json`](mcp.json), and
[`skills/bestprice-shopping/SKILL.md`](skills/bestprice-shopping/SKILL.md) form a portable
Agent Plugins package: the MCP supplies live shopping data and the Skill teaches the host when and
how to route unbranded Greek shopping intent.
Agent-compatible hosts that discover repository-local skills under `.agents/skills/` get the
same canonical workflow at [`.agents/skills/bestprice-shopping/SKILL.md`](.agents/skills/bestprice-shopping/SKILL.md). [`.codex-plugin/`](.codex-plugin/) remains the
Codex compatibility manifest. [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) plus the
same root Skill and [`.mcp.json`](.mcp.json) also make this repository a Claude plugin package.


### Self-hosted plugin marketplaces

The same repository can be added directly as a plugin marketplace, with no copied tool or Skill logic:

```sh
copilot plugin marketplace add TheBestCo/bestprice-mcp
copilot plugin install bestprice-shopping@bestprice

claude plugin marketplace add TheBestCo/bestprice-mcp
claude plugin install bestprice-shopping@bestprice
```

Copilot reads [`.github/plugin/marketplace.json`](.github/plugin/marketplace.json) and, under
Agent Plugins 1.0, loads the canonical root `plugin.json`, `mcp.json`, and
`skills/bestprice-shopping/SKILL.md`. Claude reads
[`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and uses
`.claude-plugin/plugin.json`, `.mcp.json`, and the same root Skill.

### Gemini API, DeepSeek, Z.ai

Runnable examples live in [`examples/`](examples/): the Gemini Interactions API and Genkit,
a DeepSeek Harness plugin entry, and a Z.ai GLM call. Each needs the provider's own API key.
BestPrice n