How pipeboard-co/meta-ads-mcp works
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.