@cesteral/shared

@cesteral/shared

Shared infrastructure utilities, authentication, and types for Cesteral MCP servers.

Installation

All MCP server packages depend on this package via pnpm workspace protocol (workspace:*). No separate installation is needed.

Modules

Authentication (/auth)

Module	Key Exports	Purpose
auth-strategy.ts	AuthStrategy, AuthInfo, AuthResult, createAuthStrategy()	Pluggable auth strategy factory (google-headers, jwt, none)
bearer-auth-strategy-base.ts	BearerAuthStrategyBase	Abstract base for platform-specific bearer auth (Meta, LinkedIn, TikTok, Pinterest, Snapchat, Amazon DSP, Microsoft Ads)
google-auth.ts	GoogleAuthAdapter, ServiceAccountAuthAdapter, OAuth2RefreshTokenAuthAdapter, parseCredentialsFromHeaders()	Google OAuth2/SA token management with caching
jwt.ts	verifyJwt(), createJwt(), extractBearerToken(), decodeJwtPayload()	JWT verification and creation via jose library

Example: Creating an auth strategy

import { createAuthStrategy } from "@cesteral/shared";

const strategy = createAuthStrategy("jwt", { secretKey: process.env.MCP_AUTH_SECRET_KEY });
const result = await strategy.verify(request.headers);
// result: { authInfo, googleAuthAdapter?, platformAuthAdapter?, credentialFingerprint? }

Utilities (/utils)

Core Infrastructure

Module	Key Exports	Purpose
server-bootstrap.ts	bootstrapMcpServer(), detectTransportMode()	Main orchestrator: OTEL init, stdio/HTTP branching, graceful shutdown
mcp-http-transport-factory.ts	createMcpHttpTransport(), startMcpHttpServer()	Hono-based MCP HTTP transport with CORS, session management, RFC 9728
mcp-transport-helpers.ts	SessionManager, validateSessionReuse(), buildAllowedOrigins()	Session lifecycle, credential fingerprinting, protocol version validation
config-base.ts	BaseConfigSchema, getBaseEnvConfig(), parseConfigWithSchema()	Zod-based environment configuration with defaults

Tool Registration

Module	Key Exports	Purpose
tool-handler-factory.ts	registerToolsFromDefinitions(), ToolDefinitionForFactory	Core factory that eliminates ~90 lines of boilerplate per server. Handles Zod validation, OTEL spans, JWT scope enforcement, interaction logging, response formatting, error handling
prompt-handler-factory.ts	registerPromptsFromDefinitions()	Prompt registration with standardized handling
resource-handler-factory.ts	registerStaticResourcesFromDefinitions()	Static resource registration
zod-helpers.ts	extractZodShape()	Unwraps ZodEffects for MCP SDK registration

Example: Registering tools

import { registerToolsFromDefinitions } from "@cesteral/shared";

registerToolsFromDefinitions({
  server: mcpServer,
  tools: allTools,
  resolveServices: (ctx) => resolveSessionServices(ctx),
  logger,
  rateLimiter,
});

Session Management

Module	Key Exports	Purpose
session-store.ts	SessionServiceStore<T>	Typed Map from sessionId to services with credential fingerprinting
session-resolver.ts	resolveSessionServicesFromStore()	Session lookup with descriptive error on missing sessions

Example: Session store

import { SessionServiceStore } from "@cesteral/shared";

const store = new SessionServiceStore<MyServices>();
store.set(sessionId, services);
const services = resolveSessionServicesFromStore(store, sdkContext);

Networking & HTTP

Module	Key Exports	Purpose
fetch-with-timeout.ts	fetchWithTimeout()	Fetch with AbortController timeout and request ID tracing
retryable-fetch.ts	executeWithRetry()	Exponential backoff on 429/5xx with Retry-After support
download-file.ts	downloadFileToBuffer()	URL-to-buffer download for platform upload tools
multipart-form.ts	buildMultipartFormData()	Multipart/form-data construction for binary file uploads

Rate Limiting

Module	Key Exports	Purpose
rate-limiter.ts	RateLimiter, createPlatformRateLimiter()	In-memory sliding window rate limiter with wildcard pattern support

Example: Rate limiter

import { createPlatformRateLimiter } from "@cesteral/shared";

const limiter = createPlatformRateLimiter("dv360", 100); // 100 req/min
await limiter.consume(sessionId); // throws McpError if rate exceeded

Logging & Errors

Module	Key Exports	Purpose
logger.ts	createLogger()	Pino logger factory with pino-pretty in development
mcp-errors.ts	McpError, JsonRpcErrorCode, ErrorHandler	Structured MCP error handling with JSON-RPC code mapping
request-context.ts	runWithRequestContext(), getRequestContext(), createRequestContext()	AsyncLocalStorage-based request correlation with UUIDs
interaction-logger.ts	InteractionLogger	Append-only JSONL logger with file rotation and optional GCS persistence

Example: Error handling

import { McpError, JsonRpcErrorCode } from "@cesteral/shared";

throw new McpError(JsonRpcErrorCode.NotFound, "Campaign not found", { campaignId });
// Automatically serialized to JSON-RPC error response by the tool factory

Telemetry

Module	Key Exports	Purpose
telemetry.ts	initializeOpenTelemetry(), withToolSpan(), otelLogMixin(), shutdownOpenTelemetry()	OpenTelemetry SDK init with GCP Cloud Run detection, span helpers
metrics.ts	recordToolExecution(), registerActiveSessionsGauge(), recordAuthValidation(), recordRateLimitHit()	Business metrics: tool execution counters/histograms, session gauges, auth/rate-limit counters

Validation & Helpers

Module	Key Exports	Purpose
client-validation-helpers.ts	validateRequiredFields(), checkReadOnlyFields()	Client-side entity validation without API calls
elicitation-helpers.ts	elicitArchiveConfirmation()	User confirmation for irreversible operations
bulk-operation-schemas.ts	BulkOperationResultSchema	Zod schema for bulk operation results

Conformance Testing

Module	Key Exports	Purpose
conformance-echo-tool.ts	conformanceTools	6 test tools (echo, text, logging, elicitation variants) for MCP protocol conformance
conformance-fixtures.ts	conformanceResources, conformancePrompts	Test resources and prompts
tool-examples-resource.ts	createToolExamplesResource(), createServerCapabilitiesResource()	Auto-generated MCP Resources from tool metadata

Types (/types)

Module	Key Exports	Purpose
tool-types.ts	ToolDefinition, SdkContext, ResourceDefinition, ElicitResultLike	Core type definitions for tool/resource registration

Usage

// Import utilities
import { createLogger, McpError, JsonRpcErrorCode } from "@cesteral/shared/utils";

// Import auth
import { createAuthStrategy, verifyJwt } from "@cesteral/shared/auth";

// Or import everything from barrel
import { createLogger, createAuthStrategy, registerToolsFromDefinitions } from "@cesteral/shared";

Context Efficiency Standards

• If a tool defines outputSchema, keep text responses concise and return full payload via structuredContent.
• Avoid embedding large JSON blobs in human-readable text fields.
• Keep tool descriptions short; place detailed workflows in MCP prompts/resources.
• Prefer compact default text formatting in shared tool handlers unless pretty output is explicitly required.

Development

pnpm run build       # Build
pnpm run typecheck   # Type check
pnpm run test        # Test
pnpm run lint        # Lint

Contributing

See root CLAUDE.md for development guidelines, build system details, and monorepo conventions. See the root README for full architecture context.

License

Apache License 2.0 -- see LICENSE for details. This package is part of Cesteral's open-source connector layer; Cesteral Intelligence and higher-level governance features live outside this repository.