Metadata-Version: 2.4
Name: competitive-intelligence-mcp
Version: 0.1.1
Summary: Competitive 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

# Competitive Intelligence MCP

## Core Problem

Competitor pricing, ads, SEO, launches, and reviews move faster than manual monitoring.

## 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 competitive monitoring models for price changes, new ads, SEO moves, product launches, review sentiment, and prioritized daily competitive briefs.

## Connectors

- Meta Ad Library API via OAuth scope `ads_archive`; env prefix `META_LIBRARY`
- TikTok Ads Library via OAuth scope `ads.read`; env prefix `TIKTOK_LIBRARY`
- Ahrefs/SEMrush API via OAuth scope `keywords.read`; env prefix `SEO_DATA`
- Amazon Product API via OAuth scope `products.read`; env prefix `AMAZON_PRODUCT`
- Trustpilot API via OAuth scope `reviews.read`; env prefix `TRUSTPILOT`
- Playwright Scraper via OAuth scope `browser`; env prefix `PLAYWRIGHT`

## MCP Tools

- `get_competitor_price_changes` - Price changes in the last week.
- `get_competitor_new_ads` - Recently launched competitor ads.
- `get_competitor_seo_moves` - New keywords and rank changes.
- `get_competitor_new_products` - Sitemap and catalog launch diff.
- `get_competitor_review_sentiment` - Review themes and sentiment trend.
- `get_daily_competitive_brief` - Prioritized daily competitive moves.

## Current Local Capabilities

- Detects competitor price changes and classifies response severity.
- Summarizes newly launched competitor ads and repeated angles.
- Tracks competitor SEO keyword gains, losses, and new keyword entries.
- Detects new product launches from catalog/sitemap diffs.
- Extracts positive and negative review themes for positioning opportunities.
- Produces a daily brief that prioritizes price, ad, SEO, and product signals by impact.
- Returns stable errors for empty inputs, invalid lookback windows, and unknown brands.

## Test

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

## Partial Platform Support

Customers only need to connect the competitive-intelligence sources they actually use. Missing competitor site, Meta Ad Library, TikTok Library, SEO data, Amazon product, Trustpilot, review source, or Playwright credentials do not prevent the server from starting or running local intelligence tools.

Use `get_live_connector_status` to see configured connectors. Use `test_competitor_site_connection`, `test_meta_ad_library_connection`, `test_seo_data_connection`, and `test_review_source_connection` for read-only live smoke checks when those sources are connected.

## Running Locally

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

## Claude Desktop Config

`json
{
  "mcpServers": {
    "competitive-intelligence": {
      "command": "python",
      "args": ["-m", "competitive_intelligence_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\09-competitive-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/competitive-intelligence -->
