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"]).

---

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.