AlexandreCalvet/ogury-mcp-server

Ogury MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Ogury API, specifically for retrieving campaign performance reports and brand information.

Features

• Authentication: Automatic OAuth2 token management with the Ogury API
• Campaign Reports: Retrieve campaign performance data with flexible filtering
• Brand Information: Get available brands from your Ogury account
• Parameter Validation: Built-in validation for required parameters
• Error Handling: Comprehensive error handling and user-friendly error messages

Prerequisites

• Node.js 18+
• npm or yarn
• Ogury API credentials (client_id and client_secret)

Installation

1. Clone this repository:

git clone <repository-url>
cd ogury-mcp-server

2. Install dependencies:

npm install

3. Copy the environment example file and configure your credentials:

cp env.example .env

4. Edit the .env file with your Ogury API credentials:

OGURY_CLIENT_ID=your_client_id_here
OGURY_CLIENT_SECRET=your_client_secret_here
OGURY_API_BASE_URL=https://api.ogury.com

Usage

Development Mode

npm run dev

Production Build

npm run build
npm start

Available Tools

1. get_campaign_report

Retrieves campaign performance reports from the Ogury API.

Required Parameters:

• startDate (string): Start date in YYYY-MM-DD format
• endDate (string): End date in YYYY-MM-DD format

Optional Parameters:

• accountId (string): Account IDs (one of accountId, brandId, or campaignId is required)
• brandId (string): Brand ID (one of accountId, brandId, or campaignId is required)
• campaignId (number): Campaign ID (one of accountId, brandId, or campaignId is required)
• identifier1 (string): External identifier 1
• identifier2 (string): External identifier 2
• identifier3 (string): External identifier 3

Example Usage:

{
  "startDate": "2024-09-16",
  "endDate": "2024-09-23",
  "campaignId": 100
}

2. get_brands

Retrieves available brands from your Ogury account.

Parameters: None required

API Response Format

Campaign Report Response

{
  "campaignId": 123,
  "campaign": "Ogury Campaigns",
  "costModel": "CPC",
  "campaignGoal": 100,
  "brand": "Ogury Brand",
  "strategy": "Ogury Strategy",
  "impressions": 100,
  "clicks": 100,
  "ctr": 1,
  "videoCompletes": 100,
  "vtr": 1,
  "engagement": 1,
  "engagementRate": 1,
  "spend": 1000,
  "currency": "USD",
  "reach": 100,
  "frequency": 1.5,
  "identifier1": "external identifier 1",
  "identifier2": "external identifier 2",
  "identifier3": "external identifier 3"
}

Error Handling

The server provides detailed error messages for common issues:

• Authentication Errors: Invalid credentials or expired tokens
• Parameter Validation: Missing required parameters or invalid values
• API Errors: Server errors or rate limiting issues

Development

Project Structure

src/
├── index.ts              # Main entry point
├── mcp-server.ts         # MCP server implementation
├── services/
│   └── ogury-api.ts      # Ogury API service
└── types/
    └── ogury.ts          # TypeScript type definitions

Building

npm run build

Testing

npm test

Configuration

The server can be configured through environment variables:

• OGURY_CLIENT_ID: Your Ogury API client ID
• OGURY_CLIENT_SECRET: Your Ogury API client secret
• OGURY_API_BASE_URL: Ogury API base URL (default: https://api.ogury.com)

License

MIT License - see LICENSE file for details.

Support

For issues related to:

• MCP Server: Check the GitHub issues or create a new one
• Ogury API: Contact your Ogury Account Manager