bestprice-mcp

BestPrice MCP is the official Model Context Protocol server for BestPrice.gr (a Greek price comparison service), designed to provide AI assistants with read-only shopping decision support, including real-time product search, offer comparison, and price history. It can be used without an account or API key.

Purpose and main capabilities

The server provides four read-only tools for shopping decisions, product search, offer comparison, and price history. All tools are read-only and do not place orders, create alerts, or read account data. Results link to BestPrice product pages, never directly to merchants. Unknown shipping costs are reported as unknown, not as free. Search covers only safe physical products and excludes digital goods, services, and age-restricted categories.

Queries support Greek or English, but result summaries, catalog data, and merchant names are returned in Greek.

How to use

The public endpoint is Streamable HTTP over HTTPS; anonymous shopping is available, and Events optionally supports OAuth. The official registry ID is gr.bestprice/mcp, server version 1.8.4. Public guides are available at https://www.bestprice.gr/mcp。

Multiple clients connect to the same endpoint:

• Claude: connect to BestPrice through the prefilled connector form; Claude Code can use the repository's .mcp.json as project-level configuration.
• Cursor: add it through "Add BestPrice to Cursor"; the configuration is shown in decoded form before being added; the .cursor-plugin/ directory contains the marketplace plugin and agent skill.
• VS Code, Gemini CLI, Qwen Code: all have corresponding extensions, and only import the four tools listed above.
• Codex, Claude plugins, and Agent Skill hosts: plugin.json, mcp.json, and skills/bestprice-shopping/SKILL.md in the root directory form a portable Agent Plugins package; compatible hosts can discover the same Skill under .agents/skills/.
• Copilot: reads .github/plugin/marketplace.json and loads plugin.json, mcp.json, and skills/bestprice-shopping/SKILL.md from the root directory under Agent Plugins 1.0.
• Self-hosted plugin marketplace: the repository can be added directly as a plugin marketplace, with no need to copy tools or Skill logic.
• Gemini API, DeepSeek, Z.ai: runnable examples are available in the examples/ directory, each requiring the corresponding provider's API key; BestPrice itself does not require one.
• Other MCP clients: add the Streamable HTTP server https://mcp.bestprice.gr/mcp；若主机仅支持 stdio, you can use the bridge in the repository. The bridge forwards everything to the public endpoint and accepts the environment variables BESTPRICE_MCP_URL (default public endpoint) and BESTPRICE_MCP_TIMEOUT_MS (default 60000). The Dockerfile can build the same bridge for hosts such as Glama.

Protocol details

• Version negotiation: initialize negotiates 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, and 2024-10-07; when other versions are requested, it returns 2025-11-25. It also supports per-request revisions in 2026-07-28: you must send the MCP-Protocol-Version and Mcp-Method headers (tools/call also requires Mcp-Name), and include io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in each request's _meta; omitting that envelope and only naming the revision version is rejected (-32602).
• Stateless: no MCP-Session-Id is issued or required; DELETE returns 405. A GET with Accept: text/event-stream opens a keep-alive stream, but the server does not send requests or notifications on it.
• Capabilities: compatible clients can use tools and resources. The resource surface includes an optional MCP Apps UI (ui://bestprice/shopping-results-v1.html), a server card (mcp://server-card.json), and a canonical Skill (skill://bestprice-shopping/SKILL.md). On MCP 2026-07-28 it also declares the skills extension: skills/list and skills/get return the single BestPrice Shopping Skill and its SHA-256 digest and byte size, and resources/read returns the exact markdown bytes. There are no prompts, completions, or logging; these methods returntimes -32601.
• Response: clients accepting both application/json and text/event-stream receive a single-event SSE response; if they accept only application/json, /, or no Accept header, they receive a single JSON body. Each tool returns structuredContent conforming to its outputSchema, and for clients that do not pass structured content, accompanying text with the same result.
• Errors: unknown tools are JSON-RPC errors (-32602); invalid parameters and service failures (such as unknown products) are tool results with isError: true, which the model can read and correct.
• Limits: JSON request body maximum 256 KiB (exceeding it returns 413); request timeout 12 seconds; per-client rate limiting returns HTTP 429, JSON-RPC error -32029, and a Retry-After header. JSON-RPC batch arrays are rejected (400).
• Browsers: desktop, CLI, and server-side clients do not send an Origin header and are unaffected. Browser pages can call from allowed AI host origins, bestprice.gr, or localhost (so that MCP Inspector direct mode works); other origins return 403.
• Authentication: the four shopping tools require no account. Optional account linking applies only to events:subscribe; protected resource metadata is at /.well-known/oauth-protected-resource and /mcp/oauth-protected-resource. Events remain disabled during end-to-end authentication.

Browser-native WebMCP

BestPrice pages register 22 contextual WebMCP tools in compatible browsers (contract 2.8), each tool read-only or write-only, covering: structured search results (narrow by price, stock, deals, and sorting) and opening the search results page, the shopper's shopping list and comparisons (readable everywhere, add and remove on product pages), price drop alert dialogs, visible products and load more, filtering and sorting, opening any product by id (read before tab movement), product facts, offers, specifications and price history (including charts), one visible offer action, and BestPrice Shopping Brain—applies to all public pages, including articles and the store, while leaving merchant selection to the shopper. Every tool publishes input and output schemas. Contracts, the fail-closed runtime, deterministic evaluators, and a 47-item natural language dataset are located in webmcp/.

Official MCP Registry and Discovery

Open agent discovery resources include ard.json, ai-catalog.json, a server card, and a provider-neutral BestPrice Shopping skill. The ARD example deliberately uses unbranded shopper intent so that it matches "What should I buy?", price-with-shipping, and purchase-timing requests before the user knows about BestPrice. webmcp.json describes the contextual browser tools exposed by BestPrice pages. The repository is listed in the Gemini CLI extension library as bestprice-shopping; GitHub Agent Finder can ingest public MCP directories and ARD resources. Under distribution/ are external directory contribution files pending submission (a GitHub Agent Finder Skill entry and a Docker MCP Registry remote server entry); these directories must be reviewed in their own repositories, and the checked-in files are submission payloads rather than live listings. Community indexes include Glama, WebMCP Registry, webmcp.com, and cursor.directory.

Development and Testing

Tests require no network: the bridge is tested against an in-process fake remote. Node 20 or later is required, and .nvmrc pins 22. Two versions deliberately appear in the repository: the package version in package.json and in each plugin/extension manifest (updated when this repository's manifest, bridge, or WebMCP layer changes, and tagged as vX.Y.Z); and the server version at the top of server.json and the README (the version reported by the hosted service, published to the official MCP Registry). CHANGELOG.md tracks the package version. Timestamped hosted-service checks are recorded separately.

Applicable Scenarios

Suitable for users and developers who want to make shopping decisions, search for products, compare quotes, and query price history in the Greek market with an AI assistant.

Limitations

All tools are read-only: they do not place orders, create reminders, or read account data; search excludes digital goods, services, and age-restricted categories;results link to BestPrice product pages rather than merchants; unknown shipping costs are reported as unknown; query language supports Greek and English but results are returned in Greek; subject to rate limits and request timeouts.