Metadata-Version: 2.4
Name: feedback-synthesis-mcp
Version: 0.1.1
Summary: Customer feedback intelligence MCP — synthesize GitHub Issues, HN, and App Store reviews into ranked pain clusters. Pay-per-call via x402 micropayments.
Project-URL: Homepage, https://pypi.org/project/feedback-synthesis-mcp/
Project-URL: Repository, https://github.com/sapph1re/feedback-synthesis-mcp
Project-URL: Documentation, https://github.com/sapph1re/feedback-synthesis-mcp#readme
Project-URL: Bug Tracker, https://github.com/sapph1re/feedback-synthesis-mcp/issues
Author: Cortex Labs
License: MIT
License-File: LICENSE
Keywords: app-store,customer-intelligence,feedback,github-issues,hacker-news,mcp,micropayments,pain-points,product-analytics,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: eth-account>=0.13.0
Requires-Dist: fastmcp>=3.2.3
Requires-Dist: requests>=2.32.0
Requires-Dist: x402[evm]>=2.3.0
Description-Content-Type: text/markdown

# Feedback Synthesis MCP

> Customer feedback intelligence for AI agents and developers. Synthesize GitHub Issues, Hacker News threads, and App Store reviews into ranked pain clusters with evidence links. Pay-per-call via x402 micropayments — no signup required.

<!-- mcp-name: io.github.sapph1re/feedback-synthesis-mcp -->

Stop reading through hundreds of feedback items manually. Feedback Synthesis MCP collects from multiple sources, runs a multi-pass LLM pipeline, and returns ranked pain clusters with impact scores, evidence links, and suggested actions — machine-readable for agents, human-readable for founders.

## Quick Start

**Install:**

```bash
pip install feedback-synthesis-mcp
```

**Set your wallet key** (any EVM wallet with USDC on Base mainnet):

```bash
export EVM_PRIVATE_KEY=your_private_key_here
```

**Add to Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "feedback-synthesis-mcp": {
      "command": "feedback-synthesis-mcp",
      "env": {
        "EVM_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}
```

**Add to Cursor** — edit `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "feedback-synthesis-mcp": {
      "command": "feedback-synthesis-mcp",
      "env": {
        "EVM_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}
```

Restart your client. You now have four customer intelligence tools available.

---

## Tools

| Tool | What it does | Price |
|------|-------------|-------|
| `synthesize_feedback` | Multi-source synthesis → ranked pain clusters with evidence | $0.05/call |
| `get_pain_points` | Quick single-source pain point extraction | $0.02/call |
| `search_feedback` | Full-text search across cached feedback items | $0.01/call |
| `get_sentiment_trends` | Time-series sentiment across sources | $0.03/call |

**Supported sources**: GitHub Issues, Hacker News, Apple App Store Reviews

---

## Examples

### Synthesize feedback from multiple sources

```
synthesize_feedback(
  sources=[
    {"type": "github_issues", "target": "owner/my-repo", "labels": ["bug", "feature-request"]},
    {"type": "hackernews", "target": "Show HN: MyProduct"}
  ],
  since="2026-01-01T00:00:00Z"
)
```

Returns:
```json
{
  "job_id": "syn_abc123",
  "status": "completed",
  "summary": "Analyzed 347 feedback items from 2 sources. Found 6 pain clusters.",
  "pain_clusters": [
    {
      "rank": 1,
      "title": "Authentication flow breaks on mobile Safari",
      "severity": "critical",
      "frequency": 23,
      "impact_score": 0.92,
      "description": "Users report inability to complete OAuth login on iOS Safari. Affects onboarding conversion.",
      "evidence": [
        {
          "source": "github",
          "url": "https://github.com/owner/my-repo/issues/142",
          "snippet": "Login fails silently on Safari 17.2+"
        }
      ],
      "suggested_actions": [
        "Fix Safari WebAuthn polyfill (see issue #142)",
        "Add fallback auth flow for mobile browsers"
      ]
    }
  ]
}
```

### Quick pain points from GitHub Issues

```
get_pain_points(
  source={"type": "github_issues", "target": "owner/my-repo", "labels": ["bug"]},
  top_n=5
)
```

### Search for specific topics

```
search_feedback(query="pricing too expensive", sources=["github_issues", "hackernews"])
```

### Track sentiment over time

```
get_sentiment_trends(
  sources=[{"type": "appstore", "target": "com.example.myapp"}],
  since="2025-10-01T00:00:00Z",
  granularity="weekly"
)
```

---

## Payment

This MCP uses [x402 micropayments](https://x402.org) on Base mainnet (USDC). You need:

1. An EVM wallet with USDC on Base mainnet
2. The wallet's private key set as `EVM_PRIVATE_KEY`

Each call costs $0.01–$0.05 USDC. Payments are made automatically — no subscriptions, no API keys.

**No payment configured?** The server returns a helpful error with setup instructions.

---

## Architecture

This package is a thin MCP client. All processing happens on the hosted backend:

```
Your Agent / Claude Desktop
        │
        ▼
feedback-synthesis-mcp (this package)
  - MCP tool definitions
  - x402 payment signing
  - Zero business logic
        │ HTTPS + x402
        ▼
Hosted Backend (Railway)
  - Multi-source data collection
  - 3-stage LLM pipeline (Haiku × N + Sonnet × 1)
  - SQLite caching + FTS search
  - x402 payment verification
```

Server code is private (moat). Thin client is open source.

---

## License

MIT
