mcp-page-bridge-protocol 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eray Ates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared constants and helpers used by both the mcp-page-bridge bridge (Node) and the
+ * browser-side client (extension). Keep this dependency-free so it can be
+ * bundled into a service worker / content script as well as Node.
+ */
+export declare const MCP_PAGE_BRIDGE_VERSION = "0.1.3";
+/** WebSocket subprotocol negotiated between the browser client and the bridge. */
+export declare const WS_SUBPROTOCOL = "mcp";
+/** Default port the bridge listens on for browser WebSocket connections. */
+export declare const DEFAULT_PORT = 8787;
+/** Separator between a provider label and the original tool name. */
+export declare const NAMESPACE_SEP = "__";
+/**
+ * Turn an arbitrary provider/server name into a tool-name-safe label.
+ * Lowercase, spaces/dots -> hyphen, strip disallowed chars, clamp length.
+ */
+export declare function sanitizeLabel(input: string | undefined | null): string;
+/** Build the agent-facing namespaced tool name. */
+export declare function namespaceName(label: string, name: string): string;
+/** Metadata a provider can advertise about the page it lives in. */
+export interface ProviderMeta {
+    url?: string;
+    title?: string;
+    userAgent?: string;
+    /** Browser tab id, when the provider is owned by an extension content tab. */
+    tabId?: number;
+    /** Extension-internal provider id for that tab. */
+    providerId?: string;
+}
+/** Bridge -> extension private JSON-RPC methods used by the local dashboard. */
+export declare const MCP_PAGE_BRIDGE_DASHBOARD_ACTIVATE_TAB: "mcpPageBridge/activateTab";
+export declare const MCP_PAGE_BRIDGE_DASHBOARD_CLOSE_TAB: "mcpPageBridge/closeTab";
+/** Direction of an internal channel message relative to the bridge. */
+export type ChannelDir = "up" | "down";
+/**
+ * Internal envelope used on the extension's own channel:
+ *   page (MAIN) <-> content script (ISOLATED) <-> service worker.
+ *
+ * This is NOT the wire to the bridge (that is raw MCP JSON-RPC). The SW
+ * terminates this envelope and forwards `payload` (a JSON-RPC message) onto the
+ * per-provider WebSocket. `providerId` lets a single tab host several providers
+ * (e.g. built-ins + a page MCP). `providerId === "*"` denotes a control/global
+ * message not tied to a specific provider.
+ *
+ * `dir` prevents postMessage echo loops since MAIN and ISOLATED scripts share
+ * the same `window` and both observe every `message` event.
+ */
+export interface ChannelMessage {
+    /** Magic marker so we can ignore unrelated postMessage traffic. */
+    __mcpPageBridge: true;
+    dir: ChannelDir;
+    providerId: string;
+    kind: "rpc" | "open" | "close" | "control" | "ext";
+    /**
+     * - kind "rpc":     a JSON-RPC message object
+     * - kind "open":    `{ url, title }` source metadata (for the popup)
+     * - kind "control": `{ action: "hello" | "activate" | "deactivate", ... }`
+     * - kind "ext":     up = `ExtCallPayload`, down = `ExtResultPayload`
+     */
+    payload?: unknown;
+}
+/** Request from the page (MAIN) to the SW to run an extension-only action. */
+export interface ExtCallPayload {
+    id: number;
+    action: string;
+    args?: Record<string, unknown>;
+}
+/** Response from the SW back to the page for an ExtCallPayload. */
+export interface ExtResultPayload {
+    id: number;
+    result?: unknown;
+    error?: string;
+}
+export type ControlAction = "hello" | "activate" | "deactivate";
+export interface ControlPayload {
+    action: ControlAction;
+    url?: string;
+    title?: string;
+}
+export declare const MCP_PAGE_BRIDGE_MARK: "__mcpPageBridge";

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * Shared constants and helpers used by both the mcp-page-bridge bridge (Node) and the
+ * browser-side client (extension). Keep this dependency-free so it can be
+ * bundled into a service worker / content script as well as Node.
+ */
+export const MCP_PAGE_BRIDGE_VERSION = "0.1.3";
+/** WebSocket subprotocol negotiated between the browser client and the bridge. */
+export const WS_SUBPROTOCOL = "mcp";
+/** Default port the bridge listens on for browser WebSocket connections. */
+export const DEFAULT_PORT = 8787;
+/** Separator between a provider label and the original tool name. */
+export const NAMESPACE_SEP = "__";
+/** Allowed characters in an MCP tool name component. */
+const DISALLOWED = /[^a-zA-Z0-9_-]/g;
+/**
+ * Turn an arbitrary provider/server name into a tool-name-safe label.
+ * Lowercase, spaces/dots -> hyphen, strip disallowed chars, clamp length.
+ */
+export function sanitizeLabel(input) {
+    const base = (input ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[\s.]+/g, "-")
+        .replace(DISALLOWED, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "")
+        .slice(0, 40);
+    return base || "browser";
+}
+/** Build the agent-facing namespaced tool name. */
+export function namespaceName(label, name) {
+    return `${label}${NAMESPACE_SEP}${name}`;
+}
+/** Bridge -> extension private JSON-RPC methods used by the local dashboard. */
+export const MCP_PAGE_BRIDGE_DASHBOARD_ACTIVATE_TAB = "mcpPageBridge/activateTab";
+export const MCP_PAGE_BRIDGE_DASHBOARD_CLOSE_TAB = "mcpPageBridge/closeTab";
+export const MCP_PAGE_BRIDGE_MARK = "__mcpPageBridge";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mcp-page-bridge-protocol",
+  "version": "0.1.3",
+  "type": "module",
+  "description": "Shared constants/helpers for the mcp-page-bridge bridge and browser client",
+  "license": "MIT",
+  "author": "Eray Ates",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rytsh/mcp-page-bridge.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "browser",
+    "websocket",
+    "protocol"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}