grocery-deals-mcp

by tx-smitht

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have distinct purposes, but there is overlap between list_stores and kroger_find_stores (both find stores) and between search_deals and kroger_search (both search for products, though against different data sources). Descriptions clarify the differences well enough.
Naming Consistency3/5
Naming style is mixed: list_stores, search_deals, price_check, and refresh_deals follow verb_noun, while store_circular and shopping_plan are noun phrases, and kroger_search/kroger_find_stores add a brand prefix. All use snake_case, but the inconsistent verb/prefix usage is noticeable.
Tool Count5/5
Eight tools is well-scoped for a grocery deals server. Each tool serves a clear purpose within the domain, and none feel redundant or excessive.
Completeness4/5
The set covers the core lifecycle: discover stores, search deals, view circulars, plan shopping, check price history, and refresh data. The Kroger-specific tools add precision. Minor gaps exist (e.g., no store details or deal detail endpoint), but agents can accomplish primary workflows.
Average 4.3/5 across 8 of 8 tools scored. Lowest: 3.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavioral traits. It explains that zip_code is optional if GROCERY_ZIP is set and that limit has a default, which adds useful behavioral context. However, it does not explicitly state read-only semantics, potential errors, or what happens if the store is not found. These are relatively minor for a read-only 'show' tool, but the description is not exhaustive.
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 two sentences plus a compact Args block. The purpose is front-loaded, and every sentence provides useful information. There is no redundancy or filler.
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?
Given the tool's simplicity and the presence of an output schema, the description is largely complete. It covers the tool's function and all parameter semantics. It does not discuss error cases, but that is not strictly necessary when an output schema exists. It could be improved by mentioning the relationship to sibling tools, but that is not critical.
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 schema has 0% description coverage, so the description must compensate. It fully documents all three parameters: store with examples, zip_code with format and conditional need, and limit with default. This adds meaningful guidance beyond the schema, though it could include more detail on accepted formats or edge cases.
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?
The description clearly states the tool's function: showing everything in one store's current weekly ad. It specifies the resource (store's weekly ad) and the scope (one store), which differentiates it from sibling tools like search_deals that likely search across stores. It could be more explicit about how it relates to siblings, but the purpose is clear and specific.
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 description implies the use case—when you want a full weekly ad for a specific store. It does not explicitly mention alternatives or when not to use it, but the purpose is clear enough that an agent can infer when to invoke it. There is no explicit exclusion or comparison to sibling tools like search_deals or price_check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the time cost (10-20 seconds) and the forced rebuild nature, which implies a mutating operation. However, it does not mention potential side effects, authorization needs, or impact on concurrent operations.
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 compact—three sentences plus a one-line parameter note. Every sentence adds value, with the main purpose and timing front-loaded.
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 single-parameter tool with an output schema, the description covers purpose, timing, usage guidance, and parameter semantics. It lacks only deeper runtime implications such as whether the rebuild blocks other operations or requires specific credentials, but these are not essential for basic invocation.
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 input schema provides only a property name and default, with 0% description coverage. The description's Args section compensates by specifying '5-digit US ZIP code' and noting it is 'Optional if GROCERY_ZIP is set', giving format and conditional requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Force a rebuild of the deal index from Flipp' with a specific verb and resource, distinguishing it from siblings like search_deals which query the index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Only needed mid-week; the index otherwise refreshes itself' provides explicit when-to-use and when-not-to-use guidance. It implies the alternative of waiting for automatic refresh, though doesn't name a specific sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The verb 'Find' implies read-only, and the description clarifies it returns store IDs, but it doesn't explicitly state side-effect-free behavior, output shape, or edge cases. Adequate for a simple lookup.
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 succinct and front-loaded: a one-sentence purpose followed by an Args section. The example and matching note are useful without being verbose.
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 simple find tool with two optional parameters, the description covers purpose, prerequisite, and parameter details. An output schema exists, so return values don't need description. Minor gap: does not define 'nearby' radius or result ordering, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions for the two parameters, but the description fully compensates. It explains zip_code format and optionality, and chain filtering with examples and matching semantics ('Matched against store name and chain code'), adding significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Find nearby Kroger-banner store IDs' with a specific verb and resource. It also explicitly positions the tool as a prerequisite for kroger_search, distinguishing it from sibling tools like list_stores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use guidance: 'needed once to use kroger_search'. It also explains parameter optionality and the chain filter. It doesn't explicitly mention alternatives or when not to use it, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the core behavior (listing stores near ZIP with active ads and deal counts) and the optional ZIP behavior, but does not mention potential error conditions, pagination, or rate limits. This is adequate for a simple read-only tool but lacks richer behavioral 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 concise and well-structured: a clear one-sentence purpose statement, a 'Start here' usage hint, and a compact Args section. Every part earns its place without redundant detail or excessive length.
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 simple single-parameter tool with an output schema present, the description covers the essentials: what the tool does, the input format, and optional behavior. It does not explain return-value details, but the output schema fills that gap. Minor missing context includes what happens if no ZIP is provided and no default is configured, but this is a small omission for the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides a title and default for zip_code, with no description. The tool description fully compensates by specifying it as a 5-digit US ZIP code, giving an example, and clarifying it is optional when a server default exists. This adds significant semantic value beyond the schema, making the parameter's meaning and usage unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List grocery stores near a ZIP code that have an active weekly ad, with how many deals each is running.' This is a specific verb+resource+scope and differentiates itself from siblings like search_deals or store_circular by focusing on store-level results with deal counts. The addition of 'Start here' further positions its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Start here' explicitly signals when this tool should be used as an entry point, giving clear context. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, so it stops short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. It reveals that the search covers this week's ads across all local stores and that zip_code is optional if GROCERY_ZIP is set. It does not describe error conditions, result sorting, or whether any side effects occur, but for a read-only search tool, this level of transparency is acceptable.
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 opens with a one-sentence summary and then uses a structured Args list. It is concise, with no filler, and every sentence adds value.
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?
Given the tool's complexity (5 params) and the presence of an output schema, the description provides sufficient context for correct invocation: it specifies what is searched, the optional filters, and the default limit. It could be improved by noting any restrictions on query format or behavior when no results are found, but these are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), so the description's Args section fully compensates by explaining each parameter with examples, including the optionality of zip_code, the list format for stores, and the default for limit. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search this week's ads') and the scope ('across every local grocery store') for a product. This distinguishes it from sibling tools like price_check or store_circular, which likely target specific stores or pricing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is for searching products in weekly grocery ads. It implies a general product search, but does not explicitly mention when to use alternative sibling tools like price_check or kroger_search. Since it explains the tool's role, it merits a 4, though explicit exclusions would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It does so by stating the credential requirement, the official API source, and the banner store coverage. It does not mention failure modes or rate limits, but it covers the key auth prerequisite and precision claim.
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 front-loaded with the core purpose in the first sentence and uses a clear Args block for parameter details. The list of banners is useful but somewhat lengthy. Overall, it is concise and well-structured.
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?
The output schema covers return values, so the description focuses on inputs, auth, and comparison to the circular. It lacks explicit differentiation from price_check or search_deals, but the credential note and 'more precise than the circular' cover common alternatives. For a search/pricing tool, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no per-parameter descriptions (0% coverage), so the description fully compensates by explaining each parameter: query with example, location_id as store ID from kroger_find_stores with optionality based on an environment variable, and limit with default. This adds complete semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Exact SKU-level prices (regular and promo) from a Kroger-banner store via Kroger's official API' and lists specific banners. It distinguishes itself from store_circular by claiming higher precision and from other tools through the credential requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly notes that 'Requires Kroger API credentials; without them the other tools still work,' signalling when to use this tool. It also says 'More precise than the circular,' providing a direct comparison to store_circular. However, it does not explicitly mention alternatives like price_check or search_deals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the tool relies on locally accumulated price history and that its value grows over time. It implies a read-only action with no side effects. While it doesn't detail the output format or how 'good' is computed, the mention of data source and temporal dependency adds meaningful context beyond a simple 'check price'.
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 concise and well-structured. The first sentence front-loads the purpose, followed by a brief limitation note and a clear parameter list. Every sentence earns its place—no filler words or redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (two params, no annotations) and the presence of an output schema, the description is remarkably complete. It covers what the tool does, how it works (history accumulation), parameter semantics, and even a practical consideration (usefulness over time). There is no missing critical information for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains both parameters: 'item' with an example ('boneless chicken breast') and 'zip_code' with format ('5-digit US ZIP code') and optionality condition (optional if GROCERY_ZIP is set). This adds critical meaning beyond the bare schema, which only provides types and a default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Judge whether a current price is actually good, using the price history this server accumulates.' This specific purpose distinguishes it from sibling tools like search_deals or store_circular, which are about finding deals, not evaluating a price's quality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you have a current price and want to assess it against historical data. It doesn't explicitly name alternatives or exclusions, but the uniqueness of the use case (price judgment vs. searching deals) makes the usage implied. The note about accumulating history also hints at when it may be less useful (recently started server).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavior disclosure, and it adds useful context beyond the schema: zip_code is optional if GROCERY_ZIP is set, max_stores defaults to 2, and items are demonstrated with a concrete example. It does not describe failure modes or network dependencies, but it clearly describes the core behavior for a non-destructive planning tool.
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 a single front-loaded sentence stating the tool's purpose, followed by a compact Args block. No filler or redundant information; every sentence provides value, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the presence of an output schema, and no annotations, the description covers all necessary aspects: what it does, required/optional inputs, defaults, and an example. There is no significant missing context for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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, and it does thoroughly. Each parameter is explained: items with an example, zip_code with format and optionality, and max_stores with its meaning and default. This adds meaning well beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb phrase 'Turn a shopping list into a trip plan' and clearly identifies the resource and output: which store to buy each item at. This differentiates it from sibling tools like list_stores or price_check, which focus on individual store data or pricing rather than multi-store planning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended context explicit: you use this when you have a shopping list and need to know where to buy each item. It does not explicitly name alternatives or state when not to use it, but the 'trip plan' framing and parameter examples provide clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![grocery-deals-mcp MCP server](https://glama.ai/mcp/servers/tx-smitht/grocery-deals-mcp/badges/card.svg)](https://glama.ai/mcp/servers/tx-smitht/grocery-deals-mcp)

Score Badge

Copy to your README.md:

[![grocery-deals-mcp MCP server](https://glama.ai/mcp/servers/tx-smitht/grocery-deals-mcp/badges/score.svg)](https://glama.ai/mcp/servers/tx-smitht/grocery-deals-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tx-smitht/grocery-deals-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server