docs/README.md

Sentiment Evolution Tracker – MCP Server Guide

This reference explains how to set up, operate, and extend the Sentiment Evolution Tracker. The system integrates with Claude Desktop via the Model Context Protocol (MCP) and provides persistent sentiment analytics, churn prediction, and portfolio reporting.

Sections

• Overview
• Feature Highlights
• Installation
• Operating Checklist
• MCP Tool Contracts
• Data Model
• Troubleshooting
• Roadmap & Licensing

---

Overview

Claude excels at single-session analysis but forgets historical context. Sentiment Evolution Tracker solves this gap with an MCP server that:

• Stores customer interactions and analyses in SQLite.
• Detects sentiment trends (rising, declining, stable).
• Calculates churn probability and surfaces alerts above configurable thresholds.
• Provides dashboards and MCP tools for portfolio-level insights.

Feature Highlights

• Lightweight NLP pipeline (TextBlob + NLTK) for real-time scoring.
• Risk signal detection (pricing pressure, competitor mentions, frustration).
• Next-best-action recommendation (CHURN / ESCALATION / RESOLUTION / MONITOR_CLOSELY).
• Seven MCP tools covering analytics and data retrieval.
• Deterministic demo dataset for rehearsed demos or recordings.
• CLI utilities: ASCII dashboard, HTML report generator, database viewers.

Installation

cd mcp-nlp-server
pip install -r requirements.txt
python -m textblob.download_corpora
python -m nltk.downloader punkt averaged_perceptron_tagger

Register the MCP server in %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "sentiment-tracker": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "cwd": "C:/Users/Ruben Reyes/Desktop/MCP_1stHF/mcp-nlp-server"
    }
  }
}

Restart Claude Desktop after saving the configuration.

Operating Checklist

python init_db.py                     # reset database (optional)
python tools\populate_demo_data.py   # load deterministic sample data
python tools\dashboard.py            # check ASCII KPIs (Ctrl+C to exit)
python tools\generate_report.py      # build data/reporte_clientes.html
python src\mcp_server.py             # start MCP server for Claude

Once the server is running, Claude Desktop surfaces the tools automatically.

MCP Tool Contracts

Tool	Purpose
analyze_sentiment_evolution	Scores each message 0–100 and labels the overall trend.
detect_risk_signals	Surfaces pricing pressure, competitor mentions, frustration phrases.
predict_next_action	Suggests the most likely outcome (churn, escalation, resolution, monitor).
get_customer_history	Returns profile data, interaction history, and open alerts.
get_high_risk_customers	Lists customers whose churn risk exceeds a threshold.
get_database_statistics	Provides portfolio KPIs (totals, active alerts, average sentiment).
save_analysis	Persists user-specified analysis results with metadata for future queries.

Data Model

Table	Description
customer_profiles	Aggregated metrics per customer, including lifetime sentiment and churn risk.
conversations	Each stored analysis with timestamps, trends, predicted actions, confidence.
risk_alerts	Alerts generated when risk or thresholds exceed configured limits.

Troubleshooting

• Claude cannot find the MCP server – Verify the absolute path in claude_desktop_config.json and restart Claude Desktop after editing.
• Import errors or missing modules – Ensure the virtual environment uses Python 3.10+ and rerun pip install -r requirements.txt.
• No demo data appears – Execute python init_db.py followed by python tools\populate_demo_data.py.
• Sentiment results feel off – Provide at least three customer utterances and include relevant context or escalation history.

Roadmap & Licensing

• Transformer-based sentiment and emotion tagging.
• Realtime alert delivery via Slack or email.
• Optional REST API for external integrations.
• Expanded multilingual support and PDF/CSV export routines.

The project is released under the MIT License (LICENSE).

Maintainer: Rubén Reyes · November 2025 · Version 1.0.0