# pipeboard-co/meta-ads-mcp architecture

> Architecture diagram of the GitHub repository pipeboard-co/meta-ads-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pipeboard-co/meta-ads-mcp
- Repository: https://github.com/pipeboard-co/meta-ads-mcp

## Overview

##### Project Type and Purpose
- This is a Python-based backend microservice implementing a Model Context Protocol (MCP) server for Meta Ads.
- It exposes a streamable HTTP API (and callback server) that MCP clients or LLMs (e.g. Claude, Cursor) call to manage, analyze, and optimize Meta ad campaigns.
- Internally it wraps Meta’s public Graph API endpoints, handles authentication (OAuth or token), and adds AI-oriented utilities (e.g. OpenAI “deep research”).

##### High-Level Architectural Layers
a. Client layer
- MCP-compatible clients / LLMs (Claude, Cursor, ChatGPT plugins)
b. Transport layer
- Streamable HTTP server (`meta_ads_mcp/__main__.py` + `core/server.py`)
- Optional callback server (`core/callback_server.py`)
c. Application layer
- Core request dispatcher (`core/server.py`)
- Authentication modules (`core/auth.py`, `core/authentication.py`, `core/http_auth_integration.py`, `core/pipeboard_auth.py`)
- Business-logic modules (`core/accounts.py`, `core/campaigns.py`, `core/adsets.py`, `core/ads.py`, `core/insights.py`, etc.)
- Utility modules (`core/utils.py`, `core/duplication.py`, `core/openai_deep_research.py`)
d. External integration layer
- Meta Graph API (HTTP calls via `core/api.py`)
- OpenAI API (for deep research / analysis)
e. Infrastructure & DevOps
- Dockerfile for containerization
- GitHub Actions workflows (`.github/workflows/*`) for test, publish, deploy
- Configuration files (`pyproject.toml`, `requirements.txt`, `smithery.yaml`, `server.json`, `.uv.toml`)

##### Suggested Components
- MCP Client (LLM)
- Streamable HTTP Transport
- HTTP Endpoints
- Callback/Webhook Endpoint
- Auth Layer
- OAuth Token Management
- Pipeboard Token Integration
- MCP Business Logic
- Accounts, Campaigns, AdSets, Ads, Insights, Reports, Targeting
- Utilities (duplication, budget schedules, creative management)
- OpenAI Deep Research adapter
- Meta Graph API (external service)
- Optional: Local cache or token store
- DevOps Pipelines (CI/CD)
- Container / Deployment Environment

##### Relationships & Data Flow
1. MCP Client → HTTP Transport → Server Router
2. Router delegates to Auth Layer → fetch/refresh tokens
3. Authenticated requests → Business Logic modules
4. Business Logic → External API wrappers (`core/api.py`)
5. Optional: Business Logic invokes OpenAI (for “deep research”)
6. Responses flow back up → formatted for MCP → stream to client
7. Configuration & Environment variables injected at startup

##### Architectural Patterns & Principles
- Layered Architecture: clear separation of Transport / Auth / Business Logic / External Integration.
- Single Responsibility per module (e.g., `accounts.py` only handles ad‐account operations).
- Adapter Pattern: `core/api.py` adapts Meta’s Graph API for internal models.
- Dependency Injection via environment/config files and `pyproject.toml`.
- CI/CD via GitHub Actions ensures consistent testing and publishing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["MCP Client / LLM"]:::external2
    end

    %% Transport Layer
    subgraph "Transport Layer"
        Entry["Entry Point (__main__.py)"]:::internal
        Router["HTTP Server & Router (server.py)"]:::internal
        Callback["Callback/Webhook Server (callback_server.py)"]:::internal
    end

    %% Authentication Layer
    subgraph "Auth Layer"
        Auth["OAuth & Token Authentication (auth.py)"]:::internal
        AuthCore["Core Authentication Logic (authentication.py)"]:::internal
        HTTPAuth["HTTP Auth Integration (http_auth_integration.py)"]:::internal
        PipeAuth["Pipeboard Token Integration (pipeboard_auth.py)"]:::internal
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        Accounts["Accounts (accounts.py)"]:::internal
        Campaigns["Campaigns (campaigns.py)"]:::internal
        AdSets["AdSets (adsets.py)"]:::internal
        Ads["Ads (ads.py)"]:::internal
        AdsLib["Ads Library Utilities (ads_library.py)"]:::internal
        Insights["Insights (insights.py)"]:::internal
        Reports["Reports (reports.py)"]:::internal
        Targeting["Targeting (targeting.py)"]:::internal
        Resources["Resource Definitions (resources.py)"]:::internal
        Budget["Budget Schedules (budget_schedules.py)"]:::internal
        Duplication["Duplication (duplication.py)"]:::internal
        Utils["General Utilities (utils.py)"]:::internal
        OpenAI["OpenAI Deep Research (openai_deep_research.py)"]:::internal
    end

    %% Adapter
    Adapter["Meta Graph API Adapter (api.py)"]:::internal

    %% External Integration
    subgraph "External Integration"
        MetaAPI["Meta Graph API"]:::external
        OpenAIAPI["OpenAI API"]:::external
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        Docker["Docker Container (Dockerfile)"]:::infra
        CI["CI/CD Workflows (.github/workflows)"]:::infra
        Config["Configuration Files (pyproject.toml, requirements.txt, server.json, .uv.toml, smithery.yaml)"]:::infra
    end

    %% Connections
    Client -->|"HTTP/JSON"| Entry
    Entry -->|"init server"| Router
    Entry -->|"start callback"| Callback

    Router -->|"authenticate"| Auth
    Auth -->|"delegate"| AuthCore
    AuthCore -->|"use OAuth"| Auth
    AuthCore -->|"inject token"| HTTPAuth
    AuthCore -->|"pipeboard token"| PipeAuth
    Router -->|"route to logic"| Accounts
    Router -->|"route to logic"| Campaigns
    Router -->|"route to logic"| AdSets
    Router -->|"route to logic"| Ads
    Router -->|"route to logic"| AdsLib
    Router -->|"route to logic"| Insights
    Router -->|"route to logic"| Reports
    Router -->|"route to logic"| Targeting
    Router -->|"route to logic"| Resources
    Router -->|"route to logic"| Budget
    Router -->|"route to logic"| Duplication
    Router -->|"route to logic"| Utils
    Router -->|"route to deep research"| OpenAI

    Accounts -->|"Graph API call"| Adapter
    Campaigns -->|"Graph API call"| Adapter
    AdSets -->|"Graph API call"| Adapter
    Ads -->|"Graph API call"| Adapter
    AdsLib -->|"Graph API call"| Adapter
    Insights -->|"Graph API call"| Adapter
    Reports -->|"Graph API call"| Adapter
    Targeting -->|"Graph API call"| Adapter
    Resources -->|"Graph API call"| Adapter
    Budget -->|"Graph API call"| Adapter
    Duplication -->|"Graph API call"| Adapter
    Utils -->|"utility calls"| Adapter

    Adapter -->|"HTTP calls"| MetaAPI
    OpenAI -->|"analysis requests"| OpenAIAPI

    Config -->|"env vars"| Entry
    Config -->|"env vars"| AuthCore
    Docker --> Entry
    CI -->|"deploy/test"| Docker

    %% Return to Client
    MetaAPI -->|"response"| Accounts
    OpenAIAPI -->|"analysis result"| OpenAI
    Accounts -->|"MCP response"| Router
    Router -->|"stream response"| Client

    %% Click Events
    click Entry "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/__main__.py"
    click Router "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/server.py"
    click Callback "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/callback_server.py"
    click Auth "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/auth.py"
    click AuthCore "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/authentication.py"
    click HTTPAuth "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/http_auth_integration.py"
    click PipeAuth "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/pipeboard_auth.py"
    click Adapter "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/api.py"
    click Accounts "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/accounts.py"
    click Campaigns "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/campaigns.py"
    click AdSets "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/adsets.py"
    click Ads "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/ads.py"
    click AdsLib "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/ads_library.py"
    click Insights "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/insights.py"
    click Reports "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/reports.py"
    click Targeting "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/targeting.py"
    click Resources "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/resources.py"
    click Budget "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/budget_schedules.py"
    click Duplication "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/duplication.py"
    click Utils "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/utils.py"
    click OpenAI "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/meta_ads_mcp/core/openai_deep_research.py"
    click Docker "https://github.com/pipeboard-co/meta-ads-mcp/tree/main/Dockerfile"
    click CI "https://github.com/pipeboard-co/meta-ads-mcp/tree/main/.github/workflows/"
    click Config "https://github.com/pipeboard-co/meta-ads-mcp/blob/main/pyproject.toml"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#DFFFE0,stroke:#28A745,stroke-width:1px
    classDef external2 fill:#E0F7FF,stroke:#007BFF,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#6A737D,stroke-width:1px
```
