@openconductor/mcp-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenConductor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# @openconductor/mcp-sdk
+
+The standard SDK for building production-ready MCP servers. Stop copy-pasting boilerplate — get error handling, validation, logging, and telemetry out of the box.
+
+[![npm version](https://badge.fury.io/js/%40openconductor%2Fmcp-sdk.svg)](https://www.npmjs.com/package/@openconductor/mcp-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why?
+
+Every MCP server needs the same things:
+- **Error handling** that follows JSON-RPC 2.0 spec
+- **Input validation** that doesn't suck
+- **Structured logging** for debugging and observability
+- **Telemetry** to know what's actually happening in production
+
+This SDK gives you all of that in ~15kb, with zero config required.
+
+## Install
+
+```bash
+npm install @openconductor/mcp-sdk
+```
+
+## Quick Start
+
+```typescript
+import { 
+  wrapTool, 
+  validateInput, 
+  z, 
+  createLogger,
+  createHealthCheck,
+  initTelemetry 
+} from '@openconductor/mcp-sdk'
+
+// Optional: Enable telemetry (free tier available)
+initTelemetry({
+  apiKey: 'oc_xxx',
+  serverName: 'my-mcp-server',
+  serverVersion: '1.0.0'
+})
+
+// Create a validated, wrapped tool in seconds
+const searchTool = wrapTool(
+  validateInput(
+    z.object({
+      query: z.string().min(1),
+      limit: z.number().int().positive().default(10)
+    }),
+    async (input) => {
+      // Your logic here — input is typed and validated
+      return { results: [] }
+    }
+  ),
+  { name: 'search', timeout: 5000 }
+)
+
+// Automatic error handling, logging, and telemetry!
+const result = await searchTool({ query: 'hello', limit: 5 })
+```
+
+## Features
+
+### Error Handling
+
+Clean, JSON-RPC 2.0 compliant errors with detailed context:
+
+```typescript
+import { ValidationError, ToolNotFoundError, MCPError } from '@openconductor/mcp-sdk/errors'
+
+// Throw structured errors
+throw new ValidationError('amount', 'Must be a positive integer', -5)
+
+// Automatically formatted as JSON-RPC error:
+// {
+//   code: -32602,
+//   message: "Validation failed for 'amount': Must be a positive integer",
+//   data: { field: "amount", reason: "Must be a positive integer", value: -5 }
+// }
+```
+
+**Available Errors:**
+- `ValidationError` — Invalid input parameters
+- `ToolNotFoundError` — Requested tool doesn't exist
+- `ToolExecutionError` — Tool failed during execution
+- `ResourceNotFoundError` — Resource URI not found
+- `AuthenticationError` — Auth required or failed
+- `AuthorizationError` — Not permitted
+- `RateLimitError` — Too many requests
+- `TimeoutError` — Operation timed out
+- `DependencyError` — External dependency unavailable
+- `ConfigurationError` — Invalid server config
+
+### Validation
+
+Zod-powered validation with MCP-specific helpers:
+
+
+```typescript
+import { validate, validateInput, z, schemas } from '@openconductor/mcp-sdk/validate'
+
+// Use built-in schemas for common patterns
+const schema = z.object({
+  query: schemas.nonEmptyString,
+  limit: schemas.limit,        // 1-100, defaults to 10
+  offset: schemas.offset,      // >= 0, defaults to 0
+  email: schemas.email,
+  url: schemas.url,
+})
+
+// Validate manually
+const data = validate(schema, userInput)
+
+// Or wrap your handler for automatic validation
+const handler = validateInput(schema, async (input) => {
+  // input is fully typed!
+  return doSomething(input)
+})
+```
+
+### Logging
+
+Structured JSON logging that works with any log aggregator:
+
+```typescript
+import { createLogger } from '@openconductor/mcp-sdk/logger'
+
+const log = createLogger('my-server', { 
+  level: 'info',    // 'debug' | 'info' | 'warn' | 'error'
+  pretty: true      // Pretty print for local dev
+})
+
+log.info('Tool invoked', { tool: 'search', userId: 'abc' })
+// {"timestamp":"2025-01-19T...","level":"info","service":"my-server","message":"Tool invoked","tool":"search","userId":"abc"}
+
+// Create scoped child loggers
+const toolLog = log.child({ tool: 'search', requestId: 'req_123' })
+toolLog.info('Processing query')
+// All logs include tool and requestId automatically
+```
+
+### Server Utilities
+
+Health checks and tool wrappers:
+
+```typescript
+import { createHealthCheck, wrapTool } from '@openconductor/mcp-sdk/server'
+
+// Standard health check endpoint
+const healthCheck = createHealthCheck({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+  uptime: () => process.uptime(),
+  checks: {
+    database: async () => db.ping(),
+    redis: async () => redis.ping(),
+  }
+})
+
+// Returns:
+// {
+//   status: 'healthy',
+//   name: 'my-mcp-server',
+//   version: '1.0.0',
+//   uptime: 3600,
+//   timestamp: '2025-01-19T...',
+//   checks: { database: true, redis: true }
+// }
+
+// Wrap tools with automatic error handling, logging, timeouts, and telemetry
+const safeTool = wrapTool(myHandler, {
+  name: 'my-tool',
+  timeout: 5000,  // Auto-timeout after 5s
+})
+```
+
+### Telemetry
+
+Optional observability for your MCP servers:
+
+```typescript
+import { initTelemetry } from '@openconductor/mcp-sdk/telemetry'
+
+// Initialize once at startup
+initTelemetry({
+  apiKey: 'oc_xxx',           // Get free key at openconductor.dev
+  serverName: 'my-server',
+  serverVersion: '1.0.0',
+  debug: true                  // Log telemetry events locally
+})
+
+// That's it! All wrapped tools automatically report:
+// - Invocation counts
+// - Success/failure rates
+// - Latency percentiles (p50, p95, p99)
+// - Error messages
+```
+
+**What gets sent:**
+- Tool names and call counts
+- Execution duration
+- Success/failure status
+- Error messages (not stack traces)
+- SDK and Node.js version
+
+**What never gets sent:**
+- Tool inputs or outputs
+- User data
+- Request/response bodies
+
+## Tree-Shakeable Imports
+
+Import only what you need:
+
+```typescript
+// Full SDK
+import { z, validate, wrapTool, createLogger } from '@openconductor/mcp-sdk'
+
+// Or specific modules
+import { ValidationError } from '@openconductor/mcp-sdk/errors'
+import { z, validate } from '@openconductor/mcp-sdk/validate'
+import { createLogger } from '@openconductor/mcp-sdk/logger'
+import { wrapTool } from '@openconductor/mcp-sdk/server'
+import { initTelemetry } from '@openconductor/mcp-sdk/telemetry'
+```
+
+## License
+
+MIT © [OpenConductor](https://openconductor.dev)

package/dist/errors/index.d.mts

@@ -0,0 +1,114 @@
+/**
+ * JSON-RPC 2.0 Standard Error Codes
+ * https://www.jsonrpc.org/specification#error_object
+ */
+declare const ErrorCodes: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly TOOL_NOT_FOUND: -32001;
+    readonly TOOL_EXECUTION_ERROR: -32002;
+    readonly RESOURCE_NOT_FOUND: -32003;
+    readonly AUTHENTICATION_ERROR: -32004;
+    readonly AUTHORIZATION_ERROR: -32005;
+    readonly RATE_LIMIT_ERROR: -32006;
+    readonly TIMEOUT_ERROR: -32007;
+    readonly VALIDATION_ERROR: -32008;
+    readonly DEPENDENCY_ERROR: -32009;
+    readonly CONFIGURATION_ERROR: -32010;
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * Base error class for MCP servers
+ * Formats errors according to JSON-RPC 2.0 specification
+ */
+declare class MCPError extends Error {
+    readonly code: ErrorCode;
+    readonly data?: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, data?: Record<string, unknown>);
+    /**
+     * Returns JSON-RPC 2.0 formatted error object
+     */
+    toJSON(): {
+        data?: Record<string, unknown> | undefined;
+        code: ErrorCode;
+        message: string;
+    };
+    /**
+     * Create error response for JSON-RPC
+     */
+    toResponse(id?: string | number | null): {
+        jsonrpc: "2.0";
+        id: string | number | null;
+        error: {
+            data?: Record<string, unknown> | undefined;
+            code: ErrorCode;
+            message: string;
+        };
+    };
+}
+/**
+ * Thrown when tool input validation fails
+ */
+declare class ValidationError extends MCPError {
+    constructor(field: string, reason: string, value?: unknown);
+}
+/**
+ * Thrown when a requested tool doesn't exist
+ */
+declare class ToolNotFoundError extends MCPError {
+    constructor(toolName: string);
+}
+/**
+ * Thrown when tool execution fails
+ */
+declare class ToolExecutionError extends MCPError {
+    constructor(toolName: string, reason: string, cause?: Error);
+}
+/**
+ * Thrown when a requested resource doesn't exist
+ */
+declare class ResourceNotFoundError extends MCPError {
+    constructor(resourceUri: string);
+}
+/**
+ * Thrown when authentication fails
+ */
+declare class AuthenticationError extends MCPError {
+    constructor(reason?: string);
+}
+/**
+ * Thrown when authorization fails (authenticated but not permitted)
+ */
+declare class AuthorizationError extends MCPError {
+    constructor(action: string, resource?: string);
+}
+/**
+ * Thrown when rate limits are exceeded
+ */
+declare class RateLimitError extends MCPError {
+    constructor(retryAfterMs?: number);
+}
+/**
+ * Thrown when an operation times out
+ */
+declare class TimeoutError extends MCPError {
+    constructor(operation: string, timeoutMs: number);
+}
+/**
+ * Thrown when a required dependency is unavailable
+ */
+declare class DependencyError extends MCPError {
+    constructor(dependency: string, reason: string);
+}
+/**
+ * Thrown when server configuration is invalid
+ */
+declare class ConfigurationError extends MCPError {
+    constructor(setting: string, reason: string);
+}
+
+export { AuthenticationError, AuthorizationError, ConfigurationError, DependencyError, type ErrorCode, ErrorCodes, MCPError, RateLimitError, ResourceNotFoundError, TimeoutError, ToolExecutionError, ToolNotFoundError, ValidationError };

package/dist/errors/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * JSON-RPC 2.0 Standard Error Codes
+ * https://www.jsonrpc.org/specification#error_object
+ */
+declare const ErrorCodes: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly TOOL_NOT_FOUND: -32001;
+    readonly TOOL_EXECUTION_ERROR: -32002;
+    readonly RESOURCE_NOT_FOUND: -32003;
+    readonly AUTHENTICATION_ERROR: -32004;
+    readonly AUTHORIZATION_ERROR: -32005;
+    readonly RATE_LIMIT_ERROR: -32006;
+    readonly TIMEOUT_ERROR: -32007;
+    readonly VALIDATION_ERROR: -32008;
+    readonly DEPENDENCY_ERROR: -32009;
+    readonly CONFIGURATION_ERROR: -32010;
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * Base error class for MCP servers
+ * Formats errors according to JSON-RPC 2.0 specification
+ */
+declare class MCPError extends Error {
+    readonly code: ErrorCode;
+    readonly data?: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, data?: Record<string, unknown>);
+    /**
+     * Returns JSON-RPC 2.0 formatted error object
+     */
+    toJSON(): {
+        data?: Record<string, unknown> | undefined;
+        code: ErrorCode;
+        message: string;
+    };
+    /**
+     * Create error response for JSON-RPC
+     */
+    toResponse(id?: string | number | null): {
+        jsonrpc: "2.0";
+        id: string | number | null;
+        error: {
+            data?: Record<string, unknown> | undefined;
+            code: ErrorCode;
+            message: string;
+        };
+    };
+}
+/**
+ * Thrown when tool input validation fails
+ */
+declare class ValidationError extends MCPError {
+    constructor(field: string, reason: string, value?: unknown);
+}
+/**
+ * Thrown when a requested tool doesn't exist
+ */
+declare class ToolNotFoundError extends MCPError {
+    constructor(toolName: string);
+}
+/**
+ * Thrown when tool execution fails
+ */
+declare class ToolExecutionError extends MCPError {
+    constructor(toolName: string, reason: string, cause?: Error);
+}
+/**
+ * Thrown when a requested resource doesn't exist
+ */
+declare class ResourceNotFoundError extends MCPError {
+    constructor(resourceUri: string);
+}
+/**
+ * Thrown when authentication fails
+ */
+declare class AuthenticationError extends MCPError {
+    constructor(reason?: string);
+}
+/**
+ * Thrown when authorization fails (authenticated but not permitted)
+ */
+declare class AuthorizationError extends MCPError {
+    constructor(action: string, resource?: string);
+}
+/**
+ * Thrown when rate limits are exceeded
+ */
+declare class RateLimitError extends MCPError {
+    constructor(retryAfterMs?: number);
+}
+/**
+ * Thrown when an operation times out
+ */
+declare class TimeoutError extends MCPError {
+    constructor(operation: string, timeoutMs: number);
+}
+/**
+ * Thrown when a required dependency is unavailable
+ */
+declare class DependencyError extends MCPError {
+    constructor(dependency: string, reason: string);
+}
+/**
+ * Thrown when server configuration is invalid
+ */
+declare class ConfigurationError extends MCPError {
+    constructor(setting: string, reason: string);
+}
+
+export { AuthenticationError, AuthorizationError, ConfigurationError, DependencyError, type ErrorCode, ErrorCodes, MCPError, RateLimitError, ResourceNotFoundError, TimeoutError, ToolExecutionError, ToolNotFoundError, ValidationError };

package/dist/errors/index.js

@@ -0,0 +1,159 @@
+'use strict';
+
+// src/errors/codes.ts
+var ErrorCodes = {
+  // JSON-RPC 2.0 Standard Errors
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  // MCP-Specific Errors (-32000 to -32099 reserved for implementation)
+  TOOL_NOT_FOUND: -32001,
+  TOOL_EXECUTION_ERROR: -32002,
+  RESOURCE_NOT_FOUND: -32003,
+  AUTHENTICATION_ERROR: -32004,
+  AUTHORIZATION_ERROR: -32005,
+  RATE_LIMIT_ERROR: -32006,
+  TIMEOUT_ERROR: -32007,
+  VALIDATION_ERROR: -32008,
+  DEPENDENCY_ERROR: -32009,
+  CONFIGURATION_ERROR: -32010
+};
+
+// src/errors/index.ts
+var MCPError = class extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "MCPError";
+    this.code = code;
+    this.data = data;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Returns JSON-RPC 2.0 formatted error object
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.data && { data: this.data }
+    };
+  }
+  /**
+   * Create error response for JSON-RPC
+   */
+  toResponse(id = null) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: this.toJSON()
+    };
+  }
+};
+var ValidationError = class extends MCPError {
+  constructor(field, reason, value) {
+    super(ErrorCodes.INVALID_PARAMS, `Validation failed for '${field}': ${reason}`, {
+      field,
+      reason,
+      ...value !== void 0 && { value }
+    });
+    this.name = "ValidationError";
+  }
+};
+var ToolNotFoundError = class extends MCPError {
+  constructor(toolName) {
+    super(ErrorCodes.TOOL_NOT_FOUND, `Tool '${toolName}' not found`, {
+      tool: toolName
+    });
+    this.name = "ToolNotFoundError";
+  }
+};
+var ToolExecutionError = class extends MCPError {
+  constructor(toolName, reason, cause) {
+    super(ErrorCodes.TOOL_EXECUTION_ERROR, `Tool '${toolName}' failed: ${reason}`, {
+      tool: toolName,
+      reason,
+      ...cause && { cause: cause.message }
+    });
+    this.name = "ToolExecutionError";
+  }
+};
+var ResourceNotFoundError = class extends MCPError {
+  constructor(resourceUri) {
+    super(ErrorCodes.RESOURCE_NOT_FOUND, `Resource '${resourceUri}' not found`, {
+      uri: resourceUri
+    });
+    this.name = "ResourceNotFoundError";
+  }
+};
+var AuthenticationError = class extends MCPError {
+  constructor(reason = "Authentication required") {
+    super(ErrorCodes.AUTHENTICATION_ERROR, reason);
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends MCPError {
+  constructor(action, resource) {
+    const msg = resource ? `Not authorized to ${action} on '${resource}'` : `Not authorized to ${action}`;
+    super(ErrorCodes.AUTHORIZATION_ERROR, msg, {
+      action,
+      ...resource && { resource }
+    });
+    this.name = "AuthorizationError";
+  }
+};
+var RateLimitError = class extends MCPError {
+  constructor(retryAfterMs) {
+    super(ErrorCodes.RATE_LIMIT_ERROR, "Rate limit exceeded", {
+      ...retryAfterMs && { retryAfterMs }
+    });
+    this.name = "RateLimitError";
+  }
+};
+var TimeoutError = class extends MCPError {
+  constructor(operation, timeoutMs) {
+    super(ErrorCodes.TIMEOUT_ERROR, `Operation '${operation}' timed out after ${timeoutMs}ms`, {
+      operation,
+      timeoutMs
+    });
+    this.name = "TimeoutError";
+  }
+};
+var DependencyError = class extends MCPError {
+  constructor(dependency, reason) {
+    super(ErrorCodes.DEPENDENCY_ERROR, `Dependency '${dependency}' unavailable: ${reason}`, {
+      dependency,
+      reason
+    });
+    this.name = "DependencyError";
+  }
+};
+var ConfigurationError = class extends MCPError {
+  constructor(setting, reason) {
+    super(ErrorCodes.CONFIGURATION_ERROR, `Invalid configuration '${setting}': ${reason}`, {
+      setting,
+      reason
+    });
+    this.name = "ConfigurationError";
+  }
+};
+
+exports.AuthenticationError = AuthenticationError;
+exports.AuthorizationError = AuthorizationError;
+exports.ConfigurationError = ConfigurationError;
+exports.DependencyError = DependencyError;
+exports.ErrorCodes = ErrorCodes;
+exports.MCPError = MCPError;
+exports.RateLimitError = RateLimitError;
+exports.ResourceNotFoundError = ResourceNotFoundError;
+exports.TimeoutError = TimeoutError;
+exports.ToolExecutionError = ToolExecutionError;
+exports.ToolNotFoundError = ToolNotFoundError;
+exports.ValidationError = ValidationError;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/codes.ts","../../src/errors/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * JSON-RPC 2.0 Standard Error Codes\n * https://www.jsonrpc.org/specification#error_object\n */\nexport const ErrorCodes = {\n  // JSON-RPC 2.0 Standard Errors\n  PARSE_ERROR: -32700,\n  INVALID_REQUEST: -32600,\n  METHOD_NOT_FOUND: -32601,\n  INVALID_PARAMS: -32602,\n  INTERNAL_ERROR: -32603,\n\n  // MCP-Specific Errors (-32000 to -32099 reserved for implementation)\n  TOOL_NOT_FOUND: -32001,\n  TOOL_EXECUTION_ERROR: -32002,\n  RESOURCE_NOT_FOUND: -32003,\n  AUTHENTICATION_ERROR: -32004,\n  AUTHORIZATION_ERROR: -32005,\n  RATE_LIMIT_ERROR: -32006,\n  TIMEOUT_ERROR: -32007,\n  VALIDATION_ERROR: -32008,\n  DEPENDENCY_ERROR: -32009,\n  CONFIGURATION_ERROR: -32010,\n} as const\n\nexport type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]\n","import { ErrorCodes, type ErrorCode } from './codes'\n\nexport { ErrorCodes, type ErrorCode } from './codes'\n\n/**\n * Base error class for MCP servers\n * Formats errors according to JSON-RPC 2.0 specification\n */\nexport class MCPError extends Error {\n  public readonly code: ErrorCode\n  public readonly data?: Record<string, unknown>\n\n  constructor(\n    code: ErrorCode,\n    message: string,\n    data?: Record<string, unknown>\n  ) {\n    super(message)\n    this.name = 'MCPError'\n    this.code = code\n    this.data = data\n\n    // Maintains proper stack trace in V8 environments\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor)\n    }\n  }\n\n  /**\n   * Returns JSON-RPC 2.0 formatted error object\n   */\n  toJSON() {\n    return {\n      code: this.code,\n      message: this.message,\n      ...(this.data && { data: this.data }),\n    }\n  }\n\n  /**\n   * Create error response for JSON-RPC\n   */\n  toResponse(id: string | number | null = null) {\n    return {\n      jsonrpc: '2.0' as const,\n      id,\n      error: this.toJSON(),\n    }\n  }\n}\n\n/**\n * Thrown when tool input validation fails\n */\nexport class ValidationError extends MCPError {\n  constructor(field: string, reason: string, value?: unknown) {\n    super(ErrorCodes.INVALID_PARAMS, `Validation failed for '${field}': ${reason}`, {\n      field,\n      reason,\n      ...(value !== undefined && { value }),\n    })\n    this.name = 'ValidationError'\n  }\n}\n\n/**\n * Thrown when a requested tool doesn't exist\n */\nexport class ToolNotFoundError extends MCPError {\n  constructor(toolName: string) {\n    super(ErrorCodes.TOOL_NOT_FOUND, `Tool '${toolName}' not found`, {\n      tool: toolName,\n    })\n    this.name = 'ToolNotFoundError'\n  }\n}\n\n/**\n * Thrown when tool execution fails\n */\nexport class ToolExecutionError extends MCPError {\n  constructor(toolName: string, reason: string, cause?: Error) {\n    super(ErrorCodes.TOOL_EXECUTION_ERROR, `Tool '${toolName}' failed: ${reason}`, {\n      tool: toolName,\n      reason,\n      ...(cause && { cause: cause.message }),\n    })\n    this.name = 'ToolExecutionError'\n  }\n}\n\n/**\n * Thrown when a requested resource doesn't exist\n */\nexport class ResourceNotFoundError extends MCPError {\n  constructor(resourceUri: string) {\n    super(ErrorCodes.RESOURCE_NOT_FOUND, `Resource '${resourceUri}' not found`, {\n      uri: resourceUri,\n    })\n    this.name = 'ResourceNotFoundError'\n  }\n}\n\n/**\n * Thrown when authentication fails\n */\nexport class AuthenticationError extends MCPError {\n  constructor(reason: string = 'Authentication required') {\n    super(ErrorCodes.AUTHENTICATION_ERROR, reason)\n    this.name = 'AuthenticationError'\n  }\n}\n\n/**\n * Thrown when authorization fails (authenticated but not permitted)\n */\nexport class AuthorizationError extends MCPError {\n  constructor(action: string, resource?: string) {\n    const msg = resource\n      ? `Not authorized to ${action} on '${resource}'`\n      : `Not authorized to ${action}`\n    super(ErrorCodes.AUTHORIZATION_ERROR, msg, {\n      action,\n      ...(resource && { resource }),\n    })\n    this.name = 'AuthorizationError'\n  }\n}\n\n/**\n * Thrown when rate limits are exceeded\n */\nexport class RateLimitError extends MCPError {\n  constructor(retryAfterMs?: number) {\n    super(ErrorCodes.RATE_LIMIT_ERROR, 'Rate limit exceeded', {\n      ...(retryAfterMs && { retryAfterMs }),\n    })\n    this.name = 'RateLimitError'\n  }\n}\n\n/**\n * Thrown when an operation times out\n */\nexport class TimeoutError extends MCPError {\n  constructor(operation: string, timeoutMs: number) {\n    super(ErrorCodes.TIMEOUT_ERROR, `Operation '${operation}' timed out after ${timeoutMs}ms`, {\n      operation,\n      timeoutMs,\n    })\n    this.name = 'TimeoutError'\n  }\n}\n\n/**\n * Thrown when a required dependency is unavailable\n */\nexport class DependencyError extends MCPError {\n  constructor(dependency: string, reason: string) {\n    super(ErrorCodes.DEPENDENCY_ERROR, `Dependency '${dependency}' unavailable: ${reason}`, {\n      dependency,\n      reason,\n    })\n    this.name = 'DependencyError'\n  }\n}\n\n/**\n * Thrown when server configuration is invalid\n */\nexport class ConfigurationError extends MCPError {\n  constructor(setting: string, reason: string) {\n    super(ErrorCodes.CONFIGURATION_ERROR, `Invalid configuration '${setting}': ${reason}`, {\n      setting,\n      reason,\n    })\n    this.name = 'ConfigurationError'\n  }\n}\n"]}