README_SPACE.md

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)

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.

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.

{
  "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
• Quick Start
• Blog Post

🤝 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 • Blog • Docs