# Agents overview and quick start

> Install the Haszno skill, CLI, and MCP server; run a first read-only command against the hosted demo in under five minutes.

## The three tools

Haszno ships three packages for AI agents and automation scripts. The CLI and the MCP server call the same HTTP API with the same kind of credentials (an API key sent in the `x-api-key` header, or HTTP Basic), but they read them from different places: the CLI only from its `--api-key` / `--api-url` flags and environment variables (`HASZNO_API_KEY`, `HASZNO_API_URL`, `HASZNO_BASIC`), the MCP server from those environment variables or, if none is set, from `~/.config/haszno/config.json`. See [CLI configuration](cli.md#configuration).

| Package | What it is | Best for |
|---|---|---|
| **MCP server** (`haszno-mcp`) | An MCP stdio server: 51 tools registered as `haszno_*` | Interactive Claude Code or Claude Desktop sessions — tools appear natively, no shell invocation needed |
| **CLI** (`haszno`) | A Node.js command-line program | Shell scripts, cron jobs, Codex, Cursor terminal, headless agents |
| **Skill** (`haszno-skill`) | Guidance files for Claude Code: safety rules, workflow recipes, tool and command references | Claude Code can load it when the conversation is about Haszno; teaches the agent to use the MCP and CLI |

The skill is not a separate API surface. It loads in Claude Code and directs the agent to use the MCP when connected and fall back to the CLI otherwise.

## Which one do I need?

| Your context | Use |
|---|---|
| Interactive Claude Code session | MCP server + skill |
| Claude Desktop | MCP server |
| Any MCP-compatible client (Cursor, Zed, …) | MCP server |
| Shell script or cron job | CLI |
| Codex terminal | CLI |
| You want all three set up at once | One-step installer |

## Install

### One-step installer (recommended)

Installs the CLI, MCP server, and skill in one command. Requires Node.js 20 or later, `git`, and `npm`.

```bash
curl -fsSL https://raw.githubusercontent.com/haszno-labs/haszno-skill/main/install.sh | bash
```

What it does:

1. Clones all three repos into `~/.haszno/` (with `gh repo clone` when the GitHub CLI is logged in, otherwise `git clone` over HTTPS)
2. Builds the CLI and MCP server (`npm install && npm run build`)
3. Links the `haszno` binary globally with `npm link` (falls back to a `~/.local/bin/haszno` symlink)
4. Registers the MCP server with Claude Code: `claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js` (skipped if `claude` is not on your PATH or `haszno` is already registered)
5. Copies skill files to `~/.claude/skills/haszno/`

The installer does not set up credentials. At the end it prints the two `export` lines (`HASZNO_API_URL`, `HASZNO_API_KEY`) that the CLI needs.

> [!NOTE]
> The packages are not published on npm. Use the installer above or the GitHub install paths shown on the [CLI reference](cli.md) and [MCP server](mcp.md) pages.

### Local source override

```bash
HASZNO_SRC_DIR=~/Documents/medusa-shops/haszno-labs bash install.sh
```

### Uninstall

```bash
bash ~/.haszno/haszno-skill/install.sh --uninstall
```

Removes `~/.haszno/`, the `~/.local/bin/haszno` symlink, the `npm link` (best effort), `~/.claude/skills/haszno/`, and the MCP registration. It does not remove `~/.config/haszno/config.json`.

## What works without credentials

The hosted demo at `https://haszno.com` answers a set of public read-only endpoints without authentication, with synthetic data. Other endpoints return `401`.

> [!NOTE]
> All prices, SKUs, and market data on the public demo are synthetic. Only the `/api/settings` and `/api/impact` responses carry a `"demo": true` field. See [Authentication](authentication.md) for how to get access to real data.

| Capability | No credentials (demo) | Needs credentials |
|---|---|---|
| List categories | Yes | — |
| List products with pricing and market comparisons | Yes | — |
| Dashboard stats, profit impact, pricing settings | Yes | — |
| View orders and proposals | Yes (empty lists) | — |
| Browse network suppliers or search the partner catalogue | — | Yes |
| View rules, automation status, product ideas | — | Yes |
| Update settings or prices | — | Yes |
| Approve or reject proposals | — | Yes |
| Push products to a webshop | — | Yes |
| Create or run automation rules | — | Yes |

## Safety model

Read tools and list commands are always safe — call them freely without asking.

Every command that changes data requires an explicit confirmation:

- **In the MCP server**: pass `"confirm": true` in the tool call arguments. Without it, write tools return a preview description and do not call the API.
- **In the CLI**: pass `--yes`. Without it, proposal, rule, import-push and peer commands print a preview and exit without changing anything; account, product, feed, idea and order write commands ask for confirmation at an interactive prompt. `haszno import add` is the exception: it writes without confirmation. See [Write commands and confirmation](cli.md#write-confirmation).

Before any bulk write (approving proposals, running rules), check the automation kill switch:

```bash
haszno rules automation --json
# or via MCP: haszno_automation_get
```

If `paused` is `true`, do not approve proposals or run rules — report to the user first.

If an approved proposal batch looks wrong, call `haszno proposals rollback --batch <batchId>` or the `haszno_proposals_rollback` MCP tool before doing anything else. The `batchId` is returned by the approve command.

## 5-minute quick start

### Step 1 — install

```bash
curl -fsSL https://raw.githubusercontent.com/haszno-labs/haszno-skill/main/install.sh | bash
```

Restart your shell (or open a new terminal) after installation.

### Step 2 — verify connectivity

```bash
haszno account ping
```

No credentials needed. Expected output:

```
API: OK elérhető
```

### Step 3 — run a first read command

Print the dashboard summary — no credentials needed:

```bash
haszno account stats --json
```

To use your own data later, run `haszno login` once: it saves the API URL and key to `~/.config/haszno/config.json`, which both the CLI and the MCP server read. In scripts, export `HASZNO_API_KEY` instead (see [CLI configuration](cli.md#configuration)).

### Step 4 — ask Claude

With the MCP server registered, open a Claude Code session and try:

> "List the top Haszno categories and show me the product count for each."

> "What are my current pricing settings?"

> "What is the current pricing impact summary?"

Claude Code can load the skill on its own when you mention Haszno, dropshipping, or related topics.

## Machine-readable docs

### llms.txt

A structured index of every documentation page:

```
https://docs.haszno.com/llms.txt
```

This follows the [llms.txt](https://llmstxt.org/) convention. AI agents that consume documentation before answering questions should fetch this file first to discover what pages exist.

### llms-full.txt

A single file concatenating the full Markdown content of every page:

```
https://docs.haszno.com/llms-full.txt
```

Useful for agents that need the complete documentation in one HTTP request.

### Markdown mirrors

Every HTML page has a plain-Markdown mirror at the same path with a `.md` suffix:

```
https://docs.haszno.com/en/agents.md
https://docs.haszno.com/en/cli.md
https://docs.haszno.com/en/mcp.md
https://docs.haszno.com/en/skill.md
```

Each HTML page also announces its mirror via an HTTP `Link:` response header:

```
Link: </en/agents.md>; rel="alternate"; type="text/markdown"
```

### Copy page

Each page has a **Copy page** button that writes the page's Markdown to the clipboard. Use it in browser-embedded agents to ingest the current page without rendering HTML.

## See also

- [CLI reference](cli.md) — full command reference with all flags and examples
- [MCP server](mcp.md) — full tool reference with input and output schemas
- [Agent skill](skill.md) — what the skill teaches, safety rules, workflow recipes
- [Authentication](authentication.md) — how to get API access beyond the demo