Dokumentacja Simple Stickers API & MCP

🔑

Uwierzytelnianie

Zarówno REST API, jak i serwer MCP używają uwierzytelniania tokenu Bearer za pośrednictwem klucza API.

Typ tokenu	Okres ważności	Jak uzyskać
`ss_<40 hex chars>` — klucz API	Długotrwały — ważny aż do odwołania	Wygeneruj w Ustawieniach konta → Zakładka API

🔧 Generowanie klucza API

1 Otwórz Simple Stickers i kliknij swoją awatarkę w prawym górnym rogu
2 Przejdź do Ustawień konta → Zakładka API
3 Kliknij Wygeneruj klucz API, opcjonalnie nadaj mu nazwę
4
Skopiuj klucz natychmiast — jest wyświetlany tylko raz
Klucz zaczyna się od ss_ i zawiera 40 znaków szesnastkowych.

📤 Używanie tokenu

Przekaż token w każdym żądaniu jako nagłówek autoryzacji Bearer:

Authorization: Bearer ss_a1b2c3d4e5f6...

Klucze API są ograniczone do użytkownika, który je utworzył. Wszystkie operacje na danych zwracają tylko dane tego użytkownika.

📡

REST API

🌐 Punkt końcowy

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

📨 Treść żądania

Wszystkie akcje używają tej samej koperty JSON:

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

📬 Odpowiedzi

200 OK Sukces — dane JSON w treści
4xx / 5xx Błąd — {"error": "message"}

📁

Projekty

list_projects

Zwraca wszystkie projekty należące do uwierzytelnionego użytkownika.

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

Odpowiedź: tablica obiektów {"id","name","created_at"}.

find_project

Wyszukiwanie częściowego nazwy projektu bez uwzględniania wielkości liter. Zwraca tablicę pasujących projektów.

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	Wymagane
`name`	string	Tak

create_project

Tworzy nowy projekt. Zwraca stworzony obiekt 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	Wymagane
`name`	string	Tak

rename_project

Zmienia nazwę istniejącego projektu.

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	Wymagane
`project_id`	string (UUID)	Tak
`name`	string	Tak

delete_project

Usuwa projekt i wszystkie jego zadania (kaskadowo). Zwraca {"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>"}'

⚠️ Nieodwracalne. Wszystkie zadania w projekcie są na stałe usuwane.

📝

Zadania

list_tasks

Zwraca zadania w projekcie, uporządkowane według pozycji. Opcjonalnie filtrowane po statusie.

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>"}'

# Filtrowanie po statusie:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

Parametr	Typ	Wymagane	Opis
`project_id`	string (UUID)	Tak
`status`	string	Nie	Filtruj po wartości statusu (zobacz wyliczenie poniżej)

get_task

Zwraca pojedyncze zadanie po ID, łącznie z 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

Tworzy nowe zadanie w projekcie. Zwraca stworzony obiekt zadania.

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	Wymagane	Domyślnie
`project_id`	string (UUID)	Tak
`text`	string	Tak
`status`	string	Nie	`backlog`
`notes`	string (Markdown)	Nie	`null`
`priority`	boolean	Nie	`false`
`color`	string \| null	Nie	`null` (białe)
`deadline`	string (YYYY-MM-DD) \| null	Nie	`null`

update_task

Aktualizuje jedno lub więcej pól istniejącego zadania. Wymagane jest co najmniej jedno pole opcjonalne.

# Przenieś zadanie do 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"}'

# Aktualizuj wiele pól jednocześnie:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parametr	Typ	Wymagane
`task_id`	string (UUID)	Tak
`text`	string	Nie
`status`	string	Nie
`notes`	string (Markdown) \| null	Nie
`priority`	boolean	Nie
`color`	string \| null	Nie
`deadline`	string (YYYY-MM-DD) \| null	Nie

delete_task

Trwale usuwa zadanie. Zwraca {"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>"}'

📋 Wartości wyliczenia

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (białe)

deadline

YYYY-MM-DD string, lub null aby wyczyścić.

priority

true = wysoki priorytet
false = normalny

📄

Notatki zadań (Markdown)

Notatki zadań są przechowywane i transmitowane jako zwykłe ciągi Markdown. Frontend je renderuje za pośrednictwem react-markdown. Zawsze pisz i czytaj Markdown — nie HTML.

Składnia	Wynik
`text`	Pogrubienie
`text`	Kursywa
`~~text~~`	~~Przekreślenie~~
`## Heading`	Nagłówek H2
`### Heading`	Nagłówek H3
`- item`	Lista wypunktowana
`1. item`	Lista numerowana
`code`	Kod wbudowany
```\ncode\n```	Blok kodu
`> text`	Cytat blokowy
`[text](url)`	Hiperłącze

📋 Przykładowa notatka w 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)"

Notatki z przeszłości: Notatki zapisane przed migracją Markdown mogą zawierać HTML. Frontend automatycznie je konwertuje na wyświetlaniu. Podczas czytania przez API, stare notatki mogą zwrócić ciągi HTML — zawsze pisz Markdown, bądź tolerancyjny podczas czytania.

⚙️

Ustawienia

get_column_settings

Zwraca ustawienia widoczności kolumn Kanban użytkownika.

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

Przykładowa odpowiedź:

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

columns to null jeśli użytkownik nie dostosował widoczności kolumn (obowiązują wszystkie domyślne).

❌

Dokumentacja błędów

Status HTTP	Wartość `error`	Znaczenie
401	`Unauthorized`	Token brakuje lub jest nieprawidłowy
400	`Missing <param>`	Wymagany parametr nie został podany
400	`Unknown action`	Nazwa akcji nie została rozpoznana
403	`Key management requires JWT authentication`	Próba zarządzania kluczami za pomocą tokenu klucza API
500	zmienia się	Nieoczekiwany błąd serwera

🤖

Integracja MCP

Co to jest MCP?

MCP (Model Context Protocol) to standard, który pozwala klientom AI (Claude Code, Claude Desktop, Cursor…) łączyć się z zewnętrznymi narzędziami. W przeciwieństwie do REST API, serwer MCP się opisuje — klient pyta, które narzędzia istnieją, a następnie je bezpośrednio wywołuje bez konieczności znania adresów URL lub formatów żądań.

✅ Używaj MCP gdy…

• Chcesz, aby Claude zarządzał Twoimi zadaniami konwersacyjnie
• Potrzebujesz, aby AI samodzielnie odkrywała dostępne operacje
• Preferujesz integrację plug-and-play z Claude Code / Claude Desktop
• Chcesz używać języka naturalnego zamiast pisać komendy curl

📡 Używaj REST API gdy…

• Budujesz własne skrypty automatyzacji lub potoki CI
• Potrzebujesz precyzyjnej kontroli nad żądaniami HTTP
• Integrujesz się z systemami, które nie obsługują MCP
• Chcesz przetwarzać odpowiedzi programowo

🛠️ Dostępne narzędzia MCP

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings

list_tasks

get_task

create_task

update_task

delete_task

Punkt końcowy MCP: https://www.simplestickers.app/api/mcp (Transport HTTP przesyłowy, JSON-RPC 2.0)

💻

Konfiguracja Claude Code

Claude Code natywnie obsługuje serwery MCP HTTP — nie potrzebny jest żaden proxy. Skonfiguruj raz globalnie lub dla każdego projektu.

🌐 Konfiguracja globalna — ~/.claude/mcp.json

Dotyczy wszystkich sesji Claude Code na Twojej maszynie:

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

📁 Konfiguracja dla projektu — .mcp.json w katalogu głównym

Ten sam format co konfiguracja globalna — dotyczy tylko pracy w tym katalogu:

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

✅ Weryfikacja połączenia

Po zapisaniu konfiguracji otwórz Claude Code i wpisz:

/mcp

Powinieneś zobaczyć simplestickers na liście z wszystkimi 11 dostępnymi narzędziami. Jeśli serwer jest wyświetlany jako rozłączony, kliknij Reconnect.

🖥️

Konfiguracja Claude Desktop

Ważne: Claude Desktop nie obsługuje bezpośrednio transportu MCP HTTP — używa tylko transportu stdio. Używaj mcp-remote jako proxy. Flaga -y automatycznie zatwierdza instalację npm bez interaktywnych monitów.

🍎 macOS

Plik konfiguracyjny: ~/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

Plik konfiguracyjny: %APPDATA%\Claude\claude_desktop_config.json

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

Na Windows, Claude Desktop uruchamia procesy bez kontekstu powłoki, dlatego npx musi być opakowany w 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 edytowaniu konfiguracji zrestartuj Claude Desktop. Powinieneś zobaczyć narzędzia Simple Stickers w liście narzędzi wewnątrz rozmowy.

💡

Szybkie przykłady

📡 Kompletny przepływ REST — znajdź projekt → utwórz zadanie → zaktualizuj status

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

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

# 2. Utwórz zadanie (użyj project_id z kroku 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. Przenieś zadanie do in_progress (użyj task id z kroku 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. Oznacz jako gotowe
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Przepływ MCP w Claude Code

Gdy serwer MCP jest skonfigurowany, możesz rozmawiać z Claude naturalnie:

Ty: Znajdź mój projekt "Website Redesign" i wyświetl wszystkie zadania, które są w_progress

Ty: Utwórz zadanie o wysokim priorytecie "Fix mobile navigation" z terminem 2026-06-30 i dodaj notatki z listą kontrolną

Ty: Przenieś wszystkie zadania nazwane "Deploy *" do statusu gotowe

Claude automatycznie używa narzędzi MCP na podstawie Twoich instrukcji w języku naturalnym.

🔬 Testuj serwer MCP bezpośrednio za pomocą curl

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

# Uścisk dłoni (nie potrzebny token)
curl -s -X POST $BASE \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

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

# Wywołaj narzędzie
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}'