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

Related MCP server: Dominion Observatory

How It Works

1. Automatic Session Creation

# Sessions are created automatically when the server starts
# No user input required
logger.get_or_create_session()

2. Client Request Tracking

# Every client request is automatically logged
logger.log_client_request(f"Get weather for {city}")

3. Agent Response Tracking

# Every agent response is automatically captured
logger.log_agent_response(response)

4. Complete Conversation Logging

# Full conversation turns are recorded
logger.log_conversation_turn(
    client_request=f"Get weather for {city}",
    agent_response=response
)

5. Background Monitoring

# 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

# 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

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

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

@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

# 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:

   cp env.example .env

2. Configure your environment:

   # Edit .env with your settings
   ENABLE_BACKGROUND_MONITORING=true
   MONITORING_INTERVAL_SECONDS=300

3. Run the server:

   python main.py

4. Monitor conversations:

   # 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:

   cd /path/to/your/mcp/project

2. Install dependencies:

   # Using pip
   pip install -r requirements.txt
   
   # Or using uv (recommended)
   uv sync

3. Configure environment:

   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:

   {
     "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):

   {
     "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

# In Cursor terminal or via MCP tools
python -c "
from main import get_interaction_history
print(get_interaction_history(limit=5))
"

Check System Status

# Via MCP tools in Cursor
get_system_status()

Test Conversation Tracking

# 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

# 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

{
  "mcpServers": {
    "my-custom-mcp": {
      "command": "python",
      "args": ["./main.py"],
      "env": {
        "ENVIRONMENT": "development",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Multiple MCP Servers

{
  "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.