Skip to main content
Glama
Sign In
3vgen

market-screening

by 3vgen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

market-screening

MCP server that helps an LLM answer "where should I buy my grocery list?" across Russian retail chains. You give the assistant a shopping list; it searches the products in the stores you shop at, matches comparable items (by price per kg / l), and computes the cheapest plan: everything in one store, or split across 2–3 stores.

Status: early prototype.

Chain

Status

Source

Notes

Magnit

✅

website JSON API

per-store prices, stock, promos, card-only badges

VkusVill

✅

server-rendered search page

default-region (Moscow) prices, no per-store stock

Dixy

❌

—

listing endpoint behind WAF (403)

Pyaterochka, Perekrestok, Lenta

❌

—

JS anti-bot challenge

How it works

Tool

What it does

list_stores

Stores from your config.toml

search_products(query, stores?, limit?)

Products with price, promo/old price, price per kg/l, stock, card-only badges

optimize_basket(basket, max_stores, extra_store_cost)

Exact totals: best single store vs best split, saving

The LLM does the fuzzy part (which "молоко" in each store is comparable); the server does the arithmetic, so totals are not hallucinated.

Data comes from the same public JSON endpoints the chains' websites use, without login. Results are cached for 15 minutes to keep the load on the sites minimal.

Related MCP server: PriceAtlas MCP Server

Setup

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp config.example.toml config.toml   # put your store codes there

Finding your Magnit store code: open magnit.ru, pick your store, then DevTools → Network → goods/search → Payload → storeCode.

Claude Code

claude mcp add market-screening -e MARKET_SCREENING_CONFIG=$PWD/config.toml -- $PWD/.venv/bin/market-screening

Claude Desktop / other MCP clients

{
  "mcpServers": {
    "market-screening": {
      "command": "/path/to/market-screening/.venv/bin/market-screening",
      "env": { "MARKET_SCREENING_CONFIG": "/path/to/market-screening/config.toml" }
    }
  }
}

Network note

Chains often block foreign IPs. If you use a VPN, route the chains' domains directly (split tunneling), e.g. for v2rayA RoutingA — place these above any geosite: rules:

domain(domain:magnit.ru, domain:dixy.ru, domain:vkusvill.ru)->direct

Adding a chain

Create src/market_screening/adapters/<chain>.py with an Adapter subclass that implements _search(store, query, limit) -> list[Product], register it in adapters/__init__.py, and add a parsing test with a small fixture in tests/.

Disclaimer

Unofficial project, not affiliated with any retailer. Endpoints are undocumented and may change. Intended for personal use; respect the sites' terms and keep request volume low.

License

MIT

Available Tools

3 tools
list_storesC

Stores configured by the user (chain, store code, name). Use the key field elsewhere.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full disclosure burden and largely drops it: it does not state that this is a read-only operation, whether the full set of configured stores is returned or paginated, or what happens when none exist. Only the mention of descriptive fields gives any behavioral hint, and that mostly duplicates the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two very short clauses with no wasted words, and the resource identity is front-loaded. The trailing pointer about the `key` field is terse to the point of being cryptic, but the overall size is appropriate for a trivial no-arg lookup.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not required, and a zero-parameter tool is inherently simple. However, with no annotations the description should have stated the read-only nature and whether the list is complete or paginated; those omissions leave a modest but real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond the schema. The note about the `key` field usefully tells the agent how to consume results elsewhere, which adds a small amount of semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('Stores configured by the user') and its identifying fields (chain, store code, name), but never states an explicit verb such as 'list' or 'returns'. An agent can infer enumeration from the tool name, but the description itself is a noun phrase rather than a clear action statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only guidance is 'Use the `key` field elsewhere', which hints at cross-referencing results but never says when to call this tool or what it replaces. No alternatives or exclusions are given, and the listed siblings (search_products, optimize_basket) are not addressed, leaving the agent to infer that this is a prerequisite lookup.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

optimize_basketA

Compute the cheapest way to buy the basket.

basket: [{"item": "молоко", "quantity": 2, "offers": {"magnit:123456": 89.99, "dixy:123": 92.5}}]

  • offers: price in rubles per one unit of quantity, for the product you matched in each store; omit a store if it has no suitable product. max_stores: how many different stores the user is willing to visit. extra_store_cost: rubles the user is willing to pay to avoid each extra store visit.

NameRequiredDescriptionDefault
basketYes
max_storesNo
extra_store_costNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It helpfully explains offers as per-unit prices for matched products and says to omit a store with no suitable product, and explains the extra_store_cost tradeoff, but it does not state whether the operation has side effects or what the result looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loads the purpose before giving the basket example and parameter meanings. It earns most of its words, though the example formatting is somewhat dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It covers the input shape and optimization semantics well for a tool with no annotations and limited schema descriptions. However, with no output schema, the description should say what kind of result the optimizer returns, and it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does so substantially: the basket example clarifies item, quantity, and offers, and it explicitly defines max_stores and extra_store_cost in user-facing terms.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: compute the cheapest purchase plan for a basket. It is clearly different from list_stores and search_products, though it does not explicitly name or contrast those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The optimization purpose implies when to use it, but there is no explicit guidance on when to choose it versus search_products or list_stores, nor any prerequisite or exclusion conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_productsA

Search a product in the configured stores.

query: what to look for, in Russian, e.g. "молоко 2.5%", "куриное филе". stores: optional list of store keys from list_stores (default: all). Returns per store a list of products: price in rubles, old_price if on promo, unit_price per kg / l / pcs (compare by this), stock, badges, url. Search is fuzzy: results can include unrelated items (e.g. oat drink for "молоко").

NameRequiredDescriptionDefault
limitNo
queryYes
storesNo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, and it does well: it discloses fuzzy matching that can return unrelated items, and describes returned fields such as price in rubles, old_price during promo, unit_price for comparison, stock, badges, and url. It omits limit behavior, rate limits, and any auth/permission context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, then labeled parameter notes, return shape, and the important fuzzy-search caveat. It is dense but efficient, with no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with no output schema and no annotations, it supplies substantial context: query language, store scoping, return fields, and fuzzy behavior. It is not fully complete because limit semantics and any pagination or permission behavior are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains query semantics (Russian, examples) and stores semantics (optional store keys from list_stores, default all), but it does not document the limit parameter at all, leaving one of three parameters unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Search') and resource ('product') with scope ('configured stores'). It references list_stores only as the source of store keys, and does not explicitly contrast itself with optimize_basket or any other alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives useful usage context: query should be in Russian with examples, and stores is optional with default all, sourced from list_stores. However, it does not say when to use this tool versus optimize_basket, nor give any when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedlist_stores
    • First observedoptimize_basket
    • First observedsearch_products
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 3 tools

Disambiguation5/5

Each tool occupies a distinct stage of a clear pipeline: list_stores enumerates configured stores, search_products finds items with prices, optimize_basket computes the cheapest multi-store purchase. There is no overlap in purpose or output, so an agent cannot plausibly misselect.

Naming Consistency5/5

All three names follow the same snake_case verb_noun convention (list_stores, search_products, optimize_basket), with the verb accurately signaling the operation (list vs. search vs. optimize).

Tool Count4/5

Three tools map cleanly onto the domain's three steps (enumerate stores, search products, optimize basket), so no tool is filler. It sits at the lean end of appropriate: there is no direct product-lookup or price-refresh tool, which would round the set out.

Completeness4/5

The end-to-end flow (stores -> products -> cheapest basket) is covered and the schemas are explicit about how data passes between tools. The gap is that prices/offers must be hand-carried from search_products into optimize_basket, and there is no key-based product or price lookup to refresh an item without a new fuzzy search.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • PriceAtlas MCP Server

    musaceylan
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to track global food prices, search products by barcode or name, and compare costs across 27 countries. It provides tools for real-time price scraping and data aggregation from major international supermarket chains.
    8
    4
    MIT

  • Pyaterochka MCP Tool

    dreamcatchered
    A
    license
    C
    quality
    D
    maintenance
    Enables AI assistants and MCP clients to search Pyaterochka stores, browse categories, find products with filters for price, brand, and promotions, and retrieve product details, store hours, and promotion conditions through the exposed MCP tools.
    12
    10
    MIT