Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
mcp-nlp-analytics
Running

App Files Community
mcp-nlp-analytics
File size: 3,935 Bytes 
f120be8
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# Sentiment Evolution Tracker – Hugging Face Space Edition

MCP-powered customer sentiment monitoring packaged for Hugging Face Spaces and local demos.

> Nota: el dashboard Streamlit es opcional y no forma parte del entregable principal. Solo ejecútalo si quieres experimentar con la versión interactiva local.

## 🚀 Launch The Demo (Opcional)

```powershell
streamlit run app.py
```

Open `http://localhost:8501` for the interactive dashboard.

## 📊 Feature Set

### Interactive Dashboard
- Four KPIs (customers, analyses, sentiment, alerts).
- Two charts (churn risk vs. time, sentiment trend).
- Detailed customer table with statuses.

### Deep-Dive Panels
- Select any customer to view historical analyses.
- Inspect sentiment velocity and recommended actions.
- Highlight churn drivers automatically.

### Multi-Customer Trends
- Compare sentiment trajectories across clients.
- Identify shared risk signals.

### MCP Tooling (7 tools)
1. `analyze_sentiment_evolution`
2. `detect_risk_signals`
3. `predict_next_action`
4. `get_customer_history`
5. `get_high_risk_customers`
6. `get_database_statistics`
7. `save_analysis`

## 💻 Local Setup

Requirements: Python 3.10+, pip.

```powershell
git clone https://huggingface.co/spaces/MCP-1st-Birthday/sentiment-tracker
cd mcp-nlp-server
pip install -r requirements.txt
python init_db.py
python tools\populate_demo_data.py
python tools\dashboard.py
python tools\generate_report.py      # opens data/reporte_clientes.html
streamlit run app.py
```

## 🔧 MCP Configuration

1. Edit `config/claude_desktop_config.json`.
2. Point the server entry to `src/mcp_server.py`.
3. Restart Claude Desktop and select the sentiment tracker server.

```json
{
  "mcpServers": {
    "sentiment-tracker": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "cwd": "C:/path/to/mcp-nlp-server"
    }
  }
}
```

## 📈 Use Cases

### 1. Churn Prediction
```
Input → customer ID
Process → trend analysis + risk signals + alerts
Output → alert if risk > 70% with suggested actions
```

### 2. Real-Time Monitoring
```
Dashboard highlights:
- Critical accounts (red)
- At-risk accounts (orange)
- Healthy accounts (green)
Updated whenever new analyses are stored
```

### 3. Executive Reporting
```
Generate the HTML report to share daily:
- Risk charts
- Sentiment evolution
- Top 5 accounts needing attention
- Actionable recommendations
```

### 4. LLM Integration
```
Claude workflow:
→ get_high_risk_customers()
→ get_customer_history()
→ predict_next_action()
→ Respond with urgency, revenue at risk, and next steps
```

## 📊 Sample Dataset

- Five demo customers (manufacturing, tech, retail, healthcare, finance).
- Seventeen conversations across rising/declining/stable trends.
- Alerts triggered automatically when risk exceeds thresholds.

## 🎯 Architecture

```
User / Team Lead
        ↓
Claude Desktop (optional)
        ↓ MCP Protocol (stdio)
Sentiment Tracker Server (7 tools)
        ↓
SQLite Database (customer_profiles, conversations, risk_alerts)
```

## 🔑 Key Advantages

- **Local-first**: keep customer data on-prem.
- **Zero external APIs**: predictable cost, improved privacy.
- **Real-time**: sentiment scoring < 100 ms per request.
- **Predictive**: churn detection 5–7 days ahead.
- **Agentic**: Claude drives the workflow autonomously.
- **Scalable**: handles thousands of customers on commodity hardware.

## 📚 Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Quick Start](docs/QUICK_START.md)
- [Blog Post](../BLOG_POST.md)

## 🤝 Contributions

Suggestions are welcome—open an issue or submit a pull request.

## 📝 License

MIT License.

## 🙏 Acknowledgements

- Anthropic for MCP.
- Hugging Face for the hosting platform.
- TextBlob + NLTK for NLP utilities.

---

Built for the MCP 1st Birthday Hackathon 🎉

[GitHub](https://github.com) • [Blog](../BLOG_POST.md) • [Docs](docs/)