{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/logo-400.png\" width=\"120\" alt=\"Review Analyzer\">\n</p>\n\n<h1 align=\"center\">Review Analyzer</h1>\n\n<p align=\"center\">\n  <strong>Agent-native voice-of-customer for e-commerce.</strong><br>\n  <em>Drop in an ASIN or a CSV — get sentiment, pain points, copy-ready listing improvements,<br>\n  and a black-gold HTML dashboard. 6 MCP tools. Backed by the most stable Amazon review data layer.</em>\n</p>\n\n<p align=\"center\">\n  <a href=\"#quick-start\"><img src=\"https://img.shields.io/badge/setup-30s-brightgreen?style=flat-square\" alt=\"30s Setup\"></a>\n  <a href=\"#tools\"><img src=\"https://img.shields.io/badge/MCP%20tools-6-FF6A00?style=flat-square\" alt=\"6 MCP tools\"></a>\n  <a href=\"#data-layer\"><img src=\"https://img.shields.io/badge/markets-10-FF9900?style=flat-square&logo=amazon&logoColor=white\" alt=\"10 Markets\"></a>\n  <a href=\"https://github.com/cline/mcp-marketplace/issues/1602\"><img src=\"https://img.shields.io/badge/Cline-submitted-1976d2?style=flat-square\" alt=\"Cline\"></a>\n  <a href=\"https://github.com/punkpeye/awesome-mcp-servers/pull/6528\"><img src=\"https://img.shields.io/badge/awesome--mcp--servers-PR%20%236528-blueviolet?style=flat-square\" alt=\"awesome-mcp-servers\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"MIT\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"docs/screenshots/dashboard.png\">\n    <img src=\"docs/screenshots/dashboard.png\" alt=\"Dashboard preview\" width=\"100%\">\n  </a>\n</p>\n<p align=\"center\"><sub>↑ Sample dashboard: B08N5WRWNW · 100 reviews · sentiment + pain points + listing improvements, generated by <code>render_dashboard</code>.</sub></p>\n\n---\n\n## TL;DR\n\nTwo inputs, six tools, three outputs.\n\n```\n   ┌─────────────┐                                            ┌──────────────┐\n   │   ASIN      │──┐                                       ┌─│ Markdown     │\n   └─────────────┘  │      ┌─────────────────────────┐      │ │ report       │\n                    ├──────▶ 6 agent-callable tools  ├──────┤ ├──────────────┤\n   ┌─────────────┐  │      └─────────────────────────┘      │ │ Structured   │\n   │  CSV / XLSX │──┘   fetch_reviews   analyze_csv         │ │ JSON         │\n   └─────────────┘      analyze_reviews voc_full            │ ├──────────────┤\n                        extract_listing_improvements        └─│ Black-gold   │\n                        render_dashboard                      │ HTML deck    │\n                                                              └──────────────┘\n```\n\n- **Inputs** — Amazon ASIN (auto-fetched via Shulex VOC OpenAPI, 10 markets) **or** any review CSV / Excel (Helium 10 / eBay / Shopify / custom — fuzzy column detection)\n- **Outputs** — Markdown report · structured JSON · standalone HTML dashboard\n- **Surface** — MCP server (works in Claude Code / Cursor / Cline / Continue) **and** Skill (works in Claude Code)\n\n---\n\n## Quick start\n\n### Option A — As an MCP server (recommended)\n\nRequires [`uv`](https://docs.astral.sh/uv/getting-started/installation/).\n\nAdd this to your MCP client config (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Continue.dev):\n\n```json\n{\n  \"mcpServers\": {\n    \"voc-amazon-reviews\": {\n      \"command\": \"uvx\",\n      \"args\": [\"voc-amazon-reviews-mcp\"],\n      \"env\": {\n        \"VOC_API_KEY\": \"your-shulex-key\"\n      }\n    }\n  }\n}\n```\n\nGet a free Shulex API key (100 calls/month, no credit card): [apps.voc.ai/openapi](https://apps.voc.ai/openapi).\n\n**Optional:** Add `\"ANTHROPIC_API_KEY\": \"sk-ant-...\"` to enable `extract_listing_improvements` (the only tool that calls Claude directly — others work without it). Must be an actual Anthropic key; other providers won't work.\n\nFirst run resolves dependencies in ~5s; subsequent runs are instant.\n\n#### Try it\n\nAsk any MCP-compatible agent:\n\n> Run a VOC report on `B08N5WRWNW`, render the dashboard, and write it to `~/Desktop/voc.html`.\n\nThe agent will call `voc_full` → `render_dashboard` and hand you the file.\n\n\n### Option B — One-shot CLI\n\n```bash\nbash voc.sh B08N5WRWNW --limit 100 --market US\n```\n\n### Option C — Bring your own reviews (CSV)\n\n```bash\n# Drop in any reviews CSV (Helium 10 export, eBay scrape, Shopify, custom)\npython -c \"from mcp_server.tools import analyze_csv, render_dashboard; \\\n  r = analyze_csv('reviews.csv', product_name='My Product'); \\\n  render_dashboard(r, output_path='dashboard.html')\"\n```\n\n### Option D — Hosted on Smithery (no install)\n\nConnect to the server remotely — no `uvx`, no Python, no local install. Bring\nyour own Shulex API key (Smithery prompts for it on first connection).\n\nThis repo ships a `Dockerfile` and `smithery.yaml` for one-click deploy.\nTo run your own hosted instance:\n\n1. Fork or clone this repo to your GitHub.\n2. Sign in at [smithery.ai](https://smithery.ai) with GitHub.\n3. **Deploy a server** → pick the repo. Smithery builds the container and\n   exposes an HTTPS MCP endpoint.\n4. Share the URL with users; they paste it into Claude / Cursor / Cline.\n\nThe same image runs anywhere that takes a Dockerfile — Fly.io, Railway,\nCloudflare Workers (with adapter), Render, Cloud Run.\n\nTo run the HTTP transport locally (e.g. for testing):\n\n```bash\nMCP_TRANSPORT=streamable-http PORT=8080 python -m mcp_server.server\n```\n\n### Option E — Deploy to Vercel (serverless)\n\nThis repo also ships `vercel.json` + `app.py` for one-click Vercel\ndeploys. Sign in at [vercel.com](https://vercel.com) with GitHub, import the\nrepo, and Vercel auto-detects the Python function.\n\nSet these in **Project Settings → Environment Variables** before the first\ndeploy:\n\n| Variable | Required | Notes |\n|---|---|---|\n| `VOC_API_KEY` | yes | Shulex VOC OpenAPI key |\n| `ANTHROPIC_API_KEY` | optional | Only for `extract_listing_improvements` |\n\n**Timeout caveat:** Vercel functions cap at 10s (Hobby default), 60s\n(Hobby with `maxDuration: 60` — already set in `vercel.json`), or 300s\n(Pro). Long-running tools like `voc_full` (30-90s) and\n`extract_listing_improvements` (20-60s) may exceed these limits. For\nunbounded execution, prefer Option D (Docker/Render/Fly) or local install.\n\nThe MCP endpoint after deploy: `https://your-project.vercel.app/mcp`\n\n---\n\n## Tools\n\n| # | Tool | Input | Use when |\n|---|---|---|---|\n| 1 | `fetch_reviews` | ASIN | You want raw reviews; you'll analyze them yourself |\n| 2 | `analyze_reviews` | reviews JSON | You already have reviews and want the VOC report |\n| 3 | `voc_full` | ASIN | Default \"give me a VOC report\" — fetch + analyze in one call |\n| 4 | `extract_listing_improvements` | ASIN | **★ Differentiator** — copy-ready title / 5 bullets / description grounded in customer language |\n| 5 | `analyze_csv` | CSV / Excel path or URL | The product is NOT on Amazon, or you have your own scrape |\n| 6 | `render_dashboard` | VOC report | Generate a standalone black-gold HTML dashboard, no external deps |\n\nAll 6 tools speak MCP. All return JSON-serializable dicts. Full schemas in [`mcp_server/README.md`](mcp_server/README.md).\n\n---\n\n## Data layer — why this is the moat\n\nMost \"AI review tools\" are a thin LLM wrapper over a brittle scraper. **We invert that.** The data layer is the moat:\n\n| | Typical seller-tool data layer | **review-analyzer** |\n|---|---|---|\n| **Source** | Web scraper / undocumented scrape API | Paid [Shulex VOC OpenAPI](https://apps.voc.ai/openapi) |\n| **Reliability** | Breaks when Amazon updates HTML | API-grade, no DOM dependencies |\n| **Markets** | US-only or 2-3 markets | **10**: US, CA, MX, GB, DE, FR, IT, ES, JP, AU |\n| **Volume** | 10–50 reviews (free-tier cap) | Up to **1,000 reviews per ASIN** |\n| **Freshness** | Daily snapshots, sometimes cached for days | Live pull |\n| **Schema** | Strings only | Full: verified-purchase, helpful votes, vine, variant, dates |\n| **Non-English markets** | Often broken / omitted | Native captures + AI translation |\n| **Access** | Locked behind a UI | curl + JSON, fully scriptable, MCP-ready |\n\n**For non-Amazon platforms**, `analyze_csv` accepts any review file — fuzzy column matching detects `内容` / `评价` / `body` / `review` / `content` so you don't have to reformat. Bring data from anywhere, get the same VOC report.\n\n---\n\n## vs. the alternatives\n\n| | **review-analyzer** | Helium 10 / Data Dive | review-analyzer-skill (Buluu) | Generic review scrapers |\n|---|---|---|---|---|\n| **Input** | ASIN **or** CSV | ASIN (manual UI) | CSV only | URL |\n| **Markets** | 10 | 1-3 | depends on user's data | 1 |\n| **Output** | JSON + Markdown + **HTML dashboard** | UI dashboard (locked) | CSV + MD + HTML dashboard | Raw CSV |\n| **MCP-callable** | ✅ | ❌ | ❌ Claude Code only | ❌ |\n| **Listing copy gen** | ✅ `extract_listing_improvements` (cite-by-pain-point) | Keyword research only | ❌ | ❌ |\n| **Cost** | Shulex API + Anthropic API ($0.05-0.20/listing) | $99-249/month subscription | Free (uses your Claude quota) | Free, brittle |\n| **Open source** | ✅ MIT | ❌ | ✅ MIT | varies |\n\n> **Credit & inspiration**: The 22-dimension tag system, fuzzy CSV column detection, and black-gold dashboard aesthetic were inspired by [buluslan/review-analyzer-skill](https://github.com/buluslan/review-analyzer-skill) (MIT). We adapted them onto an MCP-native architecture with the Shulex VOC OpenAPI data layer.\n\n---\n\n## Architecture\n\n```\nmcp_server/\n├── server.py                  # 6 @mcp.tool decorators\n├── tools.py                   # implementations (subprocess wrappers + Anthropic SDK)\n├── csv_loader.py              # fuzzy column detection for CSV/Excel input\n├── dashboard.py               # HTML rendering\n├── dashboard_template.html    # black-gold template (placeholders)\n├── tag_system.yaml            # 22-dim tag schema (customizable per category)\n├── schemas.py                 # pydantic structured-output models\n└── tests/                     # 36 unit tests (subprocess + Anthropic mocked)\n\nfetch.sh / analyze.sh / voc.sh   # shell pipeline behind tools 1-3\n```\n\n- **fetch + analyze loop**: shell scripts (proven, reproducible, easy to debug)\n- **listing rewrites**: Anthropic SDK direct (`claude-opus-4-7` + adaptive thinking + prompt caching on the system rubric)\n- **dashboard**: pure stdlib HTML rendering, no node / no react\n\n---\n\n## Distribution / where to find us\n\n| Channel | Status |\n|---|---|\n| [punkpeye/awesome-mcp-servers PR #6528](https://github.com/punkpeye/awesome-mcp-servers/pull/6528) | ✅ Open |\n| [cline/mcp-marketplace issue #1602](https://github.com/cline/mcp-marketplace/issues/1602) | ✅ Open |\n| [Glama](https://glama.ai/mcp/servers) | 🟢 Auto-indexed via GitHub topics |\n| [mcp.directory](https://mcp.directory) | 🟢 Auto-pull |\n| mcp.so / PulseMCP | 🟡 Pending (manual form submit) |\n| Smithery | 🟡 Container deploy ready (`smithery.yaml` + `Dockerfile` in repo) |\n| Official MCP Registry | 🟡 Pending PyPI publish (W2) |\n\n---\n\n## Roadmap\n\n- [x] Drop in CSV / Excel (any platform, fuzzy column detect)\n- [x] 22-dimension tag system (YAML-configurable)\n- [x] Black-gold HTML dashboard tool\n- [x] 6 MCP tools shipped\n- [ ] `npx skills add mguozhen/review-analyzer` one-line install\n- [ ] CLI subprocess engine option (use your Claude subscription, $0 API)\n- [ ] PyPI publish + official MCP Registry submission\n- [x] Smithery deploy config (`smithery.yaml` + `Dockerfile`)\n- [x] Vercel deploy config (`vercel.json` + `app.py`)\n- [ ] Smithery / mcp.so / PulseMCP form submissions\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n**Acknowledgments**: Tag schema, CSV column detection, and dashboard visual design inspired by [buluslan/review-analyzer-skill](https://github.com/buluslan/review-analyzer-skill). Data layer powered by [Shulex VOC OpenAPI](https://apps.voc.ai/openapi).\n\n<!-- mcp-name: io.github.mguozhen/voc-amazon-reviews-mcp -->\n",
  "bytes": 11684,
  "sha": "36b349d157fa1f881fad319991b2e66856d7287ea3fe26160db98d1377c473b8",
  "repo_slug": "mguozhen/voc-amazon-reviews",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mguozhen_voc_amazon_reviews_mc_7436b162/readme"
}