fbdl-mcp

Servidor MCP para FBDL (Facebook Developer Language) de Meta. Permite a los agentes de IA generar, validar y explorar scripts FBDL utilizados en el programa de recompensas por errores (bug bounty) de Meta (MMBRC).

No se requiere autenticación: FBDL es un formato de texto. Este servidor se ejecuta localmente y nunca se comunica con la infraestructura de Meta.

• fbdl-mcp

  • Qué hace

  • Instalación

  • Configuración con Claude Code

  • Configuración con OpenAI Codex / agentes

    • Fragmento de AGENTS.md

  • Ejemplo de flujo de trabajo

  • Referencia rápida de FBDL

    • Bloque de configuración

    • Líneas de acción

    • Reglas

  • Desarrollo

  • Estructura del proyecto

Qué hace

• validate_fbdl -- Analiza y valida scripts FBDL. Detecta entidades/acciones desconocidas, parámetros obligatorios faltantes, valores de enumeración no válidos y sintaxis incorrecta.

• list_entities -- Explora todos los tipos de entidades de configuración (User, Page, Group, Album, Friendship, Business, App, Event) con sus parámetros y ejemplos.

• list_actions -- Explora más de 70 acciones de FBDL con firmas, parámetros y ejemplos. Filtra por nombre o categoría.

• explain_fbdl -- Convierte un script FBDL en una explicación paso a paso en lenguaje sencillo.

• generate_fbdl (prompt) -- Plantilla de prompt que proporciona al LLM que realiza la llamada la gramática completa de FBDL para que pueda generar scripts válidos a partir de lenguaje natural.

Habilidades de Claude Code (no se necesita servidor MCP)

El repositorio incluye habilidades independientes de Claude Code que funcionan sin el servidor MCP. Copia el directorio .claude/skills/ en cualquier proyecto:

cp -r /path/to/fbdl-mcp/.claude/skills/ your-project/.claude/skills/

Habilidades disponibles:

• /generate-fbdl -- Genera scripts FBDL a partir de lenguaje natural. Incorpora la referencia completa de la gramática para que Claude pueda producir scripts válidos directamente.

• /validate-fbdl -- Valida scripts FBDL contra la gramática. Incluye una lista de verificación completa de estructura, entidad, acción y comprobaciones de referencia.

Estas habilidades integran toda la especificación FBDL como contexto de prompt: sin servidor, sin dependencias, sin paso de compilación.

Instalación

git clone <repo-url> && cd fbdl-mcp
npm install
npm run build

Verifica que todo funcione:

npm run check   # typecheck + lint + format + tests

Configuración con Claude Code

Añádelo a tu configuración MCP de Claude Code (~/.claude/settings.json o .claude/settings.json del proyecto):

{
  "mcpServers": {
    "fbdl": {
      "command": "node",
      "args": ["/absolute/path/to/fbdl-mcp/dist/server.js"]
    }
  }
}

Luego, en Claude Code puedes decir cosas como:

"Genera un script FBDL donde dos usuarios sean amigos, uno sea propietario de una página, el otro publique una foto y sea bloqueado"

"Valida este script FBDL: [setup] User UserOne Page PageOne with {owner: UserOne}"

"¿Qué acciones FBDL están disponibles para grupos?"

Configuración con OpenAI Codex / agentes

Para Codex o cualquier agente compatible con MCP, apúntalo al binario del servidor:

node /absolute/path/to/fbdl-mcp/dist/server.js

El servidor se comunica a través de stdio utilizando el protocolo MCP. Expone:

• 4 herramientas: validate_fbdl, list_entities, list_actions, explain_fbdl

• 1 recurso: fbdl://reference (especificación completa del lenguaje como markdown)

• 1 prompt: generate_fbdl (plantilla de prompt de lenguaje natural a FBDL)

Fragmento de AGENTS.md

Si tu framework de agentes utiliza AGENTS.md para el descubrimiento de herramientas, añade:

## FBDL MCP Server

Tools for working with Meta's FBDL (Facebook Developer Language) scripts:

- Use `validate_fbdl` after generating a script to check it for errors
- Use `list_entities` and `list_actions` to discover available FBDL constructs
- Use `explain_fbdl` to understand what an existing script does
- Use the `generate_fbdl` prompt to produce scripts from natural language

The server runs on stdio. Start with: `node /path/to/fbdl-mcp/dist/server.js`

Ejemplo de flujo de trabajo

1. El agente recibe: "Crea un escenario de prueba donde un administrador de página bloquea a un miembro de un grupo"

2. El agente llama a list_entities para comprobar qué configuración se necesita

3. El agente llama a list_actions con category: "block" para encontrar la acción correcta

4. El agente utiliza el prompt generate_fbdl para producir:

[setup] User OwnerOne User MemberOne Page PageOne with {owner: OwnerOne} Group GroupOne with {owner: OwnerOne, privacy: private, members: [MemberOne]}
OwnerOne as PageOne block MemberOne

5. El agente llama a validate_fbdl para verificar que el script sea correcto

6. El investigador pega el script en la plataforma MMBRC de Meta

Referencia rápida de FBDL

Bloque de configuración

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

Tipos de entidad: User, Page, Group, Album, Friendship, Business, App, Event

Líneas de acción

Subject [as VoiceSwitcher] action_name Label [with {key: value, ...}]

El selector de voz (as) permite a un usuario actuar como una página de la que es propietario.

Reglas

• Todas las entidades deben crearse en la configuración antes de usarse en las acciones

• El bloque de configuración es una sola línea que comienza con [setup]

• Cada acción va en su propia línea

• Las etiquetas (labels) son PascalCase y deben ser únicas

Desarrollo

npm run build         # compile TypeScript
npm run test          # run tests
npm run lint          # eslint with strict TypeScript rules
npm run format        # prettier
npm run check         # all of the above

Estructura del proyecto

src/
  schema.ts           # FBDL language spec as typed data (entities + actions)
  validator.ts        # FBDL script parser and validator
  server.ts           # MCP server (tools, resources, prompts)
  __tests__/
    schema.test.ts    # Schema integrity tests
    validator.test.ts # Validator correctness tests
    server.test.ts    # MCP tool integration tests