@hopperd-sdk/core

Analytics and instrumentation for MCP servers with automatic user intent capture.

Installation

npm install @hopperd-sdk/core

Quick Start (Recommended)

One line of code to track all your tools with automatic user intent capture:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { track } from '@hopperd-sdk/core'
import { z } from 'zod'

// Create your MCP server
const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
})

track(server, {
  apiKey: process.env.HOPPERD_API_KEY,
  serverName: 'my-server',
})

server.tool(
  'get-weather',
  'Get weather forecast',
  {
    location: z.string().describe('Location to get weather for'),
  },
  async ({ location }) => {
    // Your tool logic here
    const weather = await getWeatherData(location)
    return {
      content: [
        {
          type: 'text',
          text: `Weather in ${location}: ${weather}`,
        },
      ],
    }
  },
)

// All tools are now automatically tracked!

How It Works

The track() function automatically:

1. Enhances tool schemas with a _context parameter
2. Captures user intent - AI explains why the tool was called
3. Tracks everything - params, results, errors, duration
4. Keeps tools clean - handlers receive params without _context

When an AI assistant calls your tool, it automatically provides context:

{
  "location": "New York",
  "_context": "User wants to check weather conditions before planning outdoor activities"
}

This context is captured as "user intent" in your analytics!

Configuration

track(server, {
  apiKey: 'hopp_your_api_key',
  serverName: 'my-mcp-server',
})

Required:

• apiKey - Your Hopperd API key
• serverName - Name to identify this server in analytics

What Gets Tracked

Every tool call captures:

• Tool name and server name
• Full parameters (JSON)
• User intent - AI's explanation of why the tool was called
• Results - Complete tool output (JSON)
• Errors - Full error messages and stack traces
• Duration - Execution time in milliseconds
• Timestamps - When tools are invoked

All tracking is done asynchronously and will not impact your MCP server performance.

Key Benefits

• ✅ One-line setup - No manual tool wrapping
• ✅ Automatic user intent - Understand why users call your tools
• ✅ Full debugging data - Complete params, results, and errors
• ✅ Zero tool changes - Tools work exactly as before
• ✅ Transparent operation - Handlers receive clean parameters