Metadata-Version: 2.4
Name: social-commerce-intelligence-mcp
Version: 0.1.1
Summary: Social Commerce Intelligence 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

# Social Commerce Intelligence MCP

## Core Problem

Creator affiliate, video, and shop revenue data is siloed across TikTok, Instagram, Pinterest, YouTube, and Shopify.

## 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 received a production pass. It now includes local creator and social commerce models for creator ROI, video conversion, trending products, affiliate commissions, platform revenue, and underperforming creator detection.

## Connectors

- TikTok Shop API via OAuth scope `seller.read`; env prefix `TIKTOK_SHOP`
- TikTok for Business API via OAuth scope `advertiser.read`; env prefix `TIKTOK_BUSINESS`
- Instagram Graph API via OAuth scope `instagram_basic`; env prefix `INSTAGRAM`
- Pinterest Shopping API via OAuth scope `pins:read`; env prefix `PINTEREST`
- YouTube Data API via OAuth scope `youtube.readonly`; env prefix `YOUTUBE`
- Shopify Admin API via OAuth scope `read_orders`; env prefix `SHOPIFY`

## MCP Tools

- `get_creator_roi_report` - Creator revenue, commission, CAC, and margin.
- `get_top_converting_videos` - Rank videos by conversion quality.
- `get_trending_products` - Trending shop products by niche.
- `get_affiliate_commissions_summary` - Commission liability and payout status.
- `get_social_commerce_revenue_by_platform` - Revenue by social commerce platform.
- `identify_underperforming_creators` - Creators needing coaching or pause.

## Current Local Capabilities

- Calculates creator revenue, commission, total cost, gross profit, contribution profit, ROI, and conversion rate.
- Ranks videos by click-to-order conversion and revenue per thousand views.
- Returns trending products by category and region.
- Summarizes affiliate commission liability and creators held for payout validation.
- Compares social commerce revenue by TikTok, Instagram, YouTube, and Pinterest.
- Detects underperforming creators by order count, conversion rate, and contribution profit.

## Test

```powershell
python -m pytest .\tests -q -p no:cacheprovider
```

## Partial Platform Support

Customers only need to connect the social-commerce platforms they actually use. Missing TikTok Shop, TikTok Business, Instagram, Pinterest, YouTube, Shopify, or affiliate credentials do not prevent the server from starting or running local intelligence tools.

Use `get_live_connector_status` to see configured connectors. Use `test_tiktok_shop_connection`, `test_affiliate_connection`, and `test_social_content_connection` for read-only live smoke checks when those platforms are connected.

## Running Locally

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

## Claude Desktop Config

`json
{
  "mcpServers": {
    "social-commerce-intelligence": {
      "command": "python",
      "args": ["-m", "social_commerce_intelligence_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\07-social-commerce-intelligence"
    }
  }
}
`

## 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/social-commerce-intelligence -->
