bowmark-mcp 1.0.2 → 2.0.1

package/README.md

@@ -1,8 +1,10 @@
 # bowmark-mcp — Bowmark MCP over stdio (Node)
 
-Bowmark gives agents pre-computed navigation recipes for public websites (skip
-explore-and-discover). The canonical server is hosted, streamable HTTP, no auth
-required: `https://api.bowmark.ai/mcp`.
+Bowmark turns the interaction-gated web into a **callable function library**.
+An agent reads the library (`get_library`), writes a short JavaScript script
+against it, and sends it to `run` — Bowmark executes it on the live sites in a
+sandbox and hands back the result. The canonical server is hosted, streamable
+HTTP, no auth required: `https://api.bowmark.ai/mcp`.
 
 This package is a **thin stdio bridge** to that hosted server, for MCP hosts
 whose client only speaks stdio, in Node-flavored environments. Tool schemas,
@@ -32,23 +34,34 @@ If your host speaks streamable HTTP, skip this bridge and connect directly to
 
 | Var | Meaning |
 |---|---|
-| `BOWMARK_MCP_URL` | Target MCP URL. Default `https://api.bowmark.ai/mcp?s=n` (`?s=n` attributes the install to the npm bridge). Point at `http://localhost:3001/mcp` for a local Bowmark API. |
-| `BOWMARK_API_KEY` | Optional. Forwarded as `X-Bowmark-Key`; a free key (bowmark.ai dashboard) raises the anonymous per-IP daily synthesis cap to your plan budget. |
+| `BOWMARK_MCP_URL` | Target MCP URL. Default `https://api.bowmark.ai/mcp/npm` (the `/npm` destination attributes the install to this bridge). Point at `http://localhost:3001/mcp` for a local Bowmark API. |
+| `BOWMARK_API_KEY` | Optional. Forwarded as `X-Bowmark-Key`; a free key (bowmark.ai dashboard) lifts the anonymous per-IP daily cap to your plan budget. |
 
 ## Design notes (repo-internal)
 
 - **One remote session per request, retried once.** The hosted MCP is
   stateless, so a fresh connection is semantically identical and its cost (one
-  initialize round-trip) is noise next to an `ask` synthesis — and it
+  initialize round-trip) is noise next to a `run` that drives real browsers — and it
   sidesteps long-lived-connection failure modes without reconnect bookkeeping.
   Mirrors `packages/bowmark-mcp/python` (the PyPI bridge) exactly.
+- **The real host's name is relayed upstream.** The api tailors its operating
+  guidance per host and detects the host from `clientInfo` on the handshake —
+  but through a bridge that names the BRIDGE, so every install here would read
+  the platform-neutral text. So the host's own `clientInfo.name` (from OUR stdio
+  handshake) is forwarded as `X-Bowmark-Client` on every proxied request, and the
+  api ranks that above its own handshake. Best-effort: an unknown or missing name
+  simply falls back to the neutral text, never an error.
 - **Pass-through only.** No tool logic lives here; the agent-surfaces sync
   rule in the root CLAUDE.md is unaffected because descriptions/schemas ride
   through from `apps/api/src/routes/mcp.ts`. `callTool` results are returned
   verbatim (content, structuredContent, isError).
-- **`?s=n` source code** is registered in `apps/api/src/mcp-sources.ts` +
-  `mcp-registry/sources.json` (npm stdio bridge channel; the PyPI bridge is
-  `?s=p`).
+- **The `/npm` destination** is registered in
+  `apps/api/src/mcp-destinations.ts` + `mcp-registry/sources.json` (npm stdio
+  bridge channel; the PyPI bridge is `/pypi`). It carries the channel and
+  deliberately pins NO platform, because the relayed `X-Bowmark-Client` above is
+  a better answer than any pin. The old `?s=n` query form still resolves for
+  installs already in the wild. Adding a destination:
+  `.claude/rules/mcp-destinations.md`.
 - **npm ownership verification needs BOTH markers — the registry checks the
   published package.json, not just the README.** The `mcp-name:
   ai.bowmark/bowmark` line above and the `"mcpName": "ai.bowmark/bowmark"`

package/dist/bridge.js

@@ -8,9 +8,9 @@
 // package never needs a re-publish when the api's tools change.
 //
 // Env:
-//   BOWMARK_MCP_URL  Target MCP URL. Default https://api.bowmark.ai/mcp?s=n
-//                    (`?s=n` tags the install source as the npm bridge;
-//                    point at http://localhost:3001/mcp for a local API).
+//   BOWMARK_MCP_URL  Target MCP URL. Default https://api.bowmark.ai/mcp/npm
+//                    (the `/npm` destination attributes the install to this
+//                    bridge; point at http://localhost:3001/mcp for a local API).
 //   BOWMARK_API_KEY  Optional key, forwarded as X-Bowmark-Key. Omit for the
 //                    anonymous tier.
 //
@@ -23,8 +23,8 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-export const DEFAULT_URL = "https://api.bowmark.ai/mcp?s=n";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+export const DEFAULT_URL = "https://api.bowmark.ai/mcp/npm";
 export function targetUrl(env = process.env) {
     return env.BOWMARK_MCP_URL?.trim() || DEFAULT_URL;
 }
@@ -34,11 +34,26 @@ export function authHeaders(env = process.env) {
     const key = env.BOWMARK_API_KEY?.trim();
     return key ? { "X-Bowmark-Key": key } : undefined;
 }
-async function withRemote(fn) {
-    const client = new Client({ name: "bowmark-mcp-bridge", version: "1.0.2" });
-    const headers = authHeaders();
+/** Relay WHICH HOST is really on the other end.
+ *
+ * The hosted MCP tailors its instructions per host (ChatGPT vs a chat app vs a
+ * coding agent), and it detects the host from the `clientInfo` on the
+ * handshake. Through this bridge that signal is destroyed: we open our OWN
+ * session upstream, so the name the api would see is `bowmark-mcp-bridge` and
+ * every install through npm resolves to the platform-neutral text.
+ *
+ * The real host named itself on OUR stdio handshake, so relay that name on
+ * every proxied request. Best-effort: `undefined` before the host has
+ * initialized, and the api treats an unrecognized name the same as none. */
+export function clientHeaders(hostName) {
+    const name = hostName?.trim();
+    return name ? { "X-Bowmark-Client": name } : undefined;
+}
+async function withRemote(fn, hostName) {
+    const client = new Client({ name: "bowmark-mcp-bridge", version: "2.0.1" });
+    const headers = { ...authHeaders(), ...clientHeaders(hostName) };
     const transport = new StreamableHTTPClientTransport(new URL(targetUrl()), {
-        requestInit: headers ? { headers } : undefined,
+        requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
     });
     await client.connect(transport);
     try {
@@ -50,24 +65,56 @@ async function withRemote(fn) {
 }
 /** One retry on any failure: the remote is stateless, so a fresh session is
  * equivalent, and a transient network blip shouldn't fail the host's call. */
-export async function callRemote(fn, connect = withRemote) {
+export async function callRemote(fn, connect = withRemote, hostName) {
     try {
-        return await connect(fn);
+        return await connect(fn, hostName);
     }
     catch (first) {
         console.error(`bowmark-mcp: retrying after: ${String(first)}`);
-        return await connect(fn);
+        return await connect(fn, hostName);
+    }
+}
+/** The hosted server's `instructions` string, fetched with one initialize.
+ *
+ * Instructions are handed to the host at OUR initialize, which happens before we
+ * have talked to the remote — so unlike tools they cannot be lazily proxied per
+ * request. Fetching once at startup keeps the hosted server the single source of
+ * truth (the alternative, a hardcoded copy here, would drift the moment the api
+ * changed it and could only be corrected by an npm re-publish).
+ *
+ * KNOWN LIMITATION, and it is the reason this is not a bug report: the api tailors
+ * its instructions PER HOST, but this fetch happens before any host has connected
+ * to us, so we cannot relay a host name yet and the api answers with its
+ * platform-neutral text. Tool descriptions, fetched per request once the host HAS
+ * identified itself, are correctly per-host. Pinning a destination in
+ * BOWMARK_MCP_URL (e.g. .../mcp/cursor) is the way to get tailored instructions
+ * through a bridge.
+ *
+ * Returns undefined on any failure: instructions are a ranking hint, and a
+ * bridge that refused to start because a hint was unavailable would be strictly
+ * worse than one that starts without it. */
+export async function fetchInstructions(remote = callRemote) {
+    try {
+        return await remote(async (c) => c.getInstructions());
+    }
+    catch (err) {
+        console.error(`bowmark-mcp: could not read server instructions: ${String(err)}`);
+        return undefined;
     }
 }
-export function buildServer(remote = callRemote) {
-    const server = new Server({ name: "bowmark", version: "1.0.2" }, { capabilities: { tools: {} } });
+export function buildServer(remote = callRemote, instructions) {
+    const server = new Server({ name: "bowmark", version: "2.0.1" }, { capabilities: { tools: {} }, instructions });
+    // Whoever ran us said who they are on the stdio handshake. Read it per
+    // request rather than once: `tools/list` can arrive before the SDK has
+    // recorded it, and a fresh read costs nothing.
+    const hostName = () => server.getClientVersion()?.name;
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        return await remote((c) => c.listTools());
+        return await remote((c) => c.listTools(), undefined, hostName());
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         // Returned verbatim — content, structuredContent, and isError all ride
         // through, so upstream errors reach the host exactly as the api sent them.
-        return await remote((c) => c.callTool({ name: req.params.name, arguments: req.params.arguments ?? {} }));
+        return await remote((c) => c.callTool({ name: req.params.name, arguments: req.params.arguments ?? {} }), undefined, hostName());
     });
     return server;
 }

package/dist/cli.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 // stdout belongs to the protocol; anything human goes to stderr.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { buildServer } from "./bridge.js";
-const server = buildServer();
+import { buildServer, callRemote, fetchInstructions } from "./bridge.js";
+// One initialize before we serve, purely to carry the hosted server's
+// `instructions` through to the host — they ride on OUR initialize, so they
+// cannot be proxied per request the way tools are. Never fatal; see
+// fetchInstructions.
+const server = buildServer(callRemote, await fetchInstructions());
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "bowmark-mcp",
-  "version": "1.0.2",
+  "version": "2.0.1",
   "mcpName": "ai.bowmark/bowmark",
-  "description": "Bowmark MCP over stdio \u2014 a thin bridge to the hosted Bowmark MCP at https://api.bowmark.ai/mcp",
+  "description": "Bowmark MCP over stdio \u2014 a thin bridge to the hosted Bowmark MCP at https://api.bowmark.ai/mcp. The web as callable functions: read a typed library, write a script, Bowmark runs it on the live sites.",
   "license": "MIT",
   "author": "Bowmark AI <christopher@bowmark.ai>",
   "homepage": "https://bowmark.ai",