FlowGuide MCP Bridge

FlowGuide MCP Bridge provides the local HTTP/MCP service and Chrome Native Messaging host used by the FlowGuide extension.

Requirements

• Node.js 20 or newer
• Google Chrome or Chromium

Install

Install the verified bridge version. Its npm postinstall hook registers the Chrome Native Host automatically:

npm install -g [email protected]

Use bootstrap only when a custom unpacked extension needs an explicit extension ID or when a repair flow asks for it.

The Chrome Web Store extension does not need --extension-id. Add it only for a custom unpacked extension:

flowguide-mcp-bridge bootstrap --port 12306 --browser chrome --extension-id <32-character-extension-id>

Verify the installation:

flowguide-mcp-bridge doctor --browser chrome
flowguide-mcp-bridge smoke --port 12306

If doctor reports stale paths, permissions, or registration, apply its targeted repair and then verify again:

flowguide-mcp-bridge doctor --fix --browser chrome
flowguide-mcp-bridge smoke --port 12306 --browser-runtime

See install.md for the complete install and repair flow.

Workspace Development

Run these commands from the repository root:

pnpm --filter chrome-mcp-shared build
pnpm --filter flowguide-mcp-bridge build
pnpm --filter flowguide-mcp-bridge test
pnpm test:package-contract

The package contract test creates real npm tarballs, installs them in a temporary consumer project, and verifies the shared exports and Bridge module loading.

MCP Gateway Registry

The Bridge can discover remote tools from an external mcp-gateway-registry and merge them into the local /mcp endpoint.

Minimal configuration:

MCP_GATEWAY_REGISTRY_ENABLED=1
MCP_GATEWAY_REGISTRY_URL=http://127.0.0.1:8080
MCP_GATEWAY_REGISTRY_DISCOVERY_MODE=auto

Common optional settings:

MCP_GATEWAY_REGISTRY_AUTH_TOKEN=<bearer-token>
MCP_GATEWAY_REGISTRY_SESSION_COOKIE=<cookie-value-or-full-cookie-header>
MCP_GATEWAY_REGISTRY_USERNAME=<username>
MCP_GATEWAY_REGISTRY_PASSWORD=<password>
MCP_GATEWAY_REGISTRY_ALLOW_TOOLS=["weather.get_forecast"]
MCP_GATEWAY_REGISTRY_BLOCK_TOOLS=["finance.delete_account"]
MCP_GATEWAY_REGISTRY_REFRESH_TTL_MS=60000
MCP_GATEWAY_REGISTRY_SERVICE_MCP_SUFFIX=/mcp

Registry tools are discovered first and enabled on demand. Use mcp_gateway_search_tools, mcp_gateway_enable_tools, mcp_gateway_disable_tools, mcp_gateway_list_enabled_tools, and mcp_gateway_refresh_catalog to manage the active tool set.

Site MCP Discovery

The Bridge can also discover MCP endpoints exposed by the current browser page and route calls through the browser runtime so the site's login session remains available.

MCP_SITE_MCP_ENABLED=1
MCP_SITE_MCP_REFRESH_TTL_MS=15000

Site tools are catalogued but only appear in /mcp after they are enabled. Discovery failure does not disable the built-in local tools.

License

MIT