Content
# pangolinfo-voc-mcp
Pangolinfo white-label **Brand Social Media Insights (VOC) MCP**. This repository is the MCP protocol layer, exposing brand/topic social media collection, reading, and analysis tools to AI clients.
## Architecture
End AI users only see Pangolinfo. This repository does not hold any upstream credentials, does not deduct fees, and does not touch wholesale account quotas. Credential caching, `externalUserId` injection, point deduction, error mapping, and white-label purification are all done in the Pangolinfo backend.
```text
AI Client
-> pangolinfo-voc-mcp (this repository, MCP forwarding layer)
-> Pangolinfo Backend (fee deduction, credentials, white-label purification are done here)
-> Upstream Data Provider API
```
Production MCP Address:
```text
https://voc.pangolinfo.com/mcp?api_key=<Pangolinfo JWT/API key>
```
## Tools
There are currently 25 tools:
- Context/ Rules: `social_capabilities`, `get_context`, `get_billing_rules`, `suggest_next_actions`, `explain_error`
- Knowledge Space: `prepare_space`, `create_space`
- Brand Management: `list_brands`, `get_brand`, `prepare_brand_onboarding`, `setup_brand`, `update_brand`
- Collection: `diagnose_brand`, `refresh_brand`, `get_refresh_progress`, `wait_for_refresh`
- Data Reading: `get_brand_metrics`, `search_brand_posts`, `find_posts_about`, `get_brand_sentiment`, `get_voice_share`, `compare_competitors`, `get_risk_alerts`
- Analysis: `analyze_brand`, `get_brand_summary`
The default access path is the Knowledge Space:
```text
prepare_space (free to plan/estimatedPoints)
-> User confirms industry + platform + page count
-> create_space (deducts fee and returns spaceId + jobId)
-> get_refresh_progress / wait_for_refresh
-> Read data or analyze_brand
```
## Billing
Read-only tools are completely free. Collection tools `create_space` / `refresh_brand` / `setup_brand` are billed according to the Pangolinfo point system after the upstream acceptance is successful and returns an estimate:
```text
Points = Number of Brands * Weighted Channel Unit * Number of Keywords * Page Count * 12
```
Channel Unit: ordinary social media channels = 1, `threads` = 1, `reddit` = 2, `amazon_reviews` does not participate in the collection formula.
`analyze_brand` is a synchronous in-depth analysis, billed at 600 points per success. `get_brand_summary` is free.
## Platforms
Knowledge Space supports 9 social media platforms:
```text
tiktok, instagram, youtube, x, facebook, pinterest, trustpilot, reddit, threads
```
Default pre-selection of 7: `tiktok/instagram/youtube/x/facebook/pinterest/trustpilot`. `threads` is optional and counted as 1 channel unit, `reddit` is optional but counted as 2 channel units.
`amazon_reviews` is not a Knowledge Space channel. Only complete brand `setup_brand` supports Amazon Reviews, and must be passed:
```json
{
"monitorPlatforms": ["amazon_reviews"],
"amazonProducts": [{ "asin": "B0..." }]
}
```
Keywords must be in English. Keywords containing Chinese, Japanese, or Korean characters will be rejected at the MCP schema layer. Please translate Chinese topics into English keywords first.
## Local Development
```bash
npm ci
npm run typecheck
npm run build
npm run dev -- --transport=http --port=3000
```
Health Check:
```bash
curl http://localhost:3000/health
```
Production build uses Dockerfile. ACK deployment image tag is based on the actual release, and the current version is `0.2.6`.
