Content
# TuZonaMarket Shopping Agent Toolkit
Turn TuZonaMarket into a safe, personal-use shopping tool for AI agents. Agents can understand a shopper's preferences and delivery zone, browse the zone-specific catalog, build and review a cart, and prepare checkout for people who want to delegate time-consuming grocery shopping. It never places orders or processes payments.
## Get started
You do not need to clone the repository or install Node.js.
**Linux or macOS**
```bash
curl -fsSL https://raw.githubusercontent.com/AlexR1712/tuzonamarket-agent-toolkit/main/scripts/install.sh | sh
```
**Windows (PowerShell)**
```powershell
irm https://raw.githubusercontent.com/AlexR1712/tuzonamarket-agent-toolkit/main/scripts/install.ps1 | iex
```
The installers detect your platform and download the latest binary. They install it to `~/.local/bin` on Linux/macOS or `%LOCALAPPDATA%\Programs\TuZonaMarket\bin` on Windows. Add that directory to `PATH` if prompted.
For the first sign-in, set your credentials and use the CLI:
```bash
export TUZONA_EMAIL='you@example.com'
export TUZONA_PASSWORD='your-password'
tuzona zones
tuzona search arroz --zone carabobo --limit 5
```
`tuzona zones` lists the available delivery zones. Use the zone that serves the user's delivery address, then keep that same zone for catalog, cart, coupon, and checkout commands. `--zone` accepts a numeric ID, slug, or name, for example `2`, `carabobo`, or `lara`.
Run `tuzona login` before account actions such as cart, addresses, orders, or tracking. The CLI stores a restricted local JWT, not your password, at `~/.local/state/tuzonamarket/session.json` on Linux/macOS or the equivalent Windows app-data directory. Later commands reuse that session without requiring the environment variables. Set the variables again only when the session expires and the CLI needs to sign in again. Use `TUZONA_SESSION_FILE` or `--session-file` to choose another session-file location, and run `tuzona logout` to remove it. Run `tuzona --help` for all commands. Cart, address, and coupon changes require `--yes`.
## Install the agent skill
Install the included shopping workflow in a compatible AI agent with [skills.sh](https://skills.sh/docs):
```bash
npx skills add AlexR1712/tuzonamarket-agent-toolkit --skill tuzonamarket
```
The skill teaches an agent how to install and use the CLI, select the delivery zone, search the Spanish catalog, learn shopping preferences, and manage a cart safely.
## Connect an agent
| Setting | Value |
| --- | --- |
| MCP URL | `https://tuzonamarket-mcp.blockshift.workers.dev/mcp` |
| Transport | Streamable HTTP |
| Authentication | `Authorization: Bearer ${TUZONA_MCP_BEARER}` |
Create the secret in the agent's secure environment:
```bash
export TUZONA_MCP_BEARER="$(printf '%s' "$TUZONA_EMAIL:$TUZONA_PASSWORD" | base64 | tr -d '\n')"
```
`TUZONA_MCP_BEARER` is Base64-encoded credentials, not encryption. Do not commit or share it. The included skill contains the full agent-facing MCP workflow, including session handling, mutation confirmation, and error recovery.
## Safety
This project excludes `POST /usuario/orden/zona/{zoneId}/pagina/{page}/registrar`. It can prepare checkout, but it cannot buy. Always review and confirm cart or address changes before running them.
## Disclaimer
This is an unofficial, personal-use tool. It is not affiliated with, endorsed by, sponsored by, or approved by TuZonaMarket. TuZonaMarket names and marks belong to their respective owners.
Use this software at your own risk. It is provided without warranties, and the authors and contributors are not responsible for any loss, damage, account action, incorrect purchase preparation, or other consequence arising from its use, to the maximum extent permitted by applicable law. Verify all information and actions in TuZonaMarket before proceeding.
## Development
Use Bun 1.3.14+ to modify the project:
```bash
bun install --frozen-lockfile
bun test
bun run test:mcp
bun run typecheck
bun run build:cli
```
`bun run deploy` deploys the Worker and requires Cloudflare credentials. A `v*` tag builds the binaries and creates a GitHub Release.
## More
- [OpenAPI specification](openapi.yaml)
- [Skill for future agents](skills/tuzonamarket/SKILL.md)
- [Releases](https://github.com/AlexR1712/tuzonamarket-agent-toolkit/releases)
- [MIT License](LICENSE)
