Skip to content
reaatechREAATECH

@reaatech/mcp-load-test-core

npm v0.1.0

Provides shared TypeScript types, Zod validation schemas, and utility functions for defining and analyzing MCP load test configurations. It serves as the foundational library for the `@reaatech/mcp-load-test` ecosystem, exporting domain models for load profiles, tool call patterns, and performance metrics.

npm →source →

@reaatech/mcp-load-test-core

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Canonical TypeScript types, Zod schemas, utility functions, and structured logging for the @reaatech/mcp-load-test-* ecosystem. This package is the single source of truth for all MCP load test domain shapes.

Installation

terminal
npm install @reaatech/mcp-load-test-core
# or
pnpm add @reaatech/mcp-load-test-core

Feature Overview

  • 30+ exported types — every domain entity has a TypeScript interface or type alias
  • Zod schemas — runtime validation for all configuration shapes (profiles, patterns, auth, engine options)
  • Utility library — percentile calculation, stats aggregation, retry with backoff, URL validation, timing helpers
  • Structured logging — pre-configured Pino logger with opt-in pretty printing via MCP_LT_PRETTY_LOGS
  • Zero cross-package dependencies — lightweight foundation for the entire ecosystem

Quick Start

typescript
import {
  type LoadProfile,
  type ToolCallPattern,
  type LoadEngineOptions,
  loadEngineOptionsSchema,
} from "@reaatech/mcp-load-test-core";
 
// Define a ramp profile
const profile: LoadProfile = {
  type: "ramp",
  minConcurrency: 1,
  maxConcurrency: 100,
  rampDurationMs: 300000,
  holdDurationMs: 120000,
};
 
// Validate runtime configuration with Zod
const options = loadEngineOptionsSchema.parse({
  endpoint: "https://api.example.com/mcp",
  transport: "http",
  profile,
  patterns: [{ name: "explore-then-act", weight: 1, thinkTimeMs: 100, onStepError: "continue", steps: [{ tool: "tools/list", args: {} }] }],
});

Exports

Domain Types (types/domain.ts)

ExportDescription
GradeLetter grade: A" | "B" | "C" | "D" | "F
TransportTypeTransport protocol: stdio" | "sse" | "http" | "auto
AuthModeAuthentication mode: none" | "api-key" | "bearer" | "oauth
ToolDefinitionMCP tool descriptor with name, description, inputSchema
LatencyMetricsPercentile summary: p50, p90, p95, p99, min, max, mean, samples
ToolLatencyMetricsPer-tool latency with toolName and latency: LatencyMetrics
ErrorSummaryError aggregation: totalErrors, errorRate, breakdowns by category and tool
ThroughputMetricsThroughput snapshot: averageRps, peakRps, success/failure tallies
BreakingPointResultDetection result: detected, concurrencyAtBreak, recoveryTimeMs
BaselineComparisonComparison deltas: grade change, latency/error/throughput deltas
LoadTestReportFull test output: grade, breaking point, latencies, errors, throughput, recommendations

Profile Types

ExportDescription
RampProfileLinear ramp from min → max concurrency
SoakProfileSustained constant-concurrency load
SpikeProfileAlternating baseline/spike cycles
CustomProfileArbitrary concurrency curve via concurrencyCurve
LoadProfileDiscriminated union of all four profile types

Pattern Types

ExportDescription
PatternStepA single tool call: { tool: string; args: Record<string, unknown> }
ToolCallPatternMulti-step sequence with weight, think time, and error policy

Configuration Types

ExportDescription
AuthOptionsAuth configuration for API key, bearer token, or OAuth
LoadEngineOptionsComplete test configuration (endpoint, transport, profile, patterns)
SessionStatePer-session mutable state (id, client, context, counters, status)
MCPClientInterface contract for transport-layer abstraction

Zod Schemas (types/schemas.ts)

Every domain type has a corresponding Zod schema for runtime validation:

SchemaValidates
loadProfileSchemaUnion of rampProfileSchema, soakProfileSchema, spikeProfileSchema, customProfileSchema
toolCallPatternSchemaPattern definition with step count ≥ 1
authOptionsSchemaAuth mode and credentials
loadEngineOptionsSchemaFull test configuration

Utilities (utils/index.ts)

ExportDescription
generateUUID()RFC 9562 UUID v4
generateId()8-character random identifier
now()ISO 8601 UTC timestamp
measureTimeAsync(fn)Wraps an async function and returns { result, durationMs }
sleep(ms)Promise-based delay
retryWithBackoff(fn, maxRetries?, baseDelay?, multiplier?)Exponential backoff retry loop
percentile(sortedValues, p)Interpolated percentile calculation
calculateStats(values)Full stats object (p50/p90/p95/p99/min/max/mean/samples)
isValidURL(value)URL string validation
isPrivateURL(url)RFC 1918 / loopback / link-local detection

Logging (observability/logger.ts)

ExportDescription
loggerPre-configured Pino logger instance. Level controlled by LOG_LEVEL env (default info). Pretty output enabled when MCP_LT_PRETTY_LOGS=1.

Version (version.ts)

ExportDescription
getProgramVersion()Returns the package version from package.json (cached)

Related Packages

License

MIT

All packagesmcp-load-test overview