Vantage Telemetry MCP Server

A Model Context Protocol (MCP) server that captures and exposes usage, cost, productivity, and activity metrics for local-first software engineering teams.

It functions as the telemetry agent on a developer's machine, running in the background while plugged into an MCP-capable client (like VS Code/Cline, Cursor, Claude Code, or Windsurf).

---

🚀 Key Features

• Usage Analytics: Tracks prompts, assistant response lengths, and token usage.
• Cost Analytics: Integrates with Vantage Harness to display estimated cloud LLM costs vs. actual costs and net local-routing savings.
• Productivity Metrics: Monitors active typing session intervals, file additions/deletions, and code lines added/deleted in real-time.
• Audit Logs: Maintains a secure, local developer activity trail (file edits, command runs, git actions).
• Self-Bootstrapping: Automatically installs required Python packages (mcp, watchdog, psutil, httpx) on first startup.

Telemetry event contract and privacy

Events use an additive versioned envelope (schemaVersion, eventId, occurredAt, deviceId, sessionId, workspaceId, collectionMethod) while retaining the legacy flat fields consumed by Vantage Harness. Secrets and machine-specific absolute paths are filtered before local persistence or network delivery. Failed deliveries remain in ~/.vantage/telemetry_outbox.jsonl and retry with bounded exponential backoff.

Filesystem events deliberately use editOrigin: unknown; only an IDE-specific source such as Cursor's scored-commit database may claim AI/human attribution, and every attribution includes its source and confidence.

---

🛠️ Architecture

       VS Code / Cursor / Cline / Claude Code
                         |
                         v (stdio / JSON-RPC)
               +-------------------+
               |   Telemetry MCP   | <---+ Watches Workspace File Changes
               +-------------------+       and Git Branch & Commit logs
                 /               \
                /                 \
               v                   v
      Local JSONL File    Vantage Harness Gateway
  (~/.vantage/telemetry.jsonl)   (http://localhost:50123/v1/telemetry)

---

⚙️ Configuration in IDEs

1. VS Code (Cline)

The client setup.ps1 script automatically registers this server in VS Code's Cline configuration file (cline_mcp_settings.json).

To configure it manually, add the following entry to your Cline settings:

{
  "mcpServers": {
    "vantage-telemetry": {
      "command": "python",
      "args": [
        "d:/root/projects/vantage-telemetry-mcp/server.py"
      ],
      "env": {
        "VANTAGE_WORKSPACE_DIR": "d:/root/projects/vantage-client"
      },
      "disabled": false
    }
  }
}

2. Cursor

1. Go to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Configure the fields:
   • Name: vantage-telemetry
   • Type: stdio
   • Command: python d:/root/projects/vantage-telemetry-mcp/server.py
4. If you wish to set a specific workspace path, launch Cursor from the command line after setting the environment variable:

   $env:VANTAGE_WORKSPACE_DIR="C:/path/to/your/project"
   cursor .
   

3. Claude Code (CLI)

Add the server definition to your ~/.claude.json configuration file:

{
  "mcpServers": {
    "vantage-telemetry": {
      "command": "python",
      "args": ["d:/root/projects/vantage-telemetry-mcp/server.py"],
      "env": {
        "VANTAGE_WORKSPACE_DIR": "d:/root/projects/vantage-client"
      }
    }
  }
}

---

🛠️ Exposed MCP Tools

The telemetry server registers several tools that can be invoked by AI agents or developers to log events or request local metrics:

1. Logging Tools

• log_usage_analytics(model, prompt_tokens, completion_tokens, duration_ms): Record custom LLM invocation usage.
• log_cost_analytics(estimated_cost_usd, actual_cost_usd, savings_usd, route, model): Log AI routing financial savings.
• log_productivity_metrics(task_id, status, lines_added, lines_deleted, details): Track progress of specific development task IDs.
• log_audit_log(action, target, status, details): Manually write to the developer activity trail.

2. Querying & Reporting Tools

• get_telemetry_summary(): Returns a comprehensive markdown dashboard showing total logs, LLM token spending, local routing savings rates, coding metrics (lines written vs deleted), and recent activities.
• get_productivity_report(period): Get detailed coding speeds and list of touched files for 'today', 'week', or 'all'.
• get_cost_report(): Returns an overview of total LLM calls, local-handling ratio, estimated baseline cloud spend, actual spend, and net savings.
• get_audit_trail(limit): Displays a list of recent files modified, Git operations, and active sessions.

---

📁 File Locations

• Shared Config: ~/.vantage/config.json (defines harness URL, user ID, team ID, and optional API key).
• Local Telemetry Log: ~/.vantage/telemetry.jsonl (contains the raw JSONL list of all tracked events).
• Cursor watcher state: ~/.vantage/cursor_watcher_state.json (SQLite poll cursor + per-requestId debounce timestamps).

Composer telemetry spam

Cursor multi-root workspaces start one MCP server per folder, which used to duplicate cursor_usage POSTs to the harness. The watcher now uses a process lock (~/.vantage/cursor_db_watcher.lock) so only one instance polls Cursor’s ai_code_hashes table, aggregates hashes by requestId, and debounces (default 60s, VANTAGE_CURSOR_USAGE_INTERVAL_SEC).

After upgrading this repo, run Developer: Reload Window in Cursor so the MCP process reloads. New events include hashCount and a details summary; bare fileName-only lines indicate a stale MCP process still running old code.