Skip to main content
Glama
darrengruber

fsastore-mcp

by darrengruber
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

fsastore-mcp

An MCP server that lets an AI agent (Claude or Codex) search FSA‑eligible products on fsastore.com and add them to your shopping cart, then place the order only when you explicitly confirm the total.

  • Runs with one uvx command — no clone, no manual install.

  • No password is ever stored. You paste a short‑lived access token from your browser via a one‑click bookmarklet.

  • Search → cart is verified against the live store API.

1. Add it to your agent

You need uv installed (brew install uv). uvx then builds and runs the server straight from the repo.

This repo is private, so uvx clones it with your Git credentials. Run gh auth login (or have SSH set up) first. If you use SSH, swap the URL for git+ssh://git@github.com/darrengruber/fsastore-mcp.

Claude Code (CLI)

claude mcp add fsastore -- \
  uvx --from git+https://github.com/darrengruber/fsastore-mcp fsastore-mcp

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "fsastore": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/darrengruber/fsastore-mcp", "fsastore-mcp"]
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.fsastore]
command = "uvx"
args = ["--from", "git+https://github.com/darrengruber/fsastore-mcp", "fsastore-mcp"]

Restart the agent after editing config. To grab the latest code later, add --refresh to the uvx args (e.g. ["--refresh", "--from", "git+...", "fsastore-mcp"]).

Related MCP server: Instacart MCP Server

2. Install the token bookmarklet (one minute, one time)

The store sits behind bot protection, so the server can't log in for you. Instead you hand it a fresh token with one click. Set this up once:

  1. Copy this entire line (it starts with javascript:):

    javascript:(function(){var m=document.cookie.match(/scapi_access_token=([^;]+)/);if(!m){alert('No token yet — open your Cart once, then click again.');return;}var t=decodeURIComponent(m[1]);navigator.clipboard.writeText(t).then(function(){alert('FSA token copied ('+t.length+' chars). Paste it to your agent.');},function(){window.prompt('Copy this token:',t);});})();

  2. Create a bookmark and paste that line as its URL:

    • Chrome / Edge: ⭐ in the address bar → Edit → set Name to FSA token and replace the URL with the copied line → Save. (Or: menu → Bookmarks → Bookmark Manager → ⋮ → Add new bookmark.)

    • Firefox: Bookmarks menu → Manage Bookmarks → right‑click a folder → Add Bookmark → Name FSA token, Location = the copied line.

    • Safari: add any bookmark, then Edit Bookmarks and paste the line as its address.

That's it — you now have an FSA token button.

3. Use it

  1. Log in at https://www.fsastore.com in your browser.

  2. Click your FSA token bookmark. It copies a token to your clipboard. (If it says "No token yet", open your Cart page once and click again.)

  3. In Claude/Codex, tell the agent to set the access token, and paste it:

    Use set_access_token with: eyJ... (your copied token)

  4. Now just ask, e.g.:

    Search fsastore for sunscreen and add two of the cheapest eligible one to my cart.

When the token expires (~30 min), any tool replies login_required — just click the bookmark and set_access_token again.

Tip: ask the agent to run auth_status. It reports whether your token is for your account or a Guest session. If it says Guest, log in first, then re‑run the bookmark — otherwise you'll be editing a guest cart.

Tools the agent can call

Tool

Purpose

set_access_token

Cache a token copied by the bookmarklet

auth_status

Whether a valid token is cached, who it's for, time left

search_products

Search; FSA‑eligible only by default, each tier‑labeled

add_to_cart

Add a product (master products auto‑resolve to a buyable variant)

view_cart

Show cart contents and total

get_checkout_summary

Show the total to confirm

confirm_order

Place the order — only if the live total matches the one you pass

The server never places an order except through confirm_order with a matching total.

Run it directly (optional)

# from a clone
uvx --from . fsastore-mcp
# or
uv run fsastore-mcp

Run as an HTTP server / container (optional)

For local use the stdio transport above is all you need. To run it persistently behind an MCP gateway, set FSASTORE_MCP_TRANSPORT=http (host/port via FSASTORE_MCP_HOST / FSASTORE_MCP_PORT). A Dockerfile is included:

docker build -t fsastore-mcp .
docker run --rm -p 9130:9130 -v fsastore-state:/state fsastore-mcp

State (the cached token, active basket id) lives in the process, so serve HTTP with a single replica. The token is written under XDG_STATE_HOME (/state in the image) — mount a writable volume there.

Develop

uv sync
uv run pytest        # tests
uv run ruff check .  # lint
uv run ty check src  # types

Design notes and decisions: CONTEXT.md and docs/adr/.

Status

Verified against the live store API: product search + FSA‑eligibility, cart reuse, master→variant resolution, add‑to‑cart. Checkout submission (confirm_order) is wired and gated but not yet exercised end‑to‑end — a saved shipping/payment method may need to be applied to the cart first. The Confirm Gate prevents accidental orders regardless.

Available Tools

7 tools
add_to_cartB

Add a product (by SFCC product id) to the cart and return the updated cart.

ParametersJSON Schema
NameRequiredDescriptionDefault
pidYes
quantityNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries full behavioral burden. It only states it adds a product and returns the cart, but does not disclose idempotency, side effects (e.g., overwriting existing items), authentication requirements, or error handling (e.g., invalid product id). This is insufficient for a mutation tool.

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 a single sentence that is clear and to the point. It avoids unnecessary words. Could be slightly improved by separating the return behavior, but it remains concise and front-loaded.

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

Completeness2/5

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

Given the tool has two parameters and an output schema (unknown content), the description is minimal. It does not explain what happens if the product is out of stock, if the cart is empty, or any constraints. No error handling or assumptions are stated, making it incomplete for a transactional context.

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?

The description provides context for 'pid' as 'SFCC product id', which adds value beyond the schema (which has no description). However, 'quantity' is left unexplained (default 1), and the schema has 0% description coverage. Overall, the description partially compensates but leaves gaps.

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 ('Add'), the resource ('a product to the cart'), and that it returns the updated cart. It specifically mentions 'by SFCC product id' which is the key identifier. This distinguishes it from siblings like view_cart (view) and confirm_order (confirms).

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?

There is no explicit guidance on when to use this tool versus alternatives. For example, it does not mention that it should be used for adding items to the cart, while view_cart is for checking current contents. No context about prerequisites (e.g., quantity limitations) or post-conditions.

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

auth_statusA

Report whether a valid access token is cached and for how long.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior2/5

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

No annotations are provided, so the description bears full burden. It only states the reporting function without disclosing additional behaviors such as whether it makes network calls, requires permissions, or has side effects. This leaves gaps for an agent to infer safety and performance characteristics.

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?

Description is a single concise sentence that directly communicates the tool's purpose without any extraneous information.

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 has no parameters and an output schema (not shown), the description is complete. It covers the essential behavior needed for an agent to decide when to invoke this tool.

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 has zero parameters, so the description adds no parameter-specific information. According to guidelines, the baseline for 0 parameters is 4, which is appropriate here.

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 reports whether a valid access token is cached and the duration, using a specific verb and resource. It effectively distinguishes from sibling tools like set_access_token or search_products, which have different purposes.

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 implies usage for checking authentication status, which is contextually clear given sibling tools. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions.

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

confirm_orderB

Place the order (the Confirm Gate). Submits only if the live total matches expected_total.

ParametersJSON Schema
NameRequiredDescriptionDefault
expected_totalYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. Discloses the matching condition but omits other behaviors like idempotency, side effects (inventory deduction), or error scenarios.

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?

Two sentences front-loaded with primary purpose and key condition. No wasted words.

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?

Adequate for a simple tool with one parameter and output schema, but lacks context on prerequisite steps (e.g., calling get_checkout_summary) and behavior on mismatch.

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

Parameters2/5

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

Schema coverage is 0%, but description adds minimal meaning by implying 'expected_total' is the total to match against. Does not fully compensate for undocumented parameter purpose.

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 verb ('Place the order') and resource ('the Confirm Gate'), distinguishing from sibling tools like add_to_cart or get_checkout_summary by specifying this is the final confirmation step.

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?

Implies usage context by stating it submits only if totals match, but does not explicitly mention when not to use or suggest alternatives like get_checkout_summary for verification.

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

get_checkout_summaryA

Show the order total to review before confirming. Pass this total to confirm_order.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

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

No annotations provided, but description implies a read-only operation without side effects. Lacks explicit mention of read-only nature, but sufficient for a no-param 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?

Two concise sentences with no fluff. Every sentence adds value.

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?

For a parameterless tool with output schema, the description fully explains its purpose and relation to confirm_order.

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?

No parameters exist, so parametric details are unnecessary. Schema coverage is 100%, baseline 4 is appropriate.

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 the tool shows the order total for review before confirming, distinguishing it from siblings like confirm_order and view_cart.

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

Usage Guidelines5/5

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

Explicitly tells when to use (before confirming) and what to do next (pass total to confirm_order), providing clear guidance.

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

search_productsA

Search products. Returns FSA-eligible items by default, each tagged with its tier.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
eligible_onlyNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

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

No annotations exist, so description carries full burden. It discloses default filtering (eligible_only) and tier tagging, but omits details like pagination or sorting. Adequate for basic understanding.

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?

Two sentences with no redundancy; front-loaded with action and default behavior. Every word 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?

Has output schema, so return values are covered. Lacks details on pagination or filtering modes, but defaults and tier tagging are explained. Reasonably complete for a search tool.

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 coverage is 0%, so description must compensate. It adds meaning to eligible_only (FSA-eligible) but does not explain query or limit. Partial improvement over bare 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 the tool searches products and specifies default behavior (FSA-eligible items) with tier tagging, effectively distinguishing it from sibling tools focused on cart, auth, etc.

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 implies usage context (product search with default filter) but does not explicitly state when to use or avoid this tool. Sibling tools have distinct functions, so sufficient for typical use.

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

set_access_tokenB

Cache a freshly pasted scapi_access_token (from the FSA-token bookmarklet).

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The term 'cache' is vague about persistence, overwrite behavior, or side effects. The description lacks details on what the tool does beyond storing the token, and does not mention error conditions or return value structure.

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?

A single sentence that is front-loaded and covers the essential purpose. Every word is justified, and there is no verbosity or redundancy.

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 values do not need description. However, the tool lacks behavioral context (e.g., idempotency, error handling). Given the low complexity (one required parameter), the description is minimally adequate but leaves gaps in usage context.

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

Parameters2/5

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

Schema description coverage is 0%, requiring the description to compensate. The description calls the token a 'freshly pasted scapi_access_token' but does not explain format, constraints, or how to obtain it. For a single parameter, more semantic guidance would be beneficial.

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 verb 'cache' and the resource 'scapi_access_token', specifying its origin from the FSA-token bookmarklet. While it doesn't explicitly distinguish from siblings, the sibling tools are unrelated (cart, auth, etc.), making the purpose sufficiently clear.

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 usage after pasting from a specific bookmarklet, but it does not explicitly state when to use this tool versus alternatives, nor does it provide any conditions or prerequisites. No explicit when-not or alternative guidance is given.

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

view_cartA

Show the current cart contents and total.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

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

The description implies a read-only operation, but lacks details like authentication requirements or behavior with an empty cart. No annotations exist to supplement this.

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?

One sentence that is front-loaded with the core purpose; no wasted words.

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 description is complete for a simple view tool with no parameters and an output schema to define return values. Could mention authentication context but not essential.

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?

No parameters exist, and the schema coverage is 100%. The description implicitly notes no input is needed, which is sufficient.

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 shows cart contents and total, which is specific and distinguishes it from sibling tools like add_to_cart or confirm_order.

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?

No explicit guidance on when to use this tool versus alternatives, but the simplicity of the tool makes it obvious; minimal guidance is acceptable but not provided.

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. 7 tool updatesv0.1.0
    • First observedadd_to_cart
    • First observedauth_status
    • First observedconfirm_order
    • First observedget_checkout_summary
    • First observedsearch_products
    • First observedset_access_token
    • First observedview_cart
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.9/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: auth, product search, cart manipulation, and order confirmation. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun snake_case pattern (e.g., add_to_cart, search_products, view_cart), making it easy to predict tool names.

Tool Count5/5

With 7 tools, the set is concise yet covers the essential workflow of an FSA store checkout. No unnecessary tools or missing core actions for the apparent scope.

Completeness4/5

Covers the main flow (auth, search, cart add/view, checkout summary, confirm) but lacks cart modification tools like remove or update quantity, which agents might need.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers