CLAUDE.md git:20260506.4417968B

Immutable. This exact content never changes and is served at /api/v1/blob/8f38927699419a1a.

# Market Search — Onboarding Recipe for Coding Agents

You (Claude Code, Codex, or any other coding agent) are reading this
because someone just asked you to set up Market Search. Walk the user
through the steps below in order. Pause where this file says PAUSE —
those are the spots that need a human action you can't do yourself.

Tell the user up front: "I'll get you a working setup in about 5
minutes. There are two parts — local tools for me (instant) and a public
URL if you want to use Market Search inside claude.ai web or ChatGPT
custom apps (~3 min for permanent, instant for temporary)."

---

## Step 1 — Verify prerequisites

Run these checks. If anything fails, print the install instruction and stop.

| Check | Command | Fix if missing |
|---|---|---|
| Rust toolchain | `which cargo` | macOS: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`<br/>Linux: same as macOS<br/>Windows: https://rustup.rs |
| git | `which git` | macOS: `xcode-select --install`<br/>Linux: `apt install git` or distro equivalent |

## Step 2 — Install the binary

```bash
cargo install market-search
```

This compiles and installs `market-search` into `~/.cargo/bin/`. It takes 1–3
minutes on first install (Rust is downloading dependencies). Watch for
"Installed package `market-search`" at the end.

Verify: `market-search --version` should print a version string.

## Step 3 — Wire local stdio MCP into the user's coding agent

This is the part that gives YOU (the agent) tool access. Without it,
Market Search only works in the user's claude.ai web/ChatGPT — not in
this Claude Code/Codex session.

### For Claude Code

Read `~/.claude/settings.json`. Find the `mcpServers` block (create it if
it doesn't exist). Add or merge:

```json
{
  "mcpServers": {
    "market-search": {
      "command": "market-search",
      "args": ["mcp"]
    }
  }
}
```

Tell the user: "I added Market Search to your Claude Code config.
**Restart Claude Code** so it picks up the new server, then come back
here and we'll continue."

PAUSE — wait for the user to confirm restart.

After restart, verify in this session by listing tools — you should see
`finance_timeseries`, `finance_odds`, etc. If you don't, the config
didn't take. Check syntax of the JSON file you edited.

### For Codex

Edit Codex's MCP config (path depends on Codex version — search for
`codex.toml` or `~/.config/codex/`). Add an equivalent entry pointing
`command` at `market-search` and `args` at `["mcp"]`.

### For Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
Same JSON shape as Claude Code above.

## Step 4 — Get a public URL for claude.ai web or ChatGPT custom apps

This step is OPTIONAL. Skip if the user only uses Claude Code / Codex /
Claude Desktop locally — Step 3 was sufficient.

If they want Market Search in claude.ai web or ChatGPT, ask:

> "How do you want to connect this? Three options:
> 1. **Temporary URL (instant, 5 sec)** — best for trying it out once.
>    URL dies when you close the terminal.
> 2. **Permanent URL (free, ~3 min setup)** — best for everyday use.
>    Requires a one-time email or Google/GitHub signup at ngrok.com.
> 3. **Self-host (paid, ~10 min setup)** — most secure, your data
>    never leaves your machine. Requires you own a domain (~$10/yr)
>    and a small VPS (~$5/mo). See SELFHOST.md."

### If they pick option 1 (temporary):

Run this in a terminal that the user will keep open:

```bash
market-search mcp share --provider tunnelmole
```

(If `npx` / Node.js isn't installed, fall back to `--provider cloudflare`
which only needs the `cloudflared` binary. On macOS: `brew install
cloudflared`. On Linux: download from
https://github.com/cloudflare/cloudflared/releases/latest .)

The command prints a block with a URL ending in `/mcp`. Copy that URL
and tell the user:

- For claude.ai: Settings → Connectors → Add custom connector → paste URL → Save → toggle on in any chat
- For ChatGPT: Settings → Apps & Connectors → Create → paste URL → Save → toggle on

Tell them: "The URL stays alive while that terminal is open. If you
close it or your machine reboots, you'll need to re-run `market-search mcp share`
and paste the new URL into the connector dialog (it'll be different
each time)."

### If they pick option 2 (permanent ngrok):

First check if ngrok is installed: `which ngrok`. If missing:
- macOS: `brew install ngrok/ngrok/ngrok`
- Linux: download from https://download.ngrok.com (pick your arch)
- Windows: https://download.ngrok.com

Now open ngrok signup in their default browser:
- macOS: `open https://dashboard.ngrok.com/signup`
- Linux: `xdg-open https://dashboard.ngrok.com/signup`
- Windows: `start https://dashboard.ngrok.com/signup`

Tell them:

> "I opened ngrok signup. Sign up with Google, GitHub, or email (the
> OAuth options are fastest — no email verification step). Once you're
> in the dashboard, go to **Your Authtoken** in the left sidebar and
> copy the token. Paste it back to me."

PAUSE — wait for them to paste.

When they paste the token (it'll look like
`2abc...XYZ_ABCdef123ghi456jkl789mno`), reserve their static subdomain.

Ngrok auto-assigns each free account ONE static subdomain on
`*.ngrok-free.dev`. Find it on the dashboard's Domains page (or skip —
the next command will show it). Ask them what they want it named, or
just use the auto-assigned one.

Run:

```bash
market-search mcp share --provider ngrok --authtoken <pasted-token>
```

(Without `--domain`, ngrok uses a random URL. To pin to your reserved
subdomain, re-run with `--domain mysub.ngrok-free.dev`.)

The command prints the same paste-ready block. The URL persists across
restarts as long as you keep your ngrok account and stay under the
free-tier limits (1 GB/mo data, 20K requests/mo — typical Market Search
use is far below this).

Have them paste the URL into claude.ai or ChatGPT as described above.

### If they pick option 3 (self-host):

Open `SELFHOST.md` in this repo and walk them through the architecture.
Tell them: "This is the most secure option but the implementation is in
design phase. Pick option 1 or 2 for now and revisit when SELFHOST.md
moves out of design."

Or: if they want to contribute / pilot, point them at the GitHub issues
labeled `selfhost` and offer to walk them through Phase 0 (frp prototype
on Hetzner with a real Let's Encrypt cert).

## Step 5 — Verify end-to-end

Whichever option they picked, test it:

> "Open a new chat in claude.ai (or ChatGPT). Toggle Market Search on.
> Ask: 'What's SPY trading at right now?'"

Claude/ChatGPT should call the `finance_timeseries` tool and return a
real quote with the current price. If you see "I don't have access to
real-time data" or similar, the connector isn't working — check:

1. The `market-search mcp share` terminal is still running and showing connection
   logs when claude.ai hits it
2. The URL in the connector dialog matches exactly what `market-search mcp share`
   printed (including `/mcp` at the end)
3. For ngrok: `cat ~/.config/ngrok/ngrok.yml` shows your authtoken set

## Common failure modes

- **`cargo install` fails with linker errors**: User probably needs
  build tools. macOS: Xcode CLT (`xcode-select --install`). Linux: `apt
  install build-essential` or distro equivalent.
- **MCP tools don't appear in Claude Code after editing settings.json**:
  They didn't restart Claude Code, OR the JSON file has a syntax error
  (a stray comma, mismatched braces). Read the file back and parse it
  to confirm.
- **`market-search mcp share --provider tunnelmole` errors with "npx not found"**:
  Node.js isn't installed. Either install Node from nodejs.org, or
  switch to `--provider cloudflare` which has no Node dependency.
- **`market-search mcp share --provider cloudflare` errors with "cloudflared not
  found"**: Install cloudflared as in option 1 above.
- **Public URL works in `curl` but not in claude.ai**: Most often the
  user pasted the URL without `/mcp` at the end, or pasted with extra
  whitespace. Re-copy from the terminal block and paste again.

## What you (the agent) should NOT do

- Do not run `market-search mcp share` yourself in a non-blocking shell — it runs
  forever and you'll wedge the session. Tell the USER to run it in a
  terminal they keep open.
- Do not edit `~/.config/ngrok/ngrok.yml` directly. Use `ngrok config
  add-authtoken` (which `market-search mcp share --provider ngrok --authtoken
  <token>` does for you).
- Do not promise that the temporary URL will keep working — it won't.
  Be explicit about persistence in every option.