# Connect Markovo — Agent Playbook

You are setting up Markovo for a user. Markovo converts files (PDF, DOCX, PPTX, XLSX, images, audio, video, EPUB, CSV, text) and explicitly authorized public HTTPS pages into clean Markdown bundles. Follow these steps in order and keep the user informed briefly at each step.

> This file is the quick playbook for agents. The full interactive guide — with per-method walkthroughs — lives at `https://markovo.net/docs` (the Connect page). Fetch it if this file does not cover the user's situation.

## Step 1 — Choose the connection

Pick the first method the user's client supports, and tell the user why you chose it. When in doubt: **remote MCP for AI assistants, REST API for software, CLI for humans in a terminal.**

| # | Method | Best for | Needs API key |
|---|--------|----------|---------------|
| 1 | Remote MCP | AI assistants (Claude, ChatGPT, Cursor…) | No — OAuth sign-in |
| 2 | Local stdio MCP | Agents that must upload local files | Yes |
| 3 | CLI | Terminals, scripts, CI | Yes |
| 4 | REST API | Products and backends | Yes |

1. **Remote MCP (recommended for AI assistants)** — URL `https://markovo.net/mcp`, transport Streamable HTTP, auth OAuth 2.1 Authorization Code + PKCE. If the user's MCP client supports remote servers with OAuth, register this URL. The client opens a normal sign-in plus a consent screen; no API key is created or pasted. Remote MCP can convert public URLs and inspect owned jobs, usage, and billing guidance; it cannot upload local files.
2. **Local stdio MCP (local files for agents)** — install the client package, then configure an MCP server entry:
   ```json
   {
     "mcpServers": {
       "markovo": {
         "command": "markovo-mcp",
         "env": {
           "MARKOVO_API_KEY": "<api key>",
           "MARKOVO_MCP_ROOT": "/path/to/dedicated/project"
         }
       }
     }
   }
   ```
3. **CLI (terminal / scripts)** — `pip install "https://markovo.net/downloads/markovo-0.1.1-py3-none-any.whl#sha256=aae71e1fff133fca3a9e6c17a1fd3b1080a0bd5a05ea075eef7267491bea079d"`, then `export MARKOVO_API_KEY="mk_live_..."` and run `markovo convert file.pdf --out runs/out --max-credits 30`.
4. **REST API (products and backends)** — `POST https://markovo.net/v1/convert` with `Authorization: Bearer mk_live_...`, multipart `file` fields and a mandatory `max_credits` ceiling. Poll `GET /v1/jobs/{id}`, download via `GET /v1/jobs/{id}/download?format=md|zip`.

## Step 2 — Account and API key (skip for remote MCP OAuth)

1. Ask the user to open `https://markovo.net/app`, sign in (Google, GitHub, or email), and create an API key under **API keys** (`/app#developer`). The key is shown once, starts with `mk_live_`, and carries the `markovo:convert` scope.
2. Have the user paste the key where you tell them — an env var (`MARKOVO_API_KEY`), the MCP `env` block, or a server secret. Never ask them to put it in browser code or commit it.
3. Free accounts include 25 monthly Credits and one active API key; paid plans add capacity and retention.

## Step 3 — Verify

- Remote MCP: confirm the OAuth flow completed and list the exposed tools.
- API key: `curl -H "Authorization: Bearer $MARKOVO_API_KEY" https://markovo.net/v1/capabilities` must return 200.
- CLI: `markovo doctor --json` must report ok.

Report success with one line: method used, what the user can now ask you to convert, and where results land.

## Reference (fetch when needed)

- Full connection guide (Connect page): `https://markovo.net/docs`
- Capability status: `https://markovo.net/capabilities.md`
- Full API contract: `https://markovo.net/openapi.json`
- Copy-ready developer guide: `https://markovo.net/developer.md`
- Machine-readable site index: `https://markovo.net/llms.txt`
- Remote MCP guide: `https://markovo.net/docs/mcp`

Every conversion needs an explicit Credit ceiling (`max_credits` / `max_credit_units`); failed or cancelled jobs charge zero. Always obtain a user-approved maximum before submitting work.