Usage Scripts

This folder contains working solutions and utilities for MCP sentiment analysis with consistent naming and proper documentation.

🚀 Working Solutions

1. `sentiment_mcp_core_usage.py` ⭐ RECOMMENDED

What it does: Uses smolagents MCPClient for proper MCP protocol connection
Performance: ~0.11 seconds per request (fastest!)
Status: ✅ Works perfectly
Usage: pdm run python usage/sentiment_mcp_core_usage.py
Dependencies: smolagents[mcp] (already installed)
Protocol: Native MCP via smolagents

2. `sentiment_mcp_gradio_usage.py`

What it does: Creates a Gradio UI that connects to MCP sentiment analysis server
Performance: Fast UI-based sentiment analysis
Status: ✅ Works with interactive web interface
Usage: pdm run python usage/sentiment_mcp_gradio_usage.py
Dependencies: smolagents[mcp], gradio[mcp] (already installed)
Protocol: Native MCP via smolagents with Gradio interface

3. `sentiment_gradio_client_usage.py`

What it does: Uses Gradio client to bypass MCP protocol entirely
Performance: ~1.3 seconds per request
Status: ✅ Works reliably as backup solution
Usage: pdm run python usage/sentiment_gradio_client_usage.py
Dependencies: gradio_client (already installed)
Protocol: Direct Gradio API access

🎯 Cursor AI Integration ⭐ BEST EXPERIENCE

The most seamless way to use MCP sentiment analysis is directly within Cursor AI using the built-in MCP support:

Setup

Add this configuration to your Cursor MCP servers (~/.cursor/mcp.json):

{
  "mcpServers": {
    "sentiment-analysis": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://freemansel-mcp-sentiment.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }
  }
}

Usage in Cursor

Once configured, you can directly ask Cursor AI:

"Analyze the sentiment of this text: 'I love this product!'"
"What's the sentiment of: 'This is terrible'"
"Check sentiment: 'It's okay, nothing special'"

Benefits:

✅ No separate scripts needed
✅ Integrated directly in your coding workflow
✅ Real-time sentiment analysis while coding
✅ Works with any text in your editor

🔧 Utilities

4. `debug_imports.py`

What it does: Debugging utility to check MCP package imports
Usage: pdm run python usage/debug_imports.py
Purpose: Troubleshooting import issues
Dependencies: mcp (for testing imports)

Quick Start

For Cursor AI Users (Recommended)

Add the MCP server configuration to ~/.cursor/mcp.json
Restart Cursor AI
Ask Cursor directly for sentiment analysis

For Standalone Usage

# Primary solution (fastest)
pdm run python usage/sentiment_mcp_core_usage.py

# Interactive UI solution
pdm run python usage/sentiment_mcp_gradio_usage.py

# Backup solution (reliable)
pdm run python usage/sentiment_gradio_client_usage.py

For troubleshooting:

# Debug imports if having issues
pdm run python usage/debug_imports.py

Performance Comparison

Solution	Speed	Protocol	Interface	Reliability	Command
Cursor AI MCP	Instant	✅ Native MCP	✅ Integrated	✅ Excellent	Built-in
`sentiment_mcp_core_usage.py`	0.11s	✅ Native MCP	Terminal	✅ Excellent	`pdm run python usage/sentiment_mcp_core_usage.py`
`sentiment_mcp_gradio_usage.py`	Fast	✅ Native MCP	Web UI	✅ Excellent	`pdm run python usage/sentiment_mcp_gradio_usage.py`
`sentiment_gradio_client_usage.py`	1.3s	Direct API	Terminal	✅ Very Good	`pdm run python usage/sentiment_gradio_client_usage.py`

File Naming Convention

All scripts follow a consistent naming pattern:

sentiment_*_usage.py - Main functionality scripts
debug_*.py - Debugging and utility scripts
Each script includes comprehensive docstring with PDM commands

Dependencies

All required packages are already installed:

smolagents[mcp] - For MCP protocol support
gradio_client - For direct Gradio API access
gradio[mcp] - For Gradio UI with MCP integration
mcp - Base MCP package

Troubleshooting

If you encounter issues:

Import errors: Run pdm run python usage/debug_imports.py
MCP connection issues: Try pdm run python usage/sentiment_gradio_client_usage.py
Missing dependencies: Check the Dependencies section above
Cursor AI issues: Verify MCP server configuration in ~/.cursor/mcp.json

📚 Concepts and Technical Details

Model Context Protocol (MCP)

MCP is a protocol that enables AI applications to securely connect to external data sources and tools. In our case, it provides a standardized way to access sentiment analysis capabilities.

Key Benefits:

Standardized Interface: Consistent API across different tools
Security: Controlled access to external resources
Composability: Tools can be combined and chained
Real-time: Live connections to external services

Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client        │    │   MCP Server    │    │  Sentiment      │
│   (Cursor AI,   │◄──►│   (Protocol     │◄──►│  Analysis       │
│   smolagents,   │    │   Handler)      │    │  Engine         │
│   Gradio)       │    │                 │    │  (TextBlob)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Technical Implementation Details

1. smolagents MCPClient

Transport: Server-Sent Events (SSE)
Endpoint: https://freemansel-mcp-sentiment.hf.space/gradio_api/mcp/sse
Protocol: Native MCP with automatic tool discovery
Performance: ~110ms per request

2. Cursor AI Integration

Tool: mcp-remote npm package
Transport: SSE-only mode for reliability
Integration: Native MCP support in Cursor AI
Benefits: Zero-setup sentiment analysis in IDE

3. Gradio Client (Fallback)

Transport: Direct HTTP API calls
Endpoint: https://freemansel-mcp-sentiment.hf.space
Protocol: Gradio's native API (bypasses MCP)
Performance: ~1.3s per request

Sentiment Analysis Engine

The backend uses TextBlob for sentiment analysis, providing:

Polarity: Range from -1 (negative) to +1 (positive)
Subjectivity: Range from 0 (objective) to 1 (subjective)
Assessment: Human-readable sentiment classification

Error Handling and Reliability

Connection Timeouts: Automatic retry mechanisms
Fallback Strategies: Multiple transport methods
Graceful Degradation: Backup solutions when MCP fails
Comprehensive Logging: Detailed error reporting for debugging

The folder is now clean, organized, and ready for production use with multiple integration options! 🎉