Fbc Guard

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:

• They keep an older click ID when a returning visitor arrives from a different ad, so the conversion is attributed to the earlier ad.
• They change the click ID on the way through: decode it again, change its case, or cut it short.
• They write creationTime in seconds instead of milliseconds, or hard-code subdomainIndex.

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.

• unknown means no rule failed, but at least one rule could not decide. Today only FBC-01 can return it, when it cannot tell which variable holds the fbclid from the URL. The rule's evidence says what could not be resolved.
• not_applicable means the string _fbc does not appear anywhere in what was scanned, so no rule was evaluated. The code may live somewhere the scan cannot see.

Neither is a pass.

In check_fbc_code, kind: "auto" reads the input as HTML when it starts with < and analyses its inline bodies, and reads anything else as JavaScript.

The server runs its own negative tests at startup and refuses to start if any rule no longer fails on the code it is supposed to catch.

Command line

fbc-guard <url|file> [<url|file> ...]   check pages (http/https) or local files

fbc-guard --json [...] print JSON instead of text fbc-guard --allow-private [...] also allow localhost and private-network URLs fbc-guard --selftest run only the negative tests fbc-guard --help | --version

Each target is judged separately. URLs are fetched together with their same-origin scripts. Local files are scanned as they are, without following , so list your JavaScript files as well. A local file is read as JavaScript when its extension is .js, .mjs, .cjs, .jsx, .ts, .mts, .cts or .tsx, as HTML when it is .html, .htm, .xhtml, .shtml or .php, and otherwise by its first character, as in check_fbc_code.

Before judging any target the CLI runs the same negative tests as the server. If they fail, it prints which test failed and exits with code 2 without giving a verdict.

In CI:

npx -y -p mcp-server-fbc-guard fbc-guard ./public/index.html ./public/js/tracking.js

Rules

Each rule cites Meta's reference page, ClickID and the fbp and fbc Parameters (the older URL under /docs/marketing-api/conversions-api/parameters/fbp-and-fbc/ redirects there). The Basis column says how directly that page supports the rule:

• Official: the page states the requirement.
• Derived: the page states a general requirement; applying it to this specific code pattern is our reading.
• Observed in practice: not stated by Meta; a mistake seen in real implementations.

An error-level rule that fires fails the check (exit code 1). A warning-level rule that fires is reported with status warn and does not change the result or the exit code.

The rules read the source through a small scanner, not a JavaScript parser. Nothing inside a JavaScript comment counts, and neither does markup inside an HTML comment.

• FBC-02, FBC-03 and FBC-04 read only the JavaScript (inline bodies and fetched script files) and also ignore string contents, so a message such as 'do not call decodeURIComponent(fbclid)' does not trigger them.
• FBC-06 and the write-only-if-missing check of FBC-01 look for text that lives inside string literals, so they read the whole document with comments removed and string contents kept.
• FBC-01, FBC-05 and FBP-01 also use the scanner to find where a statement starts and ends.

FBC-01: a new fbclid must overwrite an older _fbc cookie

Code written as "set the cookie if there is none" keeps the first click ID forever. A visitor who returns through a different ad still carries the old one, and the conversion is credited to the earlier ad. Meta's page lists, as a case where the cookie should be set, a URL fbclid that "isn't equal to the corresponding value in the _fbc cookie value".

How the rule decides:

1. It finds the variables that hold the click ID from the URL: assigned from .get('fbclid'), ['fbclid'] or .fbclid, from a match, split, exec or similar call on text containing fbclid=, or copied from one of those (var f = fbclid || ''). A variable or parameter literally named fbclid also counts.
2. It looks for a !==, !=, === or == comparison between one of those variables and something that is not a literal. id !== f and if (stored === clickId) return; count; f !== '' and f != null do not.
3. A comparison passes the rule. That includes "set the cookie if it is missing or different", written as indexOf('_fbc=') < 0 || id !== f.
4. Without a comparison, the rule fails if it finds the write-only-if-missing pattern indexOf('_fbc=') < 0, or if it found a click ID variable.
5. If it found neither a click ID variable nor that pattern, the status is unknown, with an explanation. Exit code 0.

FBC-02: do not URL-decode fbclid a second time

URLSearchParams.get() already returns a decoded value. Decoding it again either leaves it unchanged or changes it, and decodeURIComponent throws on a lone %, which stops the rest of the script. Meta's page says to "do not apply any modifications before using" the click ID. It does not mention decoding specifically; treating a second decode as a modification is our reading.

FBC-03: do not change the case of fbclid

Meta's page states "ClickID value is case sensitive" and names lower- and upper-casing as modifications to avoid.

FBC-04: do not truncate fbclid

A shortened click ID is a modified click ID. Meta's page says to "do not apply any modifications before using" it; truncation is not named specifically.

FBC-05: _fbc creationTime must be in milliseconds

Meta's page defines it: "creationTime is the UNIX time since epoch in milliseconds". Date.now() already returns milliseconds; dividing by 1000 writes seconds.

The rule looks at each statement that contains an _fbc=fb. string or template literal and fails if that statement divides a millisecond clock by 1000:

• clocks: Date.now(), new Date(), (new Date), new Date().getTime(), (new Date).getTime(), new Date().valueOf(), +new Date, and d.getTime() / d.valueOf() on a variable (a new Date(...) built from arguments is a fixed moment, not the clock, and is not matched);
• divisors: /1000 or /1e3, with or without spaces, whatever wraps it (Math.floor, Math.round, Math.trunc, parseInt, |0, ~~);
• written directly in the concatenation or template literal, or stored in a variable first and concatenated in. For a variable, the last assignment before the statement is the one that counts.

It does not fire on Date.now() alone, on /1000 in other statements (a countdown timer elsewhere in the file), on a commented-out line, or on a time difference such as (end - Date.now()) / 1000, which is a duration like max-age, not a timestamp.

FBC-06 (warning): check a hard-coded subdomainIndex in the _fbc cookie

Meta's page says "subdomainIndex is which domain the cookie is defined on"