Metadata-Version: 2.4
Name: marketing-content-production-mcp
Version: 0.1.1
Summary: Marketing Content Production MCP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: license_status.py
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Dynamic: license-file

# Marketing Content Production MCP

## Core Problem

Generic AI content is disconnected from brand voice, product catalog, and real performance history.

## What This Server Provides

This folder contains a production-minded MCP server scaffold with typed JSON tool responses, connector health metadata, OAuth-oriented configuration, rate-limit guards, stable error envelopes, and deterministic demo data until live vendor integrations are attached.

This server has also received the first production pass. The tools now return domain-specific marketing outputs instead of generic placeholder metrics: brand voice context, product-aware ad copy, email sequence drafts, product descriptions, and approval-first social scheduling.

## Connectors

- Google Drive API via OAuth scope `drive.readonly`; env prefix `GOOGLE_DRIVE`
- Notion API via OAuth scope `pages.read`; env prefix `NOTION`
- Shopify Admin API via OAuth scope `read_products`; env prefix `SHOPIFY`
- Meta Ads API via OAuth scope `ads_read`; env prefix `META_ADS`
- Buffer/Later API via OAuth scope `posts.write`; env prefix `SOCIAL_PUBLISH`
- Klaviyo API via OAuth scope `campaigns.write`; env prefix `KLAVIYO`

## MCP Tools

- `get_brand_voice_context` - Extract brand voice and guardrails.
- `get_top_performing_ad_patterns` - Winning message and format patterns.
- `generate_ad_variations` - On-brand ad variations.
- `generate_email_sequence` - Lifecycle email sequence.
- `generate_product_descriptions` - Product descriptions grounded in catalog facts.
- `schedule_social_posts` - Schedule approved posts.

## Current Local Capabilities

- Uses built-in safe demo catalog entries for `growth-suite`, `retention-kit`, and `creative-lab`.
- Uses Shopify catalog products when `SHOPIFY_SHOP_DOMAIN` and `SHOPIFY_ACCESS_TOKEN` are configured.
- Uses explicit brand voice and compliance guardrails.
- Validates argument ranges and returns stable MCP error envelopes.
- Stages social posts for approval; it does not silently publish.
- Falls back safely for unknown SKUs until Shopify is connected.

## Shopify Catalog Adapter

Set these environment variables to ground product copy in live Shopify catalog data:

```powershell
$env:SHOPIFY_SHOP_DOMAIN="your-store.myshopify.com"
$env:SHOPIFY_ACCESS_TOKEN="shpat_..."
$env:SHOPIFY_API_VERSION="2025-01"
```

The adapter maps Shopify title, handle, product type, vendor, tags, body HTML, and variants into the server's internal product shape. Tags can provide better copy context with `benefit:...` and `audience:...` values. If credentials are missing, the SKU is not found, or Shopify returns an error, tools keep working with local fallback catalog data and return a warning.

## Notion Brand Docs Adapter

Set these environment variables to ground brand voice in live Notion documentation:

```powershell
$env:NOTION_API_TOKEN="secret_..."
$env:NOTION_BRAND_PAGE_ID="your-page-id"
$env:NOTION_API_VERSION="2022-06-28"
```

The adapter reads Notion page child blocks and extracts positioning, voice/personality, approved proof points, avoided claims, and compliance notes. Plain text lines such as `Voice: precise, calm`, `Avoid: fake urgency`, `Proof: Shopify-backed catalog`, and `Compliance: legal approval before regulated claims` are mapped into the same brand context shape used by the MCP tools. If Notion is missing or unavailable, the server safely falls back to local brand context and returns a warning.

## Meta Ads Pattern Adapter

Set these environment variables to ground ad patterns in recent Meta Ads performance:

```powershell
$env:META_ADS_ACCESS_TOKEN="EAAB..."
$env:META_ADS_ACCOUNT_ID="act_123456789"
$env:META_ADS_API_VERSION="v21.0"
```

The adapter reads active ads and last-30-day insights, then maps creative text and metrics into the server's internal pattern shape. It uses spend, impressions, clicks, purchases, CTR, and CVR to rank patterns and assign confidence. If Meta credentials are missing, no active ads are returned, or the API fails, the server safely falls back to local ad patterns and returns a warning.

## Test

```powershell
python -m pytest .\tests -q
```

## Partial Platform Support

Customers only need to connect the content and commerce platforms they actually use. Missing Google Drive, Notion, Shopify, Meta Ads, social publishing, or Klaviyo credentials do not prevent the server from starting or running local intelligence tools.

Use `get_live_connector_status` to see configured connectors. Use `test_shopify_catalog_connection`, `test_notion_brand_context_connection`, and `test_meta_ads_connection` for read-only live smoke checks when those platforms are connected.

## Browser Login With Connector Hub

Production customers should connect platforms in the browser through Connector Hub instead of manually editing `.env` files. This server currently supports Connector Hub credential lookup for Notion brand context.

Set:

```powershell
$env:CONNECTOR_HUB_URL="http://127.0.0.1:8090"
$env:CONNECTOR_HUB_SERVICE_TOKEN="change-me-local-service-token"
$env:CONNECTOR_HUB_WORKSPACE_ID="demo"
```

When Connector Hub has Notion credentials for the workspace, `test_notion_brand_context_connection` and `get_brand_voice_context` use those credentials. If the hub is unavailable or Notion is not connected, the server falls back to local `.env` credentials and then demo brand context.

## Running Locally

`powershell
python -m venv .venv
.\.venv\Scripts\pip install -e .
.\.venv\Scripts\python -m marketing_content_production_mcp.server
`

## Claude Desktop Config

`json
{
  "mcpServers": {
    "marketing-content-production": {
      "command": "python",
      "args": ["-m", "marketing_content_production_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\10-marketing-content-production"
    }
  }
}
`

## Production Checklist

- Create OAuth 2.1 apps for each connector and set *_CLIENT_ID plus *_CLIENT_SECRET.
- Store refresh tokens in a secrets manager, never in repo files.
- Replace deterministic demo rows in server.py with API adapter calls.
- Persist raw snapshots and normalized warehouse tables for trend analysis.
- Add integration tests with recorded fixtures for every connector.
- Validate every tool in MCP Inspector before publishing.
- Deploy with a /health route through FastMCP streamable HTTP on Railway or Render.

<!-- mcp-name: io.github.atul0016/marketing-content-production -->
