# Connect your AI agent to Yojimbo

You are an AI coding/assistant agent (Claude Code, Cursor, Cline, Windsurf, or any
MCP-capable client). This file is a runbook: **follow the steps in order** to
connect yourself to Yojimbo - an AI trading terminal for the Russian market
(MOEX) and crypto - so you can run market analytics and build persistent visual
boards for the user.

Read the whole file first, then execute. Some steps are yours to run; some need
the human (installing the desktop app, logging in, connecting a broker) - when
you reach those, ask the user to do them and wait.

---

## 1. What you'll be able to do (and what you can't)

Once connected, you get these tools over MCP:

- **Analytics** - `analyze_instrument`, `multi_timeframe_analysis`, `screen_sector`,
  `get_levels`, `analyze_order_book`, sector overviews, trade-journal stats, ...
- **Canvas (live stream)** - analytics auto-render as rich widgets in a separate
  Yojimbo window as you work.
- **Boards (persistent)** - `create_board`, `pin_to_board`, `add_note`,
  `add_live_chart`: collect the conclusions of a session onto a named, durable
  board the user can reopen later. Use these to leave the user a clean summary
  of what you found, with your reasoning (notes) next to the charts.
- **DSL authoring** - `read_skill` then `create_strategy` / `create_indicator` /
  `create_task`: write custom trading strategies (YAML), indicators (Python), and
  scheduled tasks. **Always `read_skill('writing-strategies'|'writing-indicators'|'writing-tasks')`
  first** - it's the authoritative contract + examples. Everything you create is a
  **draft** (tasks are created **paused**); the user reviews and saves/activates
  it in the terminal. You cannot save or activate on the user's behalf.

**You cannot trade.** There is no `open_position` tool by design. To propose a
trade, render a `setup_trade` widget - the user clicks "Open position" in the UI
to execute. This is a hard safety boundary; don't try to work around it.

---

## 2. Preflight - is Yojimbo running?

The MCP server lives at `http://localhost:8124/mcp/` and only exists while the
Yojimbo desktop app (or its Docker stack) is running on this machine. Check:

```bash
curl -s -o /dev/null -w "%{http_code}" http://localhost:8124/health
```

- Got `200` -> Yojimbo is up. **Go to step 4 (configure).**
- Connection refused / no response -> it's not installed or not running.
  **Go to step 3 (install).**

---

## 3. Install & sign in (human steps - guide the user)

Detect the user's OS and give them the matching install path. **You must not
install the app, enter tokens, or log in yourself** - these involve a GUI and
secrets and are the user's to do. Guide them, then wait.

### Windows - native desktop app

1. **Download the installer:**
   `https://github.com/yojimbo-hq/releases-v2/releases/latest/download/Yojimbo-Setup-x64.exe`
2. **Run it.** Unsigned build -> a Windows SmartScreen "Unknown Publisher" warning
   is expected: "More info -> Run anyway".

### macOS / Linux - Docker

The native macOS app isn't out yet; on macOS and Linux, Yojimbo runs as a local
Docker stack (opens in the browser, identical to the native app).

1. **Install Docker** if the user doesn't have it - the prerequisite differs per OS:
   - **macOS** -> Docker Desktop or OrbStack: `https://www.docker.com/products/docker-desktop/`
   - **Linux** -> Docker Engine + the compose plugin: `https://docs.docker.com/engine/install/`
   - **Windows (if they'd rather use Docker than the .exe)** -> Docker Desktop with
     the WSL2 backend, then run the command below inside a WSL shell.
2. **Start Yojimbo** - one command, identical on every OS:
   ```bash
   curl -fsSL https://yojimbo.dev/install.sh | sh
   ```
   It checks Docker, pulls the compose stack, starts it, and installs a `yojimbo`
   helper CLI (`yojimbo start|stop|logs|update|open|uninstall`).
3. Open `http://localhost:3000`.

### Then, on any OS

1. **Launch / open** Yojimbo and **sign in** with Telegram.
2. **Choose a market and connect a broker** in onboarding - T-Invest (MOEX) or
   Bybit need an API token; **Crypto mode** is analytics-only and needs no token.
3. Tell the user to say when they see the main terminal screen, then **re-run the
   preflight in step 2** to confirm the MCP server is up.

---

## 4. Configure your MCP client (your step)

Add Yojimbo to your MCP config. The transport is the same for every client; only
the file path differs. Detect which client you are and edit the right file:

| Client | Config file |
|--------|-------------|
| Claude Code | `~/.claude.json` (global) or `./.mcp.json` (project) |
| Cursor | `~/.cursor/mcp.json` |
| Cline / Windsurf | the client's MCP settings JSON |

Add this entry:

```json
{
  "mcpServers": {
    "yojimbo": {
      "transport": { "type": "http", "url": "http://localhost:8124/mcp/" }
    }
  }
}
```

Then reconnect MCP (Claude Code: `/mcp`; others: restart the client).

---

## 5. Verify

Call `create_board` with a title like `"Test"`. You should get back a
`board_id` + `board_url` (in the desktop app a board window opens). If that
works, you're connected - tell the user you're ready.

A good first real task: *"Analyse SBER on the daily timeframe, and if there's a
setup, build me a board with the chart, the key levels, and your reasoning."* -
you'd call `analyze_instrument`, then `create_board` + `pin_to_board` + `add_note`.

---

## Security & notes

- The MCP server binds to `127.0.0.1` only - not reachable from other machines.
- No auth token on `/mcp/` - there's nothing destructive there (no trading), so
  it's safe on loopback.
- Trading endpoints live on a separate authenticated path you never touch; only
  the Yojimbo UI can execute trades, on a human click.
- Everything you author (strategies/indicators) is a **draft**, tasks are
  **paused** - the user is always the one who commits and activates.