Simple Stickers API & MCP Dokumentace

🔑

Autentizace

REST API i MCP server používají Bearer token autentizaci přes klíč API.

Typ tokenu	Doba životnosti	Jak získat
`ss_<40 hex chars>` — API klíč	Dlouhodobý — platný až do odvolání	Vygenerujte v Nastavení účtu → Záložka API

🔧 Generování klíče API

1 Otevřete Simple Stickers a klikněte na svůj avatar v horním pravém rohu
2 Přejděte na Nastavení účtu → Záložka API
3 Klikněte na Vygenerovat klíč API, volitelně mu dejte název
4
Okamžitě zkopírujte klíč — je zobrazen pouze jednou
Klíč začíná na ss_ následovaný 40 hexadecimálními znaky.

📤 Použití tokenu

Přidejte token do každého požadavku jako Bearer Authorization header:

Authorization: Bearer ss_a1b2c3d4e5f6...

Klíče API jsou vázány na uživatele, který je vytvořil. Všechny datové operace vrací pouze data tohoto uživatele.

📡

REST API

🌐 Koncový bod

POST https://www.simplestickers.app/api/agent
Content-Type: application/json
Authorization: Bearer <token>

📨 Tělo požadavku

Všechny akce sdílejí stejnou obálku JSON:

{
  "action": "<action_name>",
  "<param>": "<value>"
}

📬 Odpovědi

200 OK Úspěch — JSON data v těle
4xx / 5xx Chyba — {"error": "message"}

📁

Projekty

list_projects

Vrátí všechny projekty patřící ověřenému uživateli.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_projects"}'

Odpověď: pole objektů {"id","name","created_at"}.

find_project

Vyhledávání s ignorováním rozlišování velkých a malých písmen a částečným názvem. Vrátí pole odpovídajících projektů.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"find_project","name":"My Work"}'

Parametr	Typ	Povinný
`name`	string	Ano

create_project

Vytvoří nový projekt. Vrátí vytvořený objekt projektu.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"create_project","name":"Q3 Campaign"}'

Parametr	Typ	Povinný
`name`	string	Ano

rename_project

Přejmenuje existující projekt.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"rename_project","project_id":"<uuid>","name":"New Name"}'

Parametr	Typ	Povinný
`project_id`	string (UUID)	Ano
`name`	string	Ano

delete_project

Smaže projekt a všechny jeho úkoly (kaskádově). Vrátí {"success":true}.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"delete_project","project_id":"<uuid>"}'

⚠️ Nevratné. Všechny úkoly v projektu jsou trvale smazány.

📝

Úkoly

list_tasks

Vrátí úkoly v projektu seřazené podle pozice. Volitelně filtrované podle stavu.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_tasks","project_id":"<uuid>"}'

# Filtrovat podle stavu:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

Parametr	Typ	Povinný	Popis
`project_id`	string (UUID)	Ano
`status`	string	Ne	Filtrovat podle hodnoty stavu (viz tabulka níže)

get_task

Vrátí jeden úkol podle ID, včetně project_id.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"get_task","task_id":"<uuid>"}'

create_task

Vytvoří nový úkol v projektu. Vrátí vytvořený objekt úkolu.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_task",
    "project_id": "<uuid>",
    "text": "Write unit tests",
    "priority": true,
    "color": "yellow",
    "deadline": "2026-06-30",
    "notes": "## Context\n\n- Cover happy path\n- Cover edge cases"
  }'

Parametr	Typ	Povinný	Výchozí
`project_id`	string (UUID)	Ano
`text`	string	Ano
`status`	string	Ne	`backlog`
`notes`	string (Markdown)	Ne	`null`
`priority`	boolean	Ne	`false`
`color`	string \| null	Ne	`null` (bílá)
`deadline`	string (YYYY-MM-DD) \| null	Ne	`null`

update_task

Aktualizuje jedno nebo více polí existujícího úkolu. Musí být zadáno alespoň jedno volitelné pole.

# Přesunout úkol na in_progress:
curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<uuid>","status":"in_progress"}'

# Aktualizovat více polí najednou:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parametr	Typ	Povinný
`task_id`	string (UUID)	Ano
`text`	string	Ne
`status`	string	Ne
`notes`	string (Markdown) \| null	Ne
`priority`	boolean	Ne
`color`	string \| null	Ne
`deadline`	string (YYYY-MM-DD) \| null	Ne

delete_task

Trvale smaže úkol. Vrátí {"success":true}.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"delete_task","task_id":"<uuid>"}'

📋 Hodnoty výčtu

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (bílá)

deadline

Řetězec YYYY-MM-DD, nebo null pro vymazání.

priority

true = vysoká priorita
false = normální

📄

Poznámky k úkolům (Markdown)

Poznámky k úkolům jsou uloženy a přenášeny jako prosté Markdown řetězce. Frontend je vykresluje přes react-markdown. Vždy zapisujte a čtěte Markdown — ne HTML.

Syntax	Výsledek
`text`	Tučný
`text`	Kurzíva
`~~text~~`	~~Přeškrtnutý~~
`## Heading`	Nadpis H2
`### Heading`	Nadpis H3
`- item`	Seznam s odrážkami
`1. item`	Číslovaný seznam
`code`	Řádkový kód
```\ncode\n```	Blok kódu
`> text`	Blokový citát
`[text](url)`	Hypertextový odkaz

📋 Příklad poznámky v create_task

"notes": "## Task overview\n\n- Requirement 1\n- Requirement 2\n\n**Important:** deadline is Friday\n\n[Design brief](https://example.com/brief)"

Staré poznámky: Poznámky uložené před migrací na Markdown mohou obsahovat HTML. Frontend je automaticky konvertuje při zobrazení. Při čtení přes API mohou staré poznámky vracet HTML řetězce — vždy zapisujte Markdown, buďte tolerantní při čtení.

⚙️

Nastavení

get_column_settings

Vrátí nastavení viditelnosti sloupců Kanban uživatele.

curl -s -X POST https://www.simplestickers.app/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"get_column_settings"}'

Příklad odpovědi:

{
  "columns": {
    "backlog":     true,
    "in_progress": true,
    "review":      false,
    "testing":     false,
    "done":        true
  }
}

columns je null pokud uživatel není vlastní viditelnost sloupců (platí všechny výchozí hodnoty).

❌

Referenční chyby

HTTP status	Hodnota `error`	Meaning
401	`Unauthorized`	Chybějící nebo neplatný token
400	`Missing <param>`	Povinný parametr není poskytnut
400	`Unknown action`	Název akce není rozpoznán
403	`Key management requires JWT authentication`	Pokus spravovat klíče s tokenem API klíče
500	liší se	Neočekávaná chyba serveru

🤖

Integrace MCP

Co je MCP?

MCP (Model Context Protocol) je standard, který umožňuje AI klientům (Claude Code, Claude Desktop, Cursor…) připojit se k externím nástrojům. Na rozdíl od REST API se server MCP popisuje sám — klient si vyžádá, které nástroje existují, a poté je volá přímo bez znalosti adres URL nebo formátů požadavků.

✅ Používejte MCP když…

• Chcete, aby Claude spravoval vaše úkoly konverzačně
• Potřebujete, aby AI sama objevila dostupné operace
• Upřednostňujete plug-and-play integraci s Claude Code / Claude Desktop
• Chcete používat přirozený jazyk místo psaní curl příkazů

📡 Používejte REST API když…

• Vytváříte vlastní automatizační skripty nebo CI pipeline
• Potřebujete jemnou kontrolu nad HTTP požadavky
• Integrujete se se systémy, které nepodporují MCP
• Chcete programově zpracovat odpovědi

🛠️ Dostupné MCP nástroje

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings

list_tasks

get_task

create_task

update_task

delete_task

Koncový bod MCP: https://www.simplestickers.app/api/mcp (Streamovatelný HTTP přenos, JSON-RPC 2.0)

💻

Nastavení Claude Code

Claude Code nativně podporuje HTTP MCP servery — není potřeba proxy. Nakonfigurujte jednou globálně nebo pro každý projekt.

🌐 Globální konfigurace — ~/.claude/mcp.json

Platí pro všechny relace Claude Code na vašem počítači:

{
  "mcpServers": {
    "simplestickers": {
      "type": "http",
      "url": "https://www.simplestickers.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_your_api_key_here"
      }
    }
  }
}

📁 Konfigurace pro projekt — .mcp.json v kořenovém adresáři projektu

Stejný formát jako globální konfigurace — platí pouze při práci v tomto adresáři:

{
  "mcpServers": {
    "simplestickers": {
      "type": "http",
      "url": "https://www.simplestickers.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_your_api_key_here"
      }
    }
  }
}

✅ Ověřit připojení

Po uložení konfigurace otevřete Claude Code a zadejte:

/mcp

Měli byste vidět simplestickers uvedené se všemi 11 dostupnými nástroji. Pokud se server zobrazuje jako odpojený, klikněte na Reconnect.

🖥️

Nastavení Claude Desktop

Důležité: Claude Desktop přímo nepodporuje HTTP MCP přenos — používá pouze stdio přenos. Použijte mcp-remote jako proxy. Příznak -y automaticky schválí instalaci npm bez interaktivních výzev.

🍎 macOS

Konfigurační soubor: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "simplestickers": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.simplestickers.app/api/mcp",
        "--header",
        "Authorization: Bearer ss_your_api_key_here"
      ]
    }
  }
}

🪟 Windows

Konfigurační soubor: %APPDATA%\Claude\claude_desktop_config.json

(typicky C:\Users\<name>\AppData\Roaming\Claude\claude_desktop_config.json)

Na Windows spouští Claude Desktop procesy bez kontextu shell, takže npx musí být zabaleno v cmd /c:

{
  "mcpServers": {
    "simplestickers": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://www.simplestickers.app/api/mcp",
        "--header",
        "Authorization: Bearer ss_your_api_key_here"
      ]
    }
  }
}

Po úpravě konfigurace restartujte Claude Desktop. Měli byste vidět nástroje Simple Stickers v seznamu nástrojů uvnitř konverzace.

💡

Rychlé příklady

📡 Kompletní REST workflow — vyhledat projekt → vytvořit úkol → aktualizovat stav

BASE="https://www.simplestickers.app/api/agent"
TOKEN="ss_your_api_key_here"

# 1. Find the project
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"find_project","name":"My Work"}'

# 2. Create a task (use project_id from step 1)
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_task",
    "project_id": "<project-uuid>",
    "text": "Write unit tests",
    "priority": true,
    "color": "yellow"
  }'

# 3. Move task to in_progress (use task id from step 2)
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_task",
    "task_id": "<task-uuid>",
    "status": "in_progress"
  }'

# 4. Mark as done
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Workflow MCP v Claude Code

Jakmile je server MCP konfigurován, můžete s Claude mluvit přirozeně:

Vy: Find my "Website Redesign" project and list all tasks that are in_progress

Vy: Create a high-priority task "Fix mobile navigation" with a deadline of 2026-06-30 and add notes with a checklist

Vy: Move all tasks named "Deploy *" to done status

Claude automaticky používá MCP nástroje na základě vašich pokynů v přirozeném jazyce.

🔬 Testovat MCP server přímo s curl

BASE="https://www.simplestickers.app/api/mcp"
TOKEN="ss_your_api_key_here"

# Handshake (no auth needed)
curl -s -X POST $BASE \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

# List tools
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

# Call a tool
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_projects","arguments":{}},"id":3}'