# Facebook Ads Management Control Panel (MCP)

A comprehensive Node.js Express server that integrates with the Facebook Marketing API to provide a robust platform for managing Facebook ad campaigns, analyzing performance, and receiving optimization recommendations.

## Features

- **Facebook OAuth Authentication**: Secure login with Facebook credentials
- **Ad Account Management**: View and manage multiple Facebook ad accounts
- **Campaign Management**: Create, read, update, and delete campaigns
- **Ad Set Management**: Create, read, update, and delete ad sets with targeting options
- **Ad Management**: Create, read, update, and delete ads with creative options
- **Analytics**: Comprehensive analytics for campaigns, ad sets, and ads
- **Recommendations**: Intelligent recommendations for budget optimization, targeting, and creative performance
- **API Documentation**: Detailed API documentation for all endpoints
- **Railway Deployment**: Easy deployment to Railway with minimal configuration

## Tech Stack

- **Backend**: Node.js, Express
- **Database**: MongoDB with Mongoose ODM
- **Authentication**: Passport.js with Facebook OAuth, JWT
- **API Integration**: Facebook Marketing API
- **Validation**: Joi
- **Logging**: Winston
- **Security**: Helmet, CORS, Rate Limiting, CSRF Protection
- **Deployment**: Railway

## Project Structure

```
facebook-ads-mcp/
├── src/
│   ├── config/             # Configuration files
│   ├── middleware/         # Express middleware
│   ├── models/             # Mongoose models
│   ├── routes/             # API routes
│   ├── services/           # Business logic
│   ├── utils/              # Utility functions
│   └── app.js              # Express app setup
├── server.js               # Server entry point
├── .env.example            # Environment variables example
├── package.json            # Dependencies and scripts
├── railway.json            # Railway deployment config
└── README.md               # Project documentation
```

## Prerequisites

- Node.js (v14 or higher)
- MongoDB database (local or Atlas)
- Facebook Developer Account with an app that has Marketing API permissions

## Getting Started

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/facebook-ads-mcp.git
   cd facebook-ads-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Create a `.env` file based on `.env.example`:
   ```bash
   cp .env.example .env
   ```

4. Update the `.env` file with your configuration:
   - MongoDB connection string
   - Facebook App ID and Secret
   - JWT secret key
   - Other configuration options

### Running Locally

Start the development server:

```bash
npm run dev
```

The server will be available at `http://localhost:3000`.

## API Endpoints

### Authentication

- `GET /auth/facebook`: Initiate Facebook OAuth flow
- `GET /auth/facebook/callback`: Handle Facebook OAuth callback
- `POST /auth/refresh`: Refresh JWT token
- `POST /auth/logout`: Logout user
- `GET /auth/me`: Get current user
- `PUT /auth/me`: Update current user

### Ad Accounts

- `GET /api/ad-accounts`: Get all ad accounts
- `GET /api/ad-accounts/sync`: Sync ad accounts from Facebook
- `GET /api/ad-accounts/:id`: Get ad account by ID
- `GET /api/ad-accounts/:id/insights`: Get insights for an ad account
- `GET /api/ad-accounts/:id/campaigns`: Get campaigns for an ad account

### Campaigns

- `GET /api/campaigns`: Get all campaigns
- `GET /api/campaigns/sync`: Sync campaigns from Facebook
- `POST /api/campaigns`: Create a new campaign
- `GET /api/campaigns/:id`: Get campaign by ID
- `PUT /api/campaigns/:id`: Update campaign
- `DELETE /api/campaigns/:id`: Delete campaign
- `GET /api/campaigns/:id/insights`: Get insights for a campaign
- `GET /api/campaigns/:id/adsets`: Get ad sets for a campaign
- `GET /api/campaigns/:id/analytics`: Get analytics for a campaign
- `POST /api/campaigns/:id/fetch-analytics`: Fetch and store analytics for a campaign

### Ad Sets

- `GET /api/ad-sets`: Get all ad sets
- `GET /api/ad-sets/sync`: Sync ad sets from Facebook
- `POST /api/ad-sets`: Create a new ad set
- `GET /api/ad-sets/:id`: Get ad set by ID
- `PUT /api/ad-sets/:id`: Update ad set
- `DELETE /api/ad-sets/:id`: Delete ad set
- `GET /api/ad-sets/:id/insights`: Get insights for an ad set
- `GET /api/ad-sets/:id/ads`: Get ads for an ad set
- `GET /api/ad-sets/:id/analytics`: Get analytics for an ad set
- `POST /api/ad-sets/:id/fetch-analytics`: Fetch and store analytics for an ad set
- `GET /api/ad-sets/:id/targeting-recommendations`: Get targeting recommendations for an ad set

### Ads

- `GET /api/ads`: Get all ads
- `GET /api/ads/sync`: Sync ads from Facebook
- `POST /api/ads`: Create a new ad
- `GET /api/ads/:id`: Get ad by ID
- `PUT /api/ads/:id`: Update ad
- `DELETE /api/ads/:id`: Delete ad
- `GET /api/ads/:id/insights`: Get insights for an ad
- `GET /api/ads/:id/analytics`: Get analytics for an ad
- `POST /api/ads/:id/fetch-analytics`: Fetch and store analytics for an ad
- `GET /api/ads/:id/creative-recommendations`: Get creative recommendations for an ad
- `GET /api/ads/:id/preview`: Get preview URL for an ad

### Analytics

- `GET /api/analytics/overview`: Get account overview analytics
- `GET /api/analytics/campaigns`: Get analytics for all campaigns
- `GET /api/analytics/campaigns/:id`: Get analytics for a specific campaign
- `GET /api/analytics/ad-sets`: Get analytics for all ad sets
- `GET /api/analytics/ad-sets/:id`: Get analytics for a specific ad set
- `GET /api/analytics/ads`: Get analytics for all ads
- `GET /api/analytics/ads/:id`: Get analytics for a specific ad
- `POST /api/analytics/fetch`: Fetch and store analytics for all entities
- `GET /api/analytics/comparison`: Get performance comparison between two time periods
- `GET /api/analytics/metrics`: Get available metrics for analytics

### Recommendations

- `GET /api/recommendations/budget`: Get budget optimization recommendations
- `GET /api/recommendations/targeting`: Get targeting recommendations for an ad set
- `GET /api/recommendations/creative`: Get creative performance recommendations
- `GET /api/recommendations/all`: Get all recommendations for an ad account
- `GET /api/recommendations/summary`: Get recommendations summary for an ad account
- `GET /api/recommendations/best-practices`: Get best practices recommendations

### Health Check

- `GET /health`: Health check endpoint
- `GET /health/db`: Database health check endpoint
- `GET /health/deep`: Deep health check endpoint

## Deployment to Railway

This project is configured for easy deployment to Railway.

1. Create a new project on [Railway](https://railway.app/)

2. Connect your GitHub repository

3. Add the required environment variables in the Railway dashboard

4. Deploy the project

The `railway.json` file in the repository configures the deployment settings, including the health check endpoint and restart policy.

## Security Considerations

This project implements several security measures:

- **Authentication**: JWT-based authentication with secure cookies
- **Rate Limiting**: Prevents brute force attacks
- **CSRF Protection**: Prevents cross-site request forgery
- **Helmet**: Sets various HTTP headers for security
- **Input Validation**: Validates all input data using Joi
- **MongoDB Sanitization**: Prevents NoSQL injection
- **XSS Protection**: Prevents cross-site scripting attacks

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.