Fbc Guard MCP server

fbc-guard

Static checks for the landing-page code that stores Meta's click ID.

Documentation and background: adsandcode.com/en/open-source/fbc-guard

fbc-guard reads the HTML and JavaScript that turn the fbclid URL parameter into the fbc cookie (and, if you write it yourself, the fbp cookie), and flags the known ways that code changes or loses the click ID.

It runs as an MCP server, so an AI assistant can check tracking code while it writes or reviews a page, and as a command-line tool for CI.

The problem it addresses

When someone clicks a Meta ad, the landing page URL carries an fbclid parameter. Your page, or the Meta Pixel, stores it in a first-party _fbc cookie in the form fb..., and later events send that value to Meta in the fbc parameter.

Hand-written versions of this code tend to go wrong in a few specific ways:

ad, so the conversion is attributed to the earlier ad.

• They keep an older click ID when a returning visitor arrives from a different

case, or cut it short.

• They change the click ID on the way through: decode it again, change its

subdomainIndex.

• They write creationTime in seconds instead of milliseconds, or hard-code

Advertisers report seeing an Events Manager diagnostic about a modified fbclid in the fbc parameter. Meta's documentation does not list what causes it. The first two mistakes above alter or replace the click ID between the URL and the event, so they are worth ruling out when you see it.

fbc-guard finds these patterns in source code before it ships. It does not run the code and it sends nothing to Meta.

Install

MCP server

Add this to your MCP client configuration (Claude Desktop, Cursor, and other clients that read an mcpServers block):

{
  "mcpServers": {
    "fbc-guard": {
      "command": "npx",
      "args": ["-y", "mcp-server-fbc-guard"]
    }
  }
}

Claude Code:

claude mcp add fbc-guard -- npx -y mcp-server-fbc-guard

Requires Node.js 18 or later.

Command line

npx -y -p mcp-server-fbc-guard fbc-guard https://your-landing-page.example/
# or install it
npm install -g mcp-server-fbc-guard
fbc-guard ./dist/index.html ./dist/js/tracking.js

As a library

import { checkCode } from "mcp-server-fbc-guard";

const result = checkCode(htmlOrJs); // { status, failed, unknown, warnings, rules }

The package entry point is the rules module only. Importing it does not start the MCP server, read files or touch the network.

MCP tools

Both return JSON:

{
  "status": "fail",
  "failed": ["FBC-01"],
  "unknown": [],
  "warnings": ["FBC-06"],
  "rules": [
    {
      "id": "FBC-01",
      "title": "A new fbclid must overwrite an older _fbc cookie",
      "status": "fail",
      "evidence": "indexOf('_fbc=')<0",
      "protects": "If the cookie is only written when it is missing, ...",
      "basis": "official",
      "severity": "error",
      "reference": "https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc"
    }
  ]
}

Each rule's status is pass, fail, unknown or warn. warn comes only from warning-level rules (FBC-06); it is listed under warnings and never changes the overall status or the exit code.

The overall status is pass, fail, unknown, or not_applicable.

Shortened. The full README is on GitHub.