fbdl-mcp: Instructions file for Codex

FBDL MCP Server -- Agent Instructions

What is FBDL?

FBDL (Facebook Developer Language) is a domain-specific language used in Meta's MMBRC (bug bounty program). It creates reproducible test environments with whitehat test users, pages, groups, and other Facebook entities. Researchers use FBDL scripts to set up specific scenarios for security testing.

Scripts are executed inside Meta's bug bounty platform -- this MCP server generates and validates them locally. The server fetches the FBDL grammar from https://api.facebook.com/bug_bounty/fbdl_reference/ at startup so it stays current, which requires FBDL_API_TOKEN in the environment.

Available tools

Tool	When to use
validate_fbdl	After generating or receiving any FBDL script. Always validate before presenting to user.
list_entities	To check what setup entities exist and their parameters. Filter by type (User, Page, Group, etc).
list_actions	To find available actions. Filter by name or category (post, group, page, business, event, app).
explain_fbdl	To describe what an existing FBDL script does in plain English.

There is also a generate_fbdl prompt template that provides the full FBDL grammar for script generation.

Workflow

1. list_entities / list_actions  -->  discover what's available
2. write the FBDL script          -->  follow the grammar below
3. validate_fbdl                  -->  catch errors before presenting
4. (optional) explain_fbdl        -->  verify it does what's intended

Never skip step 3. Always validate.

FBDL grammar

Setup block (single line)

[setup] Type Label [with {key: value}] [Type Label with {key: value}] ...

Everything in the setup block is on ONE line. Entities are declared sequentially.

Entity types:

• User -- No params needed. Just User LabelName.
• Page -- Requires owner. Optional: admins, editors, moderators, is_parent_location.
• Group -- Requires owner, privacy (public|private|public_legacy). Optional: members, admins, visibility.
• Album -- Requires owner, type (user|shared|page|group), place.
• Friendship -- Requires sender, receivers (list). Has NO label.
• Business -- Requires owner. Optional: employees, admins, primary_page, quarantine.
• App -- Requires owner. Optional: live (true|false), type.
• Event -- Requires owner, place. Optional: privacy, is_past, post_permission, post_approval.