Create Goal

Instructions

Implementation Reference

• src/tools/goals.ts:208-248 (registration)

  Registration of the 'rybbit_create_goal' tool on the MCP server with its metadata (title, description, annotations, inputSchema).

  server.registerTool(
    "rybbit_create_goal",
    {
      title: "Create Goal",
      description:
        "Create a new conversion goal for a site. Goal can be path-based (URL match) or event-based (custom event triggered).",
      annotations: {
        readOnlyHint: false,
        idempotentHint: false,
        openWorldHint: true,
        destructiveHint: false,
      },
      inputSchema: {
        siteId: siteIdSchema,
        name: z.string().optional().describe("Optional display name for the goal"),
        goalType: z.enum(["path", "event"]).describe("'path' = URL pattern, 'event' = custom event"),
        config: goalConfigSchema,
      },
    },
    async (args) => {
      try {
        const { siteId, ...body } = args as {
          siteId: string;
          name?: string;
          goalType: "path" | "event";
          config: Record<string, unknown>;
        };
  
        const data = await client.post(`/sites/${siteId}/goals`, body);
        return {
          content: [{ type: "text" as const, text: truncateResponse(data) }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/tools/goals.ts:227-247 (handler)

  Handler function that executes the tool logic: destructures args (siteId + body), makes a POST request to /sites/{siteId}/goals, and returns the response or an error.

  async (args) => {
    try {
      const { siteId, ...body } = args as {
        siteId: string;
        name?: string;
        goalType: "path" | "event";
        config: Record<string, unknown>;
      };
  
      const data = await client.post(`/sites/${siteId}/goals`, body);
      return {
        content: [{ type: "text" as const, text: truncateResponse(data) }],
      };
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      return {
        content: [{ type: "text" as const, text: `Error: ${message}` }],
        isError: true,
      };
    }
  }

• src/tools/goals.ts:178-206 (schema)

  The 'goalConfigSchema' used by the tool's inputSchema for the config field. Defines goal configuration with pathPattern, eventName, eventPropertyKey/Value, and propertyFilters.

  const goalConfigSchema = z
    .object({
      pathPattern: z
        .string()
        .optional()
        .describe("Path pattern (required when goalType='path'). Supports wildcards like /products/*"),
      eventName: z
        .string()
        .optional()
        .describe("Event name (required when goalType='event')"),
      eventPropertyKey: z
        .string()
        .optional()
        .describe("Event property key to match (optional, must be paired with eventPropertyValue)"),
      eventPropertyValue: z
        .union([z.string(), z.number(), z.boolean()])
        .optional()
        .describe("Event property value to match (optional, must be paired with eventPropertyKey)"),
      propertyFilters: z
        .array(
          z.object({
            key: z.string(),
            value: z.union([z.string(), z.number(), z.boolean()]),
          })
        )
        .optional()
        .describe("Multiple property filters (alternative to single eventPropertyKey/Value pair)"),
    })
    .describe("Goal configuration. Use pathPattern for path goals or eventName for event goals.");

• src/index.ts:47-48 (registration)

  Top-level registration call: registerGoalsTools(server, client) wires up all the goals tools including rybbit_create_goal.

  registerGoalsTools(server, client);
  registerJourneysTools(server, client);