catalog-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HF_HOME | No | Hugging Face cache directory for the embedding model. | |
| CATALOG_MCP_HOME | No | Directory where the catalog is stored. Defaults to the user data directory. Can also be set with --data-dir. | |
| CATALOG_MCP_TOKEN | No | Bearer token required when serving over Streamable HTTP. Generate it with `catalog-mcp token`. Not needed for stdio transport. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Product catalog built from Amazon Reviews 2023 item metadata (McAuley Lab). Typical flow: search_products -> get_product for details -> compare_products for a side-by-side table. Use find_near_duplicates to spot repeated listings of the same item. Product ids are Amazon parent ASINs (10 characters, e.g. B07XYZ1234). Read catalog://stats for what is loaded.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_productsA | Search the product catalog and return the best matches with id, title, brand, price and rating. Use this first to find product ids. Filters are applied before ranking. |
| get_productA | Get the full record for one product: features, description, category path and spec table. |
| compare_productsA | Compare 2-6 products side by side: price, rating, brand and every spec that at least two of them list. Also names the cheapest, best-rated (adjusted for rating count) and most-reviewed product. |
| find_near_duplicatesA | Find listings that are probably the same item as a product (or a draft title), e.g. one part sold by several sellers. Each candidate carries the evidence: embedding similarity, title word overlap, shared model or part numbers, and a platform check so a PS5 and a Switch edition of one game count as variants, not duplicates. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| write_product_comparison | Write a buyer-friendly comparison of 2-6 catalog products, grounded in their real specs and ratings. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| catalog_stats | What is loaded: dataset, product count per category, embedding model, build time. |
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: search for discovery, get for full detail, compare for side-by-side analysis, and find_near_duplicates for deduplication. There is no meaningful overlap in action or output, so an agent can select the right tool without confusion.
All names follow a consistent snake_case verb_noun pattern: search_products, get_product, compare_products, find_near_duplicates. The pluralization differences accurately reflect whether the tool works on one item or many.
Four tools are well-scoped for a product catalog service focused on discovery, detail retrieval, comparison, and duplicate detection. Each tool earns its place, and the surface is neither bloated nor thin.
The set covers the core read-only catalog workflows: search, retrieve, compare, and deduplicate. Minor gaps such as category browsing or availability/filter metadata exist, but agents can largely work around them using search and get_product.