Přehled MCP nástrojů

BriefGate běží jako MCP server, takže coding agenti mohou řídit sběr podkladů, aniž by opustili svůj kontext. Všech 7 nástrojů odpovídá 1:1 REST endpointům pod https://api.briefgate.dev/v1/. Server nainstalujete přes npm install -g @briefgate/mcp a API klíč nastavíte podle quickstart.md.

define_intake

Založí nový intake a klientovi okamžitě pošle e-mail s odkazem na jeho portál.

Parametry

Parametr	Typ	Povinný	Popis
`project_name`	string	Ano	Název projektu srozumitelný člověku, zobrazuje se v portálu i ve všech e-mailech.
`client.email`	string	Ano	E-mailová adresa klienta.
`client.name`	string	Ne	Jméno klienta pro oslovení.
`client.language`	string	Ne	Jazyk portálu a e-mailů: `cs`, `sk`, `pl`, `de`, `es`, `en`. Když ho vynecháte, použije se výchozí jazyk účtu, případně angličtina.
`email_copy`	object	Ne	Vaše vlastní `invite_subject`, `invite_intro`, `reminder_subject`, `reminder_intro`, které pro tento intake přebijí vestavěný překlad. Zástupné symboly: `{sender}`, `{project}`, `{client}`, `{count}`, `{minutes}`, `{due}` — neznámý se odmítne, nevypíše se doslova.
`items`	array	Ano	Seřazený seznam definic položek. Viz item-types.md.
`chase_schedule`	string	Ne	Jedna z hodnot `default`, `gentle`, `aggressive`, `custom`, `off` (výchozí `default`).
`chase_interval`	integer	Ne	Interval upomínek pro `chase_schedule: "custom"`. Bez něj upomíná custom každé 3 dny. S jiným rozvrhem se odmítne.
`chase_interval_unit`	string	Ne	`minutes`, `hours` nebo `days` (výchozí `days`). Minimum 5 minut, maximum 90 dní.
`respect_quiet_hours`	boolean	Ne	Držet upomínky v okně 8:00–19:00 místního času klienta (výchozí `true`).
`max_reminders`	integer \| string	Ne	Počet upomínek, než se intake označí za zaseknutý a vrátí vám ho (1–1000, výchozí 3, nebo `"unlimited"` pro zrušení stropu).
`chase_at_time`	string	Ne	Místní denní hodina upomínky ve formátu `HH:MM`. Vyžaduje `chase_schedule: "custom"` s intervalem v celých dnech a přebíjí noční klid.
`due_date`	string	Ne	Datum podle ISO 8601. Zobrazuje se v portálu a v předmětu e-mailu.
`send`	boolean	Ne	`false` založí koncept, aniž by klientovi šel e-mail. Odeslat později můžete přes `add_items` nebo `POST /v1/intakes/:id/send`. Výchozí `true`.
`retention`	object	Ne	`{ mode: "days"\|"on_delivery", days?: number, anonymize?: boolean }`. Výchozí: smazat 90 dní po `intake.completed`. U intake s přístupy použijte `mode: "on_delivery"` — obsah zmizí zhruba 24 hodin po vašem volání `get_intake_results`.

Příklad — web restaurace

json

{
  "project_name": "Bella Napoli — Website",
  "client": {
    "email": "[email protected]",
    "name": "Marco Esposito",
    "language": "en"
  },
  "items": [
    {
      "key": "logo",
      "label": "Restaurant logo",
      "help": "SVG or PNG with transparent background, minimum 512px.",
      "type": "image",
      "required": true,
      "constraints": {
        "formats": ["svg", "png"],
        "min_width": 512,
        "transparent_background": true
      }
    },
    {
      "key": "brand_colors",
      "label": "Brand colors",
      "help": "Pick the primary and secondary brand colors.",
      "type": "color_list",
      "required": true
    },
    {
      "key": "hero_copy",
      "label": "Hero tagline",
      "type": "longtext",
      "required": true,
      "constraints": { "max_chars": 400 }
    },
    {
      "key": "has_existing_site",
      "label": "Do you have an existing website?",
      "type": "boolean",
      "required": true
    },
    {
      "key": "existing_site_url",
      "label": "Existing website URL",
      "help": "Only required if you answered Yes above.",
      "type": "url",
      "required": false
    },
    {
      "key": "platform",
      "label": "Preferred platform",
      "type": "select",
      "required": true,
      "options": [
        { "value": "wordpress", "label": "WordPress" },
        { "value": "webflow",   "label": "Webflow" },
        { "value": "custom",    "label": "Custom / I'm not sure" }
      ]
    },
    {
      "key": "cms_password",
      "label": "Admin credentials",
      "help": "Existing CMS admin login (if migrating). Stored encrypted, one-time reveal.",
      "type": "secret",
      "required": false
    },
    {
      "key": "opening_hours",
      "label": "Opening hours",
      "type": "structured",
      "required": true,
      "schema": {
        "type": "object",
        "required": ["mon_fri", "sat", "sun"],
        "properties": {
          "mon_fri": { "type": "string" },
          "sat":     { "type": "string" },
          "sun":     { "type": "string" }
        }
      }
    }
  ],
  "chase_schedule": "default"
}

Odpověď

json

{
  "intake_id": "in_8f3kQmR2",
  "portal_url": "https://p.briefgate.dev/8f3kqmr2?t=Ky7Nn2xQ0pW4vBhLm8sTdRfGjEcAuZoI",
  "status": "sent",
  "items": [
    { "key": "logo",       "status": "pending" },
    { "key": "brand_colors","status": "pending" }
  ]
}

get_intake_status

Vrátí lehký snímek aktuálního stavu intake: které položky jsou hotové, které čekají, a celou historii upomínek. Když potřebujete jen zkontrolovat postup, sáhněte po tomhle místo get_intake_results.

Parametry

Parametr	Typ	Povinný	Popis
`intake_id`	string	Ano	Hodnota `intake_id`, kterou vrátil `define_intake`.

Odpověď

json

{
  "status": "in_progress",
  "due_date": "2024-04-01",
  "client_last_seen": "2024-03-16T14:05:33Z",
  "progress": {
    "submitted": 5,
    "total": 8,
    "outstanding": 3,
    "percent": 62
  },
  "items": [
    { "key": "logo",             "status": "approved",       "submitted_at": "2024-03-16T10:00:00Z", "label": "Restaurant logo" },
    { "key": "brand_colors",     "status": "approved",       "submitted_at": "2024-03-16T10:05:00Z", "label": "Brand colors" },
    { "key": "hero_copy",        "status": "needs_revision", "submitted_at": "2024-03-16T10:10:00Z", "label": "Hero tagline" },
    { "key": "has_existing_site","status": "approved",       "submitted_at": "2024-03-16T10:15:00Z", "label": "Do you have an existing website?" },
    { "key": "existing_site_url","status": "approved",       "submitted_at": "2024-03-16T10:15:00Z", "label": "Existing website URL" },
    { "key": "platform",         "status": "approved",       "submitted_at": "2024-03-16T10:20:00Z", "label": "Preferred platform" },
    { "key": "cms_password",     "status": "pending",        "submitted_at": null,                   "label": "Admin credentials" },
    { "key": "opening_hours",    "status": "pending",        "submitted_at": null,                   "label": "Opening hours" }
  ],
  "chases": [
    { "channel": "email", "sent_at": "2024-03-17T09:00:00Z", "status": "sent",      "attempt_no": 1 },
    { "channel": "email", "sent_at": "2024-03-20T09:00:00Z", "status": "sent",      "attempt_no": 2 },
    { "channel": "email", "sent_at": null,                   "status": "scheduled", "attempt_no": 3 }
  ]
}

Stavy položek

Stav	Význam
`pending`	Klient dosud neodeslal.
`submitted`	Nahráno nebo vyplněno; čeká na kontrolu agentem nebo na automatické schválení.
`needs_revision`	Agent si vyžádal opravu přes `request_revision`.
`approved`	Přijato (buď výslovně, nebo automaticky po 72 hodinách).

get_intake_results

Vrátí otypovaný obsah všech schválených (nebo všech odeslaných) položek. Použijte po dokončení intake, nebo průběžně s only_new: true, jak se položky schvalují.

Parametry

Parametr	Typ	Povinný	Popis
`intake_id`	string	Ano	Intake, ze kterého se výsledky berou.
`only_new`	boolean	Ne	S `true` vrátí jen položky schválené od posledního volání. Hodí se na průběžné zpracování.
`include_pending`	boolean	Ne	S `true` vrátí i položky ve stavu `submitted`, které ještě nejsou schválené.

Odpověď

json

{
  "intake_id": "in_8f3kQmR2",
  "status": "completed",
  "results": {
    "logo": {
      "url": "https://files.briefgate.dev/in_8f3kQmR2/logo.png?token=sig_abc&expires=1710615600",
      "filename": "bella-napoli-logo.png",
      "mime": "image/png",
      "width": 1024,
      "height": 512,
      "size": 48210
    },
    "brand_colors": ["#1B2A4A", "#E8E2D9", "#C8382E"],
    "hero_copy": "Since 1987, handcrafted Neapolitan pizza in the heart of the city. Come hungry, leave happy.",
    "has_existing_site": true,
    "existing_site_url": "https://old.bellanapoli.com",
    "platform": "wordpress",
    "cms_password": {
      "value": "admin:s3cr3tP@ssw0rd",
      "one_time": true,
      "first_reveal": true,
      "expires_at": "2024-04-15T10:22:00Z"
    },
    "opening_hours": {
      "mon_fri": "12:00-22:00",
      "sat": "12:00-23:00",
      "sun": "13:00-21:00"
    }
  }
}

Poznámky ke konkrétním typům:

Obrázky a soubory — url je podepsaná adresa s platností 24 hodin. Stáhněte si soubor včas, nebo si vyžádejte výsledky znovu a dostanete čerstvou adresu.
Přístupy — pole value obsahuje dešifrovaný text jen při prvním volání (first_reveal: true). Při všech dalších už tam není. Uložte si hodnotu okamžitě. Automaticky propadá po 30 dnech. API klíč musí mít scope secrets:read nebo admin.

request_revision

Označí položku jako needs_revision a pošle klientovi e-mail s vysvětlením, co je potřeba opravit. Na straně klienta se položka vrátí do pending a kolečko začne znovu.

Parametry

Parametr	Typ	Povinný	Popis
`intake_id`	string	Ano	Intake, ve kterém položka je.
`item_key`	string	Ano	Hodnota `key` položky k opravě (například `"logo"`).
`note`	string	Ano	Vysvětlení, které dostane klient. Buďte konkrétní.

Příklad

json

{
  "intake_id": "in_8f3kQmR2",
  "item_key": "logo",
  "note": "The logo appears to be exported at 320px. Please re-export at a minimum of 512px on the shortest side, ideally as an SVG vector file."
}

Odpověď

json

{
  "intake_id": "in_8f3kQmR2",
  "item_key": "logo",
  "status": "needs_revision",
  "client_notified": true
}

Klientovi přijde e-mail s vaší poznámkou a v portálu se mu daná položka zvýrazní. Po opětovném odeslání se položka vrátí do stavu submitted a 72hodinová lhůta pro automatické schválení začne běžet znovu.

send_chase

Ručně odešle upomínku mimo automatický rozvrh. Hodí se na eskalaci k SMS poté, co se e-maily odrazily, nebo na osobní pobídnutí před termínem.

Parametry

Parametr	Typ	Povinný	Popis
`intake_id`	string	Ano	Intake, který se má upomenout.
`channel`	string	Ne	`"email"` nebo `"sms"`. Výchozí je `"email"`. SMS vyžaduje telefonní číslo na účtu nebo u klienta.

Příklad

json

{
  "intake_id": "in_8f3kQmR2",
  "channel": "sms"
}

Odpověď

json

{
  "intake_id": "in_8f3kQmR2",
  "channel": "sms",
  "sent_at": "2024-03-22T08:15:00Z"
}

Kdy tenhle nástroj použít

Termín je zítra a klient na automatické e-maily nereagoval.
E-mail se odrazil (uvidíte to v poli chases z get_intake_status) a chcete zkusit SMS.
Klient po celé sérii automatických e-mailů mlčí a chcete eskalovat na SMS.

list_intakes

Vrátí stránkovaný seznam intake, volitelně filtrovaný podle stavu nebo e-mailu klienta. Hodí se na stavbu dashboardů nebo na kontrolu, který projekt potřebuje pozornost.

Parametry

Parametr	Typ	Povinný	Popis
`status`	string	Ne	Filtr podle stavu intake: `draft`, `sent`, `in_progress`, `completed`, `archived`.
`client_email`	string	Ne	Filtr na intake konkrétního klienta.
`limit`	integer	Ne	Počet výsledků na stránku (výchozí 20, maximum 100).
`offset`	integer	Ne	Posun pro stránkování (výchozí 0).

Odpověď

json

{
  "total": 47,
  "intakes": [
    {
      "id": "in_8f3kQmR2",
      "projectName": "Bella Napoli — Website",
      "clientEmail": "[email protected]",
      "status": "in_progress",
      "createdAt": "2024-03-15T10:22:00Z"
    },
    {
      "id": "in_4p2nWxY7",
      "projectName": "Green Leaf Cafe — Rebrand",
      "clientEmail": "[email protected]",
      "status": "completed",
      "createdAt": "2024-03-10T09:00:00Z"
    }
  ]
}

add_items

Přidá nové položky do už odeslaného intake. Klientovi přijde upozornění, že něco přibylo. Použijte, když se rozsah rozroste poté, co je intake živý.

Parametry

Parametr	Typ	Povinný	Popis
`intake_id`	string	Ano	Intake, který se rozšiřuje.
`items`	array	Ano	Pole definic položek ve stejném formátu jako u `define_intake`.

Příklad — doplnění požadavku na favicon po odeslání intake

json

{
  "intake_id": "in_8f3kQmR2",
  "items": [
    {
      "key": "favicon",
      "label": "Favicon",
      "help": "A square icon at least 32x32px, ideally 512x512px. Used in browser tabs and bookmarks.",
      "type": "image",
      "required": true,
      "constraints": {
        "formats": ["png", "svg"],
        "min_width": 32,
        "min_height": 32
      }
    }
  ]
}

Odpověď

json

{
  "intake_id": "in_8f3kQmR2",
  "items_added": [
    { "key": "favicon", "status": "pending" }
  ]
}

Nová položka se klientovi v portálu objeví okamžitě.

Idempotence

Kvůli síťové chybě se define_intake může zavolat dvakrát, což by klientovi poslalo dva e-maily a založilo dva intake. MCP balíček si sám odvodí stabilní idempotenční klíč z project_name, client.email a hashe pole items — opakované volání se stejnými argumenty vrátí původní odpověď a druhý intake nevznikne.

Při přímém volání REST API pošlete hlavičku Idempotency-Key:

bash

curl -X POST https://api.briefgate.dev/v1/intakes \
  -H "Authorization: Bearer bg_live_xxxxx" \
  -H "Idempotency-Key: bella-napoli-2024-01" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Když už klíč jednou viděl, vrátí BriefGate původní odpověď beze změny (HTTP 200, ne 201). Klíče propadají po 24 hodinách.

Testovací režim

API klíče s prefixem bg_test_ zapnou sandbox:

E-maily jdou k sandbox providerovi (uvidíte je v dashboardu pod Test Inbox) a na skutečné adresy se nikdy nedoručí.
SMS se tiše zahodí.
Webhooky se na váš nastavený endpoint spouštějí normálně, takže si handler otestujete celý.
Nahrané soubory se přijmou a dočasně uloží, po 7 dnech se ale smažou.

Před nasazením do produkce přepněte na klíč bg_live_.

Ukázka volání nástroje v Claude Code

Když Claude Code zavolá nástroj BriefGate, vypadá to pod kapotou takhle:

json

{
  "type": "tool_use",
  "id": "toolu_01XyzAbc",
  "name": "briefgate__define_intake",
  "input": {
    "project_name": "Bella Napoli — Website",
    "client": {
      "email": "[email protected]",
      "name": "Marco Esposito",
      "language": "en"
    },
    "items": [
      {
        "key": "logo",
        "label": "Restaurant logo",
        "type": "image",
        "required": true,
        "constraints": {
          "formats": ["svg", "png"],
          "min_width": 512
        }
      }
    ],
    "chase_schedule": "default"
  }
}

Název nástroje nese prefix podle jména MCP serveru (briefgate__). Serializaci do JSON i přenos si Claude Code obstará sám — vy jen přirozeným jazykem popíšete, co potřebujete, a volání sestaví agent.