bowmark-mcp 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# 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`.
+
+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
+{ "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?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. |
+
+## 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
+  sidesteps long-lived-connection failure modes without reconnect bookkeeping.
+  Mirrors `packages/bowmark-mcp/python` (the PyPI bridge) exactly.
+- **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 `mcp-name: ai.bowmark/bowmark` line above is load-bearing**: the
+  official MCP Registry validates npm package ownership by finding that
+  marker in the package README. Don't remove it.
+- **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.
+
+## Tests
+
+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.
+
+## Publishing to npm
+
+To ship a version: **bump `version` in `package.json` (and the two
+`version: "0.1.0"` literals in `src/bridge.ts`) and merge** —
+`.github/workflows/publish-bowmark-mcp.yml` compares the manifest against
+live npm on every merge touching this folder and publishes only when the
+version is new (requires the `NPM_TOKEN_BOWMARK_MCP` Actions secret; token
+lives in the 1Password item "npm bowmark-mcp publish token"). Not
+release-please; the bump IS the release action.
+
+After the FIRST publish: add an npm `packages` entry to
+`mcp-registry/server.json` (same after-publish ordering rule as PyPI — the
+registry validates the `mcp-name` marker on the live npm README), and swap
+the website stdio tab's Node step from `npx mcp-remote` to
+`npx bowmark-mcp`.

package/dist/bridge.js

@@ -0,0 +1,73 @@
+// 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?s=n
+//                    (`?s=n` tags the install source as the npm 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?s=n";
+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;
+}
+async function withRemote(fn) {
+    const client = new Client({ name: "bowmark-mcp-bridge", version: "0.1.0" });
+    const headers = authHeaders();
+    const transport = new StreamableHTTPClientTransport(new URL(targetUrl()), {
+        requestInit: headers ? { 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) {
+    try {
+        return await connect(fn);
+    }
+    catch (first) {
+        console.error(`bowmark-mcp: retrying after: ${String(first)}`);
+        return await connect(fn);
+    }
+}
+export function buildServer(remote = callRemote) {
+    const server = new Server({ name: "bowmark", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return await remote((c) => c.listTools());
+    });
+    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 server;
+}

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/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();
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "bowmark-mcp",
+  "version": "0.1.0",
+  "description": "Bowmark MCP over stdio \u2014 a thin bridge to the hosted Bowmark MCP at https://api.bowmark.ai/mcp",
+  "license": "MIT",
+  "author": "Bowmark AI <christopher@bowmark.ai>",
+  "homepage": "https://bowmark.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bowmark-ai/bowmark-mcp.git",
+    "directory": "node"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bowmark",
+    "browser-automation",
+    "ai-agents"
+  ],
+  "type": "module",
+  "bin": {
+    "bowmark-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "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"
+  }
+}