bowmark-mcp 2.0.1 → 2.1.0

package/README.md

@@ -1,108 +1,41 @@
-# bowmark-mcp — Bowmark MCP over stdio (Node)
+# bowmark-mcp — compatibility forwarder
 
-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`.
+**The bridge moved to [`@bowmark/mcp`](https://www.npmjs.com/package/@bowmark/mcp).**
+This package is the old name, kept working.
 
-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,
-descriptions, and results pass through verbatim — the hosted server stays the
-single source of truth; nothing is reimplemented here. (Python-flavored
-environments: the same bridge exists on PyPI as `bowmark-mcp` — `uvx
-bowmark-mcp`.)
-
-`mcp-name: ai.bowmark/bowmark`
-
-## Use
-
-```sh
-npx bowmark-mcp
-```
-
-Any MCP host config:
-
-```json
+```jsonc
+// what you have: still works, prints one notice on stderr
 { "mcpServers": { "bowmark": { "command": "npx", "args": ["bowmark-mcp"] } } }
-```
-
-If your host speaks streamable HTTP, skip this bridge and connect directly to
-`https://api.bowmark.ai/mcp`.
 
-## Environment
-
-| Var | Meaning |
-|---|---|
-| `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. |
+// what to move to
+{ "mcpServers": { "bowmark": { "command": "npx", "args": ["@bowmark/mcp"] } } }
+```
 
-## Design notes (repo-internal)
+Nothing else changes: same bridge, same tools, same endpoint, same version
+number. `bin/bowmark-mcp.mjs` imports `@bowmark/mcp/cli` in-process and that is
+the whole package. In-process rather than spawned, because a child would need
+stdio, signal and exit-code plumbing to be transparent, and every one of those
+is a way for a stdio transport to break.
 
-- **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 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).
-- **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"`
-  field in `package.json` are both load-bearing; don't remove either. Learned
-  the hard way 2026-07-04: `release-mcp.yml`'s registry republish failed for
-  five straight api releases (`server returned status 400: ... "NPM package
-  'bowmark-mcp' is missing required 'mcpName' field"`) because only the
-  README marker was present — the package.json field is what `mcp-publisher
-  publish` actually validates against the live npm package.
-- **Versioning is manual** (thin bridge, not the api): bump `package.json`
-  when it changes. Not wired into release-please; `private` is deliberately
-  absent so npm publish works — release-please doesn't manage this package.
+**PyPI did not move.** `uvx bowmark-mcp` is unchanged, and it is now the
+*blessed* name there: PEP 752 standardises hyphen-prefixed namespaces rather
+than `@scope`, and PyPI has no rename, alias or redirect mechanism at all. Only
+npm is scoped.
 
-## Tests
+## Why a forwarder rather than `npm deprecate`
 
-Network-free unit tests live in the monorepo suite:
-`tests/unit/mcp-stdio-node.test.ts` (`pnpm test:unit`). The remote hop is
-injected at the `callRemote`/`buildServer` seams.
+`npm deprecate` provides a warning to anyone who installs the package. It warns,
+it never blocks, and npm has no "moved" mechanism at all. The name has real
+traffic (3,032 npm installs in the month to 2026-07-28) and every published
+config, registry listing and benchmark harness names it, so the old name has to
+keep *working*, not merely warn. `npm deprecate bowmark-mcp` is run as well: it
+is the notice, this package is the compatibility.
 
-## Publishing to npm
+It is never deleted and never unpublished.
 
-**Live since 2026-07-04** (published by CI + cold-verified via
-`npx -y bowmark-mcp` against prod). To ship a version: **bump `version` in
-`package.json` (and the two `version` literals in `src/bridge.ts`) and
-merge.** The actual publish does NOT run in this monorepo's CI — this repo
-is private, and npm Trusted Publishing (OIDC) validates against
-`package.json`'s `repository.url`, which (correctly) points at the public
-mirror `github.com/bowmark-ai/mcp`, not `Metroxe/bowmark`. So merging here
-only lands the version bump; `release-bowmark-mcp.yml` mirror-syncs it to
-`bowmark-ai/mcp`, and THAT repo's own `.github/workflows/publish.yml`
-(source-controlled at
-[`packages/bowmark-mcp/.github/workflows/publish.yml`](../.github/workflows/publish.yml)
-in this monorepo, mirrored in like any other file) does the real `npm
-publish`. Auth is npm **Trusted Publishing** (OIDC) — no token, configured
-on npmjs.com (package Settings → Trusted Publisher → GitHub Actions, repo
-`bowmark-ai/mcp`, workflow `publish.yml`). Publishing from the public
-mirror also auto-generates provenance attestations, which npm only produces
-for public-repo publishes — impossible from this private monorepo
-regardless of `repository.url`. Not release-please; the bump IS the release
-action.
+## Versioning
 
-`mcp-registry/server.json` carries the matching npm `packages` entry (landed
-after the first publish per the mcp-name ordering rule), and the website
-stdio tab's Node step points at `npx bowmark-mcp`.
+The forwarder's `version` and its `@bowmark/mcp` dependency are pinned to the
+canonical package's version, exactly. A forwarder on an older version would
+silently serve an older bridge to everyone who never migrated, which is the one
+thing it exists to prevent. Both pins are checked in CI upstream.

package/bin/bowmark-mcp.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// The `bowmark-mcp` npm name, kept alive forever.
+//
+// The bridge itself moved to `@bowmark/mcp` on 2026-08-05. This package is the
+// old name continuing to work: npm cannot be unpublished past 72h, `npm
+// deprecate` only WARNS and never blocks an install, and there is no "moved"
+// mechanism on npm at all — so a forwarder is the only thing that actually
+// preserves compatibility for the configs already in the wild.
+// `.claude/rules/agent-surfaces.md` § Published packages cannot be unpublished.
+//
+// Two properties this file exists to hold:
+//
+//   - **stdout belongs to the protocol.** The notice goes to stderr. A single
+//     stray byte on stdout desynchronises the JSON-RPC framing and the host
+//     drops the server with no useful error.
+//   - **The real CLI is imported IN-PROCESS, never spawned.** A child process
+//     would need stdio, signal and exit-code plumbing to be transparent, and
+//     every one of those is a way for a stdio transport to break. An import
+//     shares this process's own stdio by construction.
+//
+// `@bowmark/mcp` declares `./cli` in its `exports` map precisely so this line
+// is a supported entry point rather than a deep import into someone's dist/.
+// No em dash in this string: it is outbound copy, read by everyone who installs
+// the old name. Root CLAUDE.md, "no em dashes in outbound-to-others content".
+console.error(
+  "bowmark-mcp: this package now forwards to @bowmark/mcp. Point your config at `npx @bowmark/mcp` (same bridge, same behaviour).",
+);
+
+await import("@bowmark/mcp/cli");

package/package.json

@@ -1,44 +1,32 @@
 {
   "name": "bowmark-mcp",
-  "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. The web as callable functions: read a typed library, write a script, Bowmark runs it on the live sites.",
+  "version": "2.1.0",
+  "description": "Compatibility forwarder. The Bowmark stdio MCP bridge now ships as @bowmark/mcp; this package re-execs it so every config already in the wild keeps working.",
   "license": "MIT",
   "author": "Bowmark AI <christopher@bowmark.ai>",
   "homepage": "https://bowmark.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bowmark-ai/mcp.git",
-    "directory": "node"
+    "directory": "node-compat"
   },
   "keywords": [
     "mcp",
     "model-context-protocol",
-    "bowmark",
-    "browser-automation",
-    "ai-agents"
+    "bowmark"
   ],
   "type": "module",
   "bin": {
-    "bowmark-mcp": "dist/cli.js"
+    "bowmark-mcp": "bin/bowmark-mcp.mjs"
   },
   "files": [
-    "dist",
+    "bin",
     "README.md"
   ],
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "rm -rf dist && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.7",
-    "typescript": "~5.9.2"
+    "@bowmark/mcp": "2.1.0"
   }
 }

package/dist/bridge.js

@@ -1,120 +0,0 @@
-// Bowmark MCP stdio bridge (Node) — the npm twin of packages/bowmark-mcp/python (PyPI).
-//
-// A thin stdio MCP server that proxies every request to the hosted Bowmark
-// MCP (streamable HTTP, https://api.bowmark.ai/mcp). Exists for stdio-only
-// MCP hosts in Node-flavored environments: they run `npx bowmark-mcp` and get
-// the exact hosted tools — schemas, descriptions, and envelopes pass through
-// verbatim, so the hosted server stays the single source of truth and this
-// 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/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.
-//
-// Design note — one remote session PER REQUEST, retried once. The hosted MCP
-// is stateless and auth-free, so a fresh connection is semantically identical
-// to a held one, costs one initialize round-trip (noise next to an `ask`
-// synthesis), and sidesteps every long-lived-connection failure mode (idle
-// HTTP timeouts, half-open sockets) without reconnect bookkeeping. Mirrors
-// the Python bridge's contract exactly.
-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/npm";
-export function targetUrl(env = process.env) {
-    return env.BOWMARK_MCP_URL?.trim() || DEFAULT_URL;
-}
-/** Optional API key -> X-Bowmark-Key header (the hosted MCP also accepts
- * Authorization: Bearer; one header is enough). */
-export function authHeaders(env = process.env) {
-    const key = env.BOWMARK_API_KEY?.trim();
-    return key ? { "X-Bowmark-Key": key } : undefined;
-}
-/** 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: Object.keys(headers).length > 0 ? { headers } : undefined,
-    });
-    await client.connect(transport);
-    try {
-        return await fn(client);
-    }
-    finally {
-        await client.close().catch(() => { });
-    }
-}
-/** 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, hostName) {
-    try {
-        return await connect(fn, hostName);
-    }
-    catch (first) {
-        console.error(`bowmark-mcp: retrying after: ${String(first)}`);
-        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, 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(), 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 ?? {} }), undefined, hostName());
-    });
-    return server;
-}

package/dist/cli.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-// stdout belongs to the protocol; anything human goes to stderr.
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-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());