Bowmark MCP · Bowmark

{
  "name": "get_library",
  "description": "**Use this whenever a task touches a live website.** It answers, definitively and cheaply, whether Bowmark can already DO the thing: look up current prices, check real availability or stock, search a site, get a quote or a fare, drive a configurator, start a booking, or pull anything that only exists behind a form, a filter, or a login.\n\n**Use this for Bowmark questions too.** Before answering how to write or run a Bowmark script, what the sandbox supports, or how to start when no site or task is named, call it with the caller's words. The matching entry gives the platform guidance; guessing from general programming knowledge does not.\n\n**Checking is cheap, so check.** One read-only call, no site is touched, and an unrecognized query returns a one-line index instead of an error, so the check never dead-ends and never costs you an attempt. If nothing fits, you have lost one cheap call and can use your normal approach.\n\nWhat comes back is the callable **function library** you write against: the runtime globals (`log`) PLUS, for each capability your query named, its namespace, TypeScript types, functions, and worked examples. Everything listed is real and callable. The language rules and how to run a script are on the `run` tool description.\n\nPass `query` — what you want to DO (`\"flights\"`, `\"price a GPU\"`) or, if you have one in mind, the COMPANY or site (`\"Kayak\"`, `\"newegg.com\"`). If the caller gave only a URL, use its hostname as the query — the query parameters identify a page state, not the company. A phrase in the user's own words is fine; it is matched against the whole library. **You get what you asked about and nothing else.** If nothing matches — or you send no query — you get instead a one-line index: pick whichever entry fits and CALL AGAIN with its name to get the types and examples you need to write a script.\n\n**Every response is bounded, and it says so when it is a slice.** A broad query can match more than one response carries; when that happens the answer opens with a partial-answer line naming what it left out. **Read it before concluding anything** — absence from a sliced list means nothing, and the fix is one narrower query (a single task, or a single company by name), which always returns that entry in full. Only an answer that does NOT say it is a slice supports the conclusion that a task is uncovered.\n\n**Two tiers come back.** CAPABILITIES (`bowmark.flights.search(...)`) are the default and usually what you want: one call fans out across several sites, dedupes, ranks, and routes around a site that's failing. PROVIDERS (`bowmark.providers.kayak.search(...)`) are the individual sites, callable directly — they appear only when your query NAMED a company, or when the capability has just one provider behind it. A direct provider call gets that site's own raw shape and no failover, so prefer the capability unless you specifically want that site.\n\nLoop: call `get_library` → write a JS script against the `bowmark` global → send it to `run`.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Optional, but pass one — it decides how much detail comes back. What the user wants to do, in their words (\"flights\", \"price a GPU\", \"book a table\", \"check stock\"), or a company/site if they named one (\"Kayak\", \"newegg.com\"). If they supplied only a URL, pass its hostname rather than the full URL or its query parameters. A rough guess is always safe: a value that matches nothing returns the one-line index rather than an error, and so does omitting it."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "run",
  "description": "**Executes the task on the real websites** (the search, the price check, the availability lookup, the configurator, the booking flow) and returns what came back. Runs a script you authored against the `get_library` vocabulary, on the live sites, and returns `{ ok, result, logs, error, ms }`. Call `get_library` FIRST — it gives the exact function names, argument shapes, and return types; this description is the LANGUAGE + how-to (get_library is just the vocabulary).\n\nTHE LANGUAGE — plain async JavaScript:\n• `bowmark` is a ready global (no import). Call capabilities off it — `await bowmark.<capability>.<method>(...)` — always `await`, they&#39;re async.\n• Individual sites are callable too, at `await bowmark.providers.<provider>.<fn>(...)`. Use one when you specifically want THAT site; otherwise prefer the capability, which fans out across sites and routes around failures.\n• Real control flow: `await`, `if`, loops, array methods (`map`/`filter`/`sort`/`slice`), and `Promise.all` for fan-out.\n• `return` a value to get it back (JSON-serialized). `log(...)` for progress lines.\n• Standard JavaScript built-ins are there (`JSON`, `Math`, `Date`, `RegExp`, `Intl`, `Promise`), plus `URL` and `URLSearchParams` — use them to resolve a relative link against the page it came from and to build query strings. Nothing else from the Web platform exists: no `fetch`, `setTimeout`, `TextEncoder` or `crypto`.\n• `bowmark` is the ONLY I/O — no `fetch`, `process`, filesystem, or `import`/`require`. Write a plain async body, not a wrapping function.\n• Keep scripts small and deterministic — no infinite loops. Runs in a hard sandbox with CPU + memory + wall-clock limits.\n\n**Your own tool-call budget is tighter than you&#39;d guess, and it decides how many calls fit in one script.** Most MCP clients time a single tool call out at around 55 seconds, and ONE ordinary capability call already spends 30-55 seconds of that fanning out to live sites — see COMPOSITION below before calling a second capability in the same script.\n\nSENDING IT: pass the script text as `run({ script })` — `script` is the only argument (there is no `site` argument; the library exposes every capability under `bowmark`). `result` is whatever you returned; `logs` are your `log()` lines in order; on a throw/timeout `ok:false` and `error` is set.\n\nCHECK `status` BEFORE `ok`. It is `ok` | `error` | `partial` | `needs_user`.\n• `partial` means the script RAN and `result` is real and usable, but some of what it called never answered — so the result is narrower than what you asked for. `ok` is still `true`; this is not a failure. `incomplete.summary` says what happened in one sentence, `incomplete.failures` names each call that threw and what the site said, and `incomplete.degraded` names each call that answered while reporting its OWN results thin. You MUST say so when you present the result: name what was missed, and do not describe it as complete, exhaustive, or &#39;all&#39; of anything. A `partial` you report as whole is a wrong answer, not a slightly smaller right one.\n• Before you conclude a `partial` is final, check `incomplete.failures[].fixable`. `fixable: true` means YOUR ARGUMENT was rejected, not the site — the error text names what that function actually takes, so re-read it in `get_library`, fix the argument and run again; that recovers the whole answer. For any other failure re-running usually returns the same thing.\n• `needs_user` means a site needs the USER signed in — it is NOT a failure and NOT something you can fix by editing the script. `needs` lists the sites; `meta.handoff.url` is a single-use link that expires (`meta.handoff.expiresAt`). Give the user that URL, say which sites it covers, and WAIT. When they tell you they&#39;re done, send the SAME script again unchanged. Do NOT retry before then — it will stop at the same place and cost another run. Do NOT try to log in yourself, ask them for a password, or work around it with a different site.\n• Logged-in runs need a Bowmark API key on the connection; if you get `needs_user` saying so, tell the user to add one rather than retrying.\n\nSAVED CREDENTIALS: `savedSecrets` lists every credential the run stored in the user&#39;s Bowmark account, each as `{ name, type, viewUrl }`. An API key a key-making function returns is saved there automatically as `<vendor>_api_key`, and later runs that call that vendor use it with nothing to configure. When `savedSecrets` is present, tell the user what was saved and give them each `viewUrl`, where they can view or manage it.\n\n`trace` is the execution trace — every capability you called and the providers it fanned out to under the hood: `[{ kind:&#39;capability&#39;, capability:&#39;flights&#39;, method:&#39;search&#39;, ms }, { kind:&#39;provider&#39;, capability:&#39;flights&#39;, provider:&#39;google_flights&#39;, fn:&#39;search&#39;, results, status, ms }, …]`. The script never visits websites — it calls capabilities that route to providers, and the trace is the receipt.\n\nCOMPOSITION MEANS PARALLEL, NOT SEQUENTIAL. Default to ONE capability call per script — most already spend 30-55 seconds of your own ~55-second tool-call budget on their own, so a second call made AFTER the first routinely never returns before your client gives up, and the script errors with nothing to show for either call. If you genuinely need several, run them TOGETHER inside `Promise.all` — in parallel they cost about what one call costs, not the sum of them — and never call them one after another. To sweep a date range, call the search per date inside `Promise.all` and sort/filter the merged array (each flight result carries its `date`, so you can tell the runs apart). See the `get_library` examples for the exact shape. If even one call will not fit your budget, narrow the query (fewer dates, a single site instead of a fan-out) or split the work across separate turns — do not compose more into one script to make it fit.\n\nSOME capabilities return their rows alongside a `warnings` array — `{ flights, warnings }`, `{ hotels, warnings }`, `{ cars, warnings }`. Others return a bare array. The signature in `get_library` tells you which; go by it rather than assuming. Where there IS a `warnings` array it names any site dropped from the fan-out, and the rows themselves look identical with or without it. Read it, and pass on anything it says rather than quoting a &#39;cheapest&#39; that only ranks the sites that happened to answer. Dropping `warnings` from what you return does not hide it — the run comes back `status: &#39;partial&#39;` regardless, because the runtime counts what your script CALLED, not what it chose to report.\n\nWHEN NO FUNCTION FITS, OR ONE FAILED ON THE SITE ITSELF: `bowmark.browser_agent` hands the task, in plain language, to a hosted AI browser agent. It costs real money per turn, charged to the account, so use it only after `get_library` had nothing for the site or a function&#39;s failure was not `fixable`. `start({ task })` returns at once with an `id` and a `watchUrl`. Give the user that link: they can watch the agent and take over the browser to sign in or clear a check. The agent keeps working between your runs, so in LATER runs call `status(id, { waitMs: 60000 })`; when it is `needs_input`, relay `question` to the user and answer with `send(id, message)`; when it is `idle`, read `result` and call `stop(id)`. Always `stop` a session you are finished with. `get_library({ query: \"browser agent\" })` has the types.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "script": {
        "type": "string",
        "description": "The JavaScript script body to execute (async, against the `bowmark` global). e.g. `const { flights, warnings } = await bowmark.flights.search({from:&#39;SFO&#39;,to:&#39;JFK&#39;,depart:&#39;2026-09-01&#39;}); return { best: flights.sort((a,b)=>a.price-b.price)[0], warnings };`"
      }
    },
    "required": [
      "script"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "runId": {
        "type": "string",
        "format": "uuid"
      },
      "ok": {
        "type": "boolean"
      },
      "status": {
        "type": "string",
        "enum": [
          "ok",
          "error",
          "partial",
          "needs_user"
        ]
      },
      "result": {},
      "logs": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "error": {
        "type": [
          "string",
          "null"
        ]
      },
      "ms": {
        "type": "number"
      },
      "needs": {
        "type": "array",
        "items": {}
      },
      "secretNeeds": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "secret": {
              "type": "string"
            },
            "reason": {
              "type": "string",
              "enum": [
                "expired",
                "pending",
                "unavailable"
              ]
            },
            "expiredAt": {
              "type": "string"
            }
          },
          "required": [
            "secret",
            "reason"
          ],
          "additionalProperties": false
        }
      },
      "savedSecrets": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "viewUrl": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "type",
            "viewUrl"
          ],
          "additionalProperties": false
        }
      },
      "savedFiles": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "contentType": {
              "type": "string"
            },
            "bytes": {
              "type": "number"
            },
            "url": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "contentType",
            "bytes",
            "url",
            "expiresAt"
          ],
          "additionalProperties": false
        }
      },
      "incomplete": {},
      "emptyHanded": {},
      "meta": {},
      "notice": {}
    },
    "required": [
      "ok"
    ],
    "additionalProperties": false
  }
}

{
  "name": "report",
  "description": "Record what was missing, wrong, or incomplete so Bowmark can build it. Pass the `runId` returned by `run` when this report is about a run; omit it when `get_library` did not cover the task. This records feedback only and does not retry a run.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "report": {
        "type": "string",
        "minLength": 1,
        "maxLength": 4000,
        "description": "What Bowmark could not do or returned incorrectly."
      },
      "runId": {
        "type": "string",
        "format": "uuid",
        "description": "Optional `runId` returned by `run` for the result you are reporting."
      }
    },
    "required": [
      "report"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "ok": {
        "type": "boolean"
      }
    },
    "required": [
      "ok"
    ],
    "additionalProperties": false
  }
}

{
  "name": "list_secrets",
  "description": "List the stored credentials this account holds, by NAME. Returns name, type, which hosts each may be used against, when it expires and when it was last used — never a value, and no Bowmark endpoint returns one.\n\n**Call this BEFORE `request_secret`.** A secret the user has already set is ready to use; asking for it again sends them to a page for nothing. In a script, refer to one by name: `bowmark.secret('acme_pw')`.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

{
  "name": "request_secret",
  "description": "Create a named, empty slot for a credential and get back a link the user opens to fill it in. They type the value on a Bowmark page and choose how long it lives, from 5 minutes to never. It is encrypted in their own browser before it leaves, so nothing on the way — this connection included — ever sees it.\n\n**Give the user the link. Never ask them to type a password, API key or one-time code to you.** A credential in this conversation is in your context, in the transcript and in the logs.\n\n**Name it for the person, not for your script.** The name you pass is the heading on the page they open and the row they see in their credential list months later, so make it `<site>_<what it is>`: `letterboxd_password`, `stripe_api_key`, `acme_totp_seed`. A run id, a timestamp, a uuid or a bare `password` is refused.\n\nCall `list_secrets` first: if the name already exists and is set, use it instead. `name` is lowercase letters, digits, `_`, `.` and `-`. `hosts` narrows where the value may be used and is worth passing — a secret is refused against any other site.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Lowercase name, `<site>_<what it is>` — `letterboxd_password`, `stripe_api_key`, `acme_totp_seed`. Letters, digits, _ . - only. THE USER READS THIS: it is the heading on the page they open and the row in their credential list months later, so use words, never a run id, a timestamp or a bare `password`."
      },
      "type": {
        "type": "string",
        "enum": [
          "password",
          "username",
          "totpSeed",
          "apiKey",
          "recoveryCodes",
          "cookie",
          "text"
        ],
        "description": "What kind of value the person will be asked for."
      },
      "hosts": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Hosts the value may be used against, e.g. [\"acme.com\"]. Refused elsewhere."
      }
    },
    "required": [
      "name",
      "type"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_secret_link",
  "description": "Return the dashboard link for one stored credential this account holds, so you can answer \"where is my Acme password?\" with somewhere to go. **It returns a URL, never a value** — opening it requires the user to be signed in and to confirm who they are, and only their own browser can read what comes back.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "The stored secret's name, as `list_secrets` shows it."
      }
    },
    "required": [
      "name"
    ],
    "additionalProperties": false
  }
}

{
  "name": "list_connections",
  "description": "List the saved logins this account holds — which site, which account, whether it is still good, and when it was last used. A live one means a script can reach that site's signed-in pages with no sign-in step and usually no browser.\n\nUseful before a task that needs an account: a connection marked `needs_reauth` or `expired` is why a run would pause and ask the user to sign in again. Revoking one is deliberately not a tool — it is the user's to do, at https://bowmark.ai/dashboard/connections.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}