@clerk/mcp-tools

Provides strongly-typed boilerplate and utilities for building MCP servers in TypeScript, handling the protocol handshake, request/response serialization, and lifecycle management. Uses TypeScript generics and discriminated unions to enforce type safety across tool definitions, resource handlers, and prompt templates, reducing runtime errors and enabling IDE autocomplete for MCP protocol compliance.

Abstracts MCP client creation across multiple transport layers (stdio, HTTP, WebSocket) and LLM providers (OpenAI, Anthropic, custom), handling connection pooling, reconnection logic, and provider-specific capability negotiation. Uses a factory pattern with pluggable transport adapters and provider-specific message formatters to normalize tool calling across different LLM APIs.

Validates tool definitions against MCP schema specifications and converts between MCP tool schemas and provider-specific formats (OpenAI function calling, Anthropic tool use). Uses JSON Schema validation with custom error messages and provides bidirectional converters that preserve parameter constraints, descriptions, and required fields across format boundaries.

Automatically injects Clerk user/organization context into MCP request messages and extracts it from responses, enabling MCP servers to access authenticated user data without explicit token passing. Implements context middleware that intercepts MCP calls, enriches them with Clerk session tokens and user metadata, and validates responses against Clerk permissions.

Provides TypeScript interfaces and decorators for defining MCP resources (files, documents, data) and prompt templates with compile-time type checking. Uses discriminated unions and generic constraints to ensure resource handlers return correct types and prompt templates have valid variable substitution, with IDE autocomplete for resource URIs and template variables.

Wraps MCP tool handlers with automatic error catching, serialization, and protocol-compliant error responses. Converts JavaScript/TypeScript exceptions into MCP error objects with proper error codes, messages, and optional stack traces, and validates that all responses conform to MCP protocol specifications before sending.

Supports deploying the same MCP server across multiple transport layers (stdio for local processes, HTTP for REST-like access, WebSocket for bidirectional streaming) using a transport-agnostic server implementation. Uses adapter pattern to normalize message handling across transports and provides configuration for each transport's specific requirements (port binding, CORS, authentication).

Caches tool execution results with configurable time-to-live (TTL) and cache key generation based on tool name and parameters. Uses in-memory or Redis-backed storage (configurable) to avoid redundant tool invocations when the same parameters are requested multiple times, with cache invalidation hooks for tools that produce time-sensitive results.

Provides structured logging middleware that captures MCP request/response pairs, tool execution times, errors, and authentication events. Integrates with popular logging libraries (Winston, Pino, Bunyan) and exports metrics in OpenTelemetry format for integration with observability platforms (Datadog, New Relic, Prometheus).