MCP Agent Tracker

# MCP Agent Tracker A Model Context Protocol (MCP) server that automatically tracks client-agent conversations without requiring any user interaction. ## Features ### 🗣️ **Automatic Conversation Tracking** - **Zero User Interaction Required**: All conversations are tracked automatically - **Client Request Logging**: Every client prompt/request is logged - **Agent Response Logging**: Every agent response is captured - **Complete Conversation Turns**: Full request-response pairs are recorded - **Session Management**: Automatic session creation and tracking ### 🔧 **MCP Tools Available** - `get_current_weather(city)`: Get weather information for a city - `agent_interaction(prompt)`: Interact with the agent - `get_interaction_history(limit, session_id)`: Retrieve conversation history - `get_conversation_summary(session_id)`: Get conversation statistics and patterns ### 📊 **Automatic Monitoring** - **Background Health Checks**: Continuous system monitoring every 5 minutes - **Automatic Metadata Collection**: System info, process details, uptime - **Error Tracking**: Comprehensive error logging and recovery - **Performance Metrics**: Execution times and system health ## How It Works ### 1. **Automatic Session Creation** ```python # Sessions are created automatically when the server starts # No user input required logger.get_or_create_session() ``` ### 2. **Client Request Tracking** ```python # Every client request is automatically logged logger.log_client_request(f"Get weather for {city}") ``` ### 3. **Agent Response Tracking** ```python # Every agent response is automatically captured logger.log_agent_response(response) ``` ### 4. **Complete Conversation Logging** ```python # Full conversation turns are recorded logger.log_conversation_turn( client_request=f"Get weather for {city}", agent_response=response ) ``` ### 5. **Background Monitoring** ```python # System health is monitored continuously # No user interaction needed def background_monitoring(): while True: logger.log_interaction(interaction_type='health_check', ...) time.sleep(Config.MONITORING_INTERVAL_SECONDS) ``` ## Configuration ### Environment Variables ```bash # Enable/disable features ENABLE_BACKGROUND_MONITORING=true MONITORING_INTERVAL_SECONDS=300 ENABLE_AUTOMATIC_METADATA=true # Database and logging DATABASE_URL= DB_PATH=./data/agent_tracker.db LOG_LEVEL=INFO ``` ### Configuration Options - **`ENABLE_BACKGROUND_MONITORING`**: Enable continuous system monitoring - **`MONITORING_INTERVAL_SECONDS`**: How often to run health checks (default: 300s) - **`ENABLE_AUTOMATIC_METADATA`**: Collect system info automatically ## Database Schema ### AgentInteraction Table ```sql CREATE TABLE agent_interactions ( id INTEGER PRIMARY KEY, timestamp TIMESTAMP, session_id VARCHAR(255), user_id VARCHAR(255), interaction_type VARCHAR(100), -- 'client_request', 'agent_response', 'conversation_turn' prompt TEXT, -- Client request response TEXT, -- Agent response status VARCHAR(50), error_message TEXT, meta_data JSON -- Automatic system metadata ); ``` ### Session Table ```sql CREATE TABLE sessions ( id VARCHAR(255) PRIMARY KEY, user_id VARCHAR(255), started_at TIMESTAMP, last_activity TIMESTAMP, total_interactions INTEGER, meta_data JSON ); ``` ## Usage Examples ### Basic Conversation Tracking ```python @mcp.tool() def my_tool(prompt: str) -> str: # Client request is automatically logged logger.log_client_request(prompt) # Process the request response = process_request(prompt) # Agent response is automatically logged logger.log_agent_response(response) # Complete conversation turn is recorded logger.log_conversation_turn(prompt, response) return response ``` ### Getting Conversation History ```python # Get recent conversations history = get_interaction_history(limit=10) # Get conversation summary summary = get_conversation_summary() ``` ## Security Features - **Environment Variables**: All configuration via environment variables - **No Hardcoded Secrets**: Secure credential management - **Isolated Database Schema**: Separate schema for tracking data - **Error Isolation**: Logging failures don't break main functionality ## Getting Started 1. **Copy environment file**: ```bash cp env.example .env ``` 2. **Configure your environment**: ```bash # Edit .env with your settings ENABLE_BACKGROUND_MONITORING=true MONITORING_INTERVAL_SECONDS=300 ``` 3. **Run the server**: ```bash python main.py ``` 4. **Monitor conversations**: ```bash # Use the MCP tools to interact and track conversations ``` ## 🚀 Using in Cursor ### Prerequisites - **Cursor IDE** installed on your system - **Python 3.8+** with pip/uv package management - **Git** for cloning the repository ### Step 1: Setup MCP Server 1. **Clone and navigate to your project**: ```bash cd /path/to/your/mcp/project ``` 2. **Install dependencies**: ```bash # Using pip pip install -r requirements.txt # Or using uv (recommended) uv sync ``` 3. **Configure environment**: ```bash cp env.example .env # Edit .env with your preferred settings ``` ### Step 2: Configure Cursor for MCP 1. **Open Cursor Settings**: - Press `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux) - Or go to `Cursor → Preferences → Settings` 2. **Add MCP Configuration**: ```json { "mcpServers": { "mcp-project": { "command": "python", "args": ["/absolute/path/to/your/project/main.py"], "env": { "PYTHONPATH": "/absolute/path/to/your/project" } } } } ``` 3. **Alternative: Use relative paths** (if Cursor is opened in project directory): ```json { "mcpServers": { "mcp-project": { "command": "python", "args": ["./main.py"] } } } ``` ### Step 3: Test MCP Integration 1. **Restart Cursor** after adding MCP configuration 2. **Open Command Palette** (`Cmd+Shift+P` or `Ctrl+Shift+P`) 3. **Type "MCP"** to see available MCP commands 4. **Test a tool**: - Use `get_current_weather("New York")` to test weather functionality - Use `agent_interaction("Hello, how are you?")` to test conversation tracking - Use `get_system_status()` to check system health ### Step 4: Use MCP Tools in Cursor #### Available Tools - **`get_current_weather(city)`**: Get weather for any city - **`agent_interaction(prompt)`**: Interact with the agent and track conversations - **`get_interaction_history(limit, session_id)`**: View conversation history - **`get_conversation_summary(session_id)`**: Get conversation analytics - **`get_system_status()`**: Check system health and configuration - **`test_conversation_tracking(message)`**: Test the tracking system #### Example Usage in Cursor 1. **Open Command Palette** (`Cmd+Shift+P`) 2. **Type MCP command**: ``` MCP: mcp-project: get_current_weather ``` 3. **Enter parameters** when prompted: ``` city: San Francisco ``` 4. **View results** in the output panel ### Step 5: Monitor and Debug #### View Conversation History ```bash # In Cursor terminal or via MCP tools python -c " from main import get_interaction_history print(get_interaction_history(limit=5)) " ``` #### Check System Status ```bash # Via MCP tools in Cursor get_system_status() ``` #### Test Conversation Tracking ```bash # Via MCP tools in Cursor test_conversation_tracking("Test message from Cursor") ``` ### Troubleshooting #### Common Issues 1. **"MCP server not found"**: - Check the absolute path in your Cursor settings - Ensure the Python path is correct - Verify the server is running 2. **"Import errors"**: - Check `PYTHONPATH` in MCP configuration - Ensure all dependencies are installed - Verify you're in the correct directory 3. **"Permission denied"**: - Make sure `main.py` is executable - Check file permissions - Try running with `python3` instead of `python` #### Debug Commands ```bash # Test MCP server directly python main.py # Check dependencies pip list | grep mcp # Verify configuration python -c "from config import Config; print(Config.ENVIRONMENT)" ``` ### Advanced Configuration #### Custom MCP Server Names ```json { "mcpServers": { "my-custom-mcp": { "command": "python", "args": ["./main.py"], "env": { "ENVIRONMENT": "development", "LOG_LEVEL": "DEBUG" } } } } ``` #### Multiple MCP Servers ```json { "mcpServers": { "mcp-project": { "command": "python", "args": ["./main.py"] }, "another-mcp": { "command": "python", "args": ["./other_mcp.py"] } } } ``` ### Benefits in Cursor ✅ **Seamless Integration**: Use MCP tools directly in your IDE ✅ **Real-time Monitoring**: Track conversations as you work ✅ **Debugging Tools**: Built-in testing and monitoring functions ✅ **Performance Insights**: Monitor system health and usage ✅ **Conversation Analytics**: Analyze interaction patterns ✅ **Zero Configuration**: Automatic setup and tracking Your MCP server will now be fully integrated with Cursor, providing powerful conversation tracking and monitoring capabilities right in your development environment! ## What Gets Tracked Automatically ✅ **Client Requests**: Every prompt, question, or request ✅ **Agent Responses**: Every response, answer, or action ✅ **Conversation Flow**: Complete request-response pairs ✅ **System Health**: Background monitoring and metrics ✅ **Error Handling**: All errors and exceptions ✅ **Session Data**: User sessions and activity ✅ **Metadata**: System info, timestamps, environment ❌ **Tool Usage**: Internal MCP tool executions are not tracked ❌ **User Input**: No manual logging required ❌ **Configuration**: Automatic setup and management The system is designed to be completely hands-off - once started, it will track all client-agent conversations automatically without any intervention needed.