feat: meta ads

servlets/meta-ads/.gitignore

@@ -0,0 +1 @@
+dist/

servlets/meta-ads/README.md

@@ -0,0 +1,143 @@
+# Meta Ads
+
+
+This project provides a comprehensive suite of tools designed for managing and analyzing advertising campaigns on the Meta advertising platform. By leveraging these tools, users can efficiently create, monitor, and optimize their advertising efforts across various campaigns, ad sets, and ads.
+
+## Features
+
+- **Business Management:** Retrieve all businesses associated with a user account for better organization and management.
+- **Ad Account Access:** Access all ad accounts available to the user, allowing for streamlined management of advertising resources.
+- **Detailed Account Insights:** Obtain comprehensive information about specific ad accounts, including performance metrics and settings.
+- **Campaign Management:** Retrieve and manage campaigns linked to ad accounts, including filtering options based on status and limits.
+- **Ad Set Management:** Access ad sets associated with specific campaigns or ad accounts, facilitating detailed analysis and organization.
+- **Ad Management:** Retrieve ads linked to particular ad sets, campaigns, or accounts, enabling thorough oversight of advertising materials.
+- **Performance Insights:** Gain insights into campaign, ad set, and ad performance, including metrics such as impressions, clicks, and conversions.
+- **Custom Audience Management:** Manage custom audiences within ad accounts to target advertising more effectively.
+- **Creative Management:** Retrieve and manage creative assets used in advertising efforts.
+- **Bulk Operations:** Perform bulk updates on multiple campaigns, ad sets, or ads for efficient management.
+
+## Configuration
+
+To utilize these tools, authentication via OAuth is required. The tools are configured to interact with the Meta advertising platform, specifically through the Facebook Graph API. A network connection to `graph.facebook.com` is mandatory to access and manage advertising resources effectively.
+
+## Tool Descriptions
+
+### Business Management Tool
+
+- **Description:** Retrieve all businesses associated with the user account.
+- **Input Requirements:** None.
+
+### Ad Account Tool
+
+- **Description:** Access all ad accounts available to the user. Optionally, filter by a specific business ID.
+- **Input Requirements:** 
+  - `business_id`: (optional) The ID of the business to filter ad accounts.
+
+### Account Info Tool
+
+- **Description:** Obtain detailed information about a specific ad account.
+- **Input Requirements:**
+  - `account_id`: The ad account ID (format: act_123456789).
+
+### Campaign Management Tool
+
+- **Description:** Retrieve campaigns for a specific ad account, with options to filter by status and limit the number of campaigns returned.
+- **Input Requirements:**
+  - `account_id`: The ad account ID (format: act_123456789).
+  - `limit`: (optional) The maximum number of campaigns to return.
+  - `status`: (optional) Filter for campaign statuses (ACTIVE, PAUSED, ARCHIVED).
+
+### Ad Set Management Tool
+
+- **Description:** Retrieve ad sets for a specific campaign or ad account, with options to filter by status and limit the number returned.
+- **Input Requirements:**
+  - `account_id`: (optional) The ad account ID to filter ad sets.
+  - `campaign_id`: (optional) The campaign ID to filter ad sets.
+  - `limit`: (optional) The maximum number of ad sets to return.
+  - `status`: (optional) Filter for ad set statuses (ACTIVE, PAUSED, ARCHIVED).
+
+### Ad Management Tool
+
+- **Description:** Retrieve ads for a specific ad set, campaign, or ad account, with options to filter by status and limit the number returned.
+- **Input Requirements:**
+  - `account_id`: (optional) The ad account ID to filter ads.
+  - `adset_id`: (optional) The ad set ID to filter ads.
+  - `campaign_id`: (optional) The campaign ID to filter ads.
+  - `limit`: (optional) The maximum number of ads to return.
+  - `status`: (optional) Filter for ad statuses (ACTIVE, PAUSED, ARCHIVED).
+
+### Performance Insights Tool
+
+- **Description:** Get performance insights for campaigns, ad sets, and ads, with customizable metrics and time ranges.
+- **Input Requirements:**
+  - **For campaigns:** 
+    - `account_id`: The account ID to get insights for.
+    - `campaign_ids`: An array of campaign IDs for insights.
+    - `date_preset`: Preset value for date ranges.
+    - `metrics`: Metrics to retrieve.
+    - `time_range`: Optional custom time range.
+  - **For ad sets:** 
+    - Similar to above but focusing on ad sets.
+  - **For ads:** 
+    - Similar to above but focusing on ads.
+
+### Audience Management Tool
+
+- **Description:** Retrieve custom audiences within a specific ad account.
+- **Input Requirements:**
+  - `account_id`: The ad account ID (format: act_123456789).
+  - `limit`: (optional) The maximum number of audiences to return.
+
+### Creative Management Tool
+
+- **Description:** Retrieve creatives associated with an ad account.
+- **Input Requirements:**
+  - `account_id`: The ad account ID (format: act_123456789).
+  - `limit`: (optional) The maximum number of creatives to return.
+
+### Bulk Update Tool
+
+- **Description:** Perform bulk updates on multiple campaigns, ad sets, or ads for streamlined management.
+- **Input Requirements:**
+  - `operations`: An array of update operations specifying the type of object to update, object ID, and fields to update.
+
+This suite of tools is designed to enhance the management and analysis of advertising activities on the Meta platform, ensuring users can efficiently optimize their advertising strategies.
+
+## How to regsiter an oauth client
+
+### Creating an app
+1. Go to https://developers.facebook.com/apps
+2. Click on "Create App"
+3. Fill in form, click on "Next"
+4. In the use cases, click on "Other"
+5. Select "Business activity"
+6. In Business Portfolio pick the one for mcp.run/dylibso. Note: we will need to verify the business before being able to publish the app for all users, then click on "Create app"
+
+### Basic settings
+1. Click on "App settings" -> "Basic", take note of App ID and App secret
+2. Click on "Add platform" -> Website, and then in Site URL write "https://www.mcp.run/"
+3. Note that you can start business verification from this page
+
+![image](https://github.com/user-attachments/assets/17268b36-ff48-4fe5-af93-315b75156b12)
+
+### Advanced Settings
+1. Click on "App settings" -> "Advanced"
+2. in "Share Redirect Domain Allow List" add "www.mcp.run" and "mcp.run"
+
+### Setting up Marketing API
+1. Go to `https://developers.facebook.com/apps/:appId/add/` or click on "Add Product" on the sidebar
+![image](https://github.com/user-attachments/assets/4cb69641-a223-4260-80b9-51647324d32b)
+3. Click on "setup up" on Marketing API
+4. you don't need to do anything else here
+
+### Setting up Facebook Login for Businesses
+1. Go back to "Add product" and then set up "Facebook Login for Business"
+2. Go to `https://developers.facebook.com/apps/:appId/business-login/settings/`
+3. In `Valid OAuth Redirect URIs` add `https://www.mcp.run/api/login/servlet/dylibso/meta-ads/callback`
+
+## OAuth configuration
+
+- Scopes: `ads_management`, `ads_read`, `read_insights`
+- Allowed domains: `graph.facebook.com`
+- Authorize URL: `https://www.facebook.com/dialog/oauth`
+- Token URL: `https://graph.facebook.com/oauth/access_token`

servlets/meta-ads/go.mod

@@ -0,0 +1,5 @@
+module meta-ads
+
+go 1.22.1
+
+require github.com/extism/go-pdk v1.1.0

servlets/meta-ads/go.sum

@@ -0,0 +1,2 @@
+github.com/extism/go-pdk v1.1.0 h1:K2On6XOERxrYdsgu0uLzCxeu/FYRHE8jId/hdEVSYoY=
+github.com/extism/go-pdk v1.1.0/go.mod h1:Gz+LIU/YCKnKXhgge8yo5Yu1F/lbv7KtKFkiCSzW/P4=

servlets/meta-ads/main.go

@@ -0,0 +1,129 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/extism/go-pdk"
+)
+
+// Schema related types for tool description
+type SchemaProperty struct {
+	Type        string  `json:"type"`
+	Description string  `json:"description,omitempty"`
+	Items       *schema `json:"items,omitempty"`
+}
+
+func prop(tpe, description string) SchemaProperty {
+	return SchemaProperty{Type: tpe, Description: description}
+}
+
+func propWithItems(tpe, description string, itemsSchema schema) SchemaProperty {
+	return SchemaProperty{
+		Type:        tpe,
+		Description: description,
+		Items:       &itemsSchema,
+	}
+}
+
+type schema = map[string]interface{}
+type props = map[string]SchemaProperty
+
+// Helper function to create a pointer
+func some[T any](t T) *T {
+	return &t
+}
+
+// Called when the tool is invoked
+func Call(input CallToolRequest) (CallToolResult, error) {
+	token, ok := pdk.GetConfig("OAUTH_TOKEN")
+	if !ok {
+		return CallToolResult{
+			IsError: some(true),
+			Content: []Content{{
+				Type: ContentTypeText,
+				Text: some("No OAUTH_TOKEN configured"),
+			}},
+		}, nil
+	}
+
+	args := input.Params.Arguments.(map[string]interface{})
+	pdk.Log(pdk.LogDebug, fmt.Sprint("Args: ", args))
+
+	switch input.Params.Name {
+	// Account Management
+	case GetBusinessesTool.Name:
+		return getBusinesses(token, args)
+	case GetAdAccountsTool.Name:
+		return getAdAccounts(token, args)
+	case GetAccountInfoTool.Name:
+		return getAccountInfo(token, args)
+	// Campaign Management
+	case GetCampaignsTool.Name:
+		return getCampaigns(token, args)
+	case CreateCampaignTool.Name:
+		return createCampaign(token, args)
+	case UpdateCampaignTool.Name:
+		return updateCampaign(token, args)
+	case DeleteCampaignTool.Name:
+		return deleteCampaign(token, args)
+	case GetCampaignInfoTool.Name:
+		return getCampaignInfo(token, args)
+	// Ad Set Management
+	case GetAdSetsTool.Name:
+		return getAdSets(token, args)
+	case CreateAdSetTool.Name:
+		return createAdSet(token, args)
+	case UpdateAdSetTool.Name:
+		return updateAdSet(token, args)
+	case DeleteAdSetTool.Name:
+		return deleteAdSet(token, args)
+	case GetAdSetInfoTool.Name:
+		return getAdSetInfo(token, args)
+	// Ad Management
+	case GetAdsTool.Name:
+		return getAds(token, args)
+	case CreateAdTool.Name:
+		return createAd(token, args)
+	case UpdateAdTool.Name:
+		return updateAd(token, args)
+	case DeleteAdTool.Name:
+		return deleteAd(token, args)
+	case GetAdInfoTool.Name:
+		return getAdInfo(token, args)
+	// Insights
+	case GetCampaignInsightsTool.Name:
+		return getCampaignInsights(token, args)
+	case GetAdSetInsightsTool.Name:
+		return getAdSetInsights(token, args)
+	case GetAdInsightsTool.Name:
+		return getAdInsights(token, args)
+	// Audiences
+	case GetAudiencesTool.Name:
+		return getAudiences(token, args)
+	case CreateAudienceTool.Name:
+		return createAudience(token, args)
+	// Creatives
+	case GetCreativesTool.Name:
+		return getCreatives(token, args)
+	case CreateCreativeTool.Name:
+		return createCreative(token, args)
+	// Bulk Operations
+	case BulkUpdateTool.Name:
+		return bulkUpdate(token, args)
+	default:
+		return CallToolResult{
+			IsError: some(true),
+			Content: []Content{{
+				Type: ContentTypeText,
+				Text: some("Unknown tool " + input.Params.Name),
+			}},
+		}, nil
+	}
+}
+
+// Describe the tools provided by this servlet
+func Describe() (ListToolsResult, error) {
+	return ListToolsResult{
+		Tools: MetaAdsReadOnlyTools,
+	}, nil
+}