shinzo-ts

Shinzo TS provides OpenTelemetry-compatible instrumentation for MCP servers written in TypeScript. By integrating the Shinzo instrumentation, you gain visibility into how your MCP tools are used, how long operations take, and how calls propagate across components. The SDK offers a straightforward way to initialize telemetry for your MCP server, configure exporters, and optionally sanitize or customize the data carried in traces and metrics. You can enable or disable tracing and metrics, attach authentication for exporters, and supply custom data processors to shape telemetry before it leaves your process. Use the provided server wrapper to register tools and instrument their usage with telemetry colocated to your MCP server runtime.

Typical workflow:

• Install the Shinzo MCP instrumentation package.
• Create or initialize your MCP server instance as shown in the examples.
• Configure a TelemetryConfig to point to your OpenTelemetry collector or console exporter.
• Call instrumentServer(server, telemetryConfig) to enable telemetry around your server's tool invocations.
• Use server.tool(...) to register and instrument each MCP tool you expose.

This setup allows you to observe tool usage, capture stack traces or spans for tool calls, and collect metrics for performance monitoring across platforms.

Prerequisites:

• Node.js (recommended LTS) installed
• npm or pnpm to manage packages

Installation steps:

1. Install the Shinzo MCP instrumentation package:

pnpm add @shinzolabs/instrumentation-mcp

If you prefer npm:

npm install @shinzolabs/instrumentation-mcp

2. Ensure you have an OpenTelemetry collector or endpoint to export traces and metrics. If you are developing locally, you can start a local collector or use a console exporter for development:

// Example TelemetryConfig export type (in your code file):
export const telemetryConfig = {
  serverName: NAME,
  serverVersion: VERSION,
  exporterEndpoint: "http://localhost:4318/v1"
}

3. Instrument your MCP server according to the usage examples in the README and the SDK docs. Place instrumentation initialization early in server startup so all tool invocations are captured.

4. Run your MCP server as you normally would (node or your preferred runner). Ensure environmental variables for your exporter (e.g., OTEL_EXPORTER_ENDPOINT) are set if you’re using a remote collector.

Tips and common issues:

• Ensure the exporterEndpoint is reachable from your runtime. If using a bearer token, provide OTEL_AUTH_TOKEN in your environment.
• If you enable enablePIISanitization, personal data in traces will be sanitized automatically. You can override with a custom dataProcessors function.
• Console exporters (exporterType: 'console') do not support metrics; disable metrics in development if you’re using the console exporter.
• When deploying to production, consider tuning the samplingRate, batchTimeoutMs, and export intervals to balance telemetry fidelity with performance.
• If you encounter missing tool data, verify that tools are registered via server.tool(...) before instrumented calls are made.