shinzo-ts

Installation

pnpm add @shinzolabs/instrumentation-mcp

Usage

For the simplest configuration, just pass in the server name, version, and exporter endpoint:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { instrumentServer, TelemetryConfig } from "@shinzolabs/instrumentation-mcp"

const NAME = "my-mcp-server"
const VERSION = "1.0.0"

const server = new McpServer({
  name: NAME,
  version: VERSION,
  description: "Example MCP server with telemetry"
})

// Use TelemetryConfig to set configuration options
const telemetryConfig: TelemetryConfig = {
  serverName: NAME,
  serverVersion: VERSION,
  exporterEndpoint: "http://localhost:4318/v1" // OpenTelemetry collector endpoint - /trace and /metrics are added automatically
}

// Initialize telemetry
const telemetry = instrumentServer(server, telemetryConfig)

// Add tools using the tool method
server.tool(...)

The TelemetryConfig exposes a number of other options for precise and expansive telemetry processing:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { instrumentServer, TelemetryConfig } from "@shinzolabs/instrumentation-mcp"

const NAME = "my-other-mcp-server"
const VERSION = "1.0.0"

const server = new McpServer({
  name: NAME,
  version: VERSION,
  description: "Example MCP server with telemetry"
})

const telemetryConfig: TelemetryConfig = {
  serviceName: NAME,
  serviceVersion: VERSION,
  exporterEndpoint: "http://localhost:4318/v1", // OpenTelemetry collector endpoint
  exporterAuth: {
    type: "bearer",
    token: process.env.OTEL_AUTH_TOKEN
  },
  enablePIISanitization: false,
  enableTracing: false,
  samplingRate: 0.7,
  dataProcessors: [
    (telemetryData: any) => {
      if (telemetryData['mcp.tool.name'] === "sensitive_operation") {
        for (const key of Object.keys(telemetryData)) {
          if (key.startsWith('mcp.request.argument')) delete telemetryData[key]
        }
      }
      return telemetryData
    }
  ]
}

const telemetry = instrumentServer(server, telemetryConfig)

// Add tools using the tool method
server.tool(...)

Configuration Options

The TelemetryConfig interface provides comprehensive configuration options for customizing telemetry behavior:

TelemetryConfig Properties

Property	Type	Required	Default	Description
serverName	string	✅	-	Name of the MCP server
serverVersion	string	✅	-	Version of the MCP server
exporterEndpoint	string	⚠️	-	OpenTelemetry collector OTLP endpoint URL (required unless using console exporter)
exporterAuth	ExporterAuth	❌	-	Authentication configuration for the exporter
samplingRate	number	❌	1.0	Trace sampling rate (0.0 to 1.0)
metricExportIntervalMs	number	❌	5000	Metric export interval in milliseconds
enablePIISanitization	boolean	❌	true	Enable automatic PII sanitization
enableArgumentCollection	boolean	❌	false	Enable collection of tool arguments in traces
dataProcessors	((data: any) => any)[]	❌	[]	Array of custom data processing functions
exporterType	'otlp-http' | 'otlp-grpc' | 'console'	❌	'otlp-http'	Type of telemetry exporter
enableMetrics	boolean	❌	true	Enable metrics collection
enableTracing	boolean	❌	true	Enable tracing collection
batchTimeoutMs	number	❌	2000	Batch timeout in milliseconds
PIISanitizer	PIISanitizer	❌	-	Custom PII sanitizer instance

ExporterAuth Configuration

The exporterAuth property supports multiple authentication methods:

Auth Type	Properties	Description
bearer	token: string	Bearer token authentication
apiKey	apiKey: string	API key authentication
basic	username: string, password: string	Basic HTTP authentication

Usage Examples

Minimal Configuration

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "http://localhost:4318/v1" // OpenTelemetry collector endpoint
}

Bearer Token Authentication

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.example.com/v1",
  exporterAuth: {
    type: "bearer",
    token: process.env.OTEL_AUTH_TOKEN
  }
}

Custom Data Processing

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "http://localhost:4318/v1", // OpenTelemetry collector endpoint
  dataProcessors: [
    (data) => {
      // Remove sensitive parameters
      if (data['mcp.tool.name'] === 'sensitive_tool') {
        delete data['mcp.request.argument.password']
      }
      return data
    }
  ]
}

Console Development Setup

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "console",
  enableMetrics: false, // Console exporter doesn't support metrics
  samplingRate: 1.0 // Sample all traces in development
}

Contributing

Contributions are welcome! Please see the Contributing Guide in the main repository.

License

This package is distributed under the MIT License.