Type Definitions

Complete TypeScript type definitions for OmniMCP, ensuring type safety across your MCP integrations.

Core Types

Client Types

// Client configuration
interface ClientInfo {
  name: string;
  version: string;
}

interface ClientCapabilities {
  experimental?: Record<string, any>;
  sampling?: Record<string, any>;
}

// Server information
interface ServerInfo {
  name: string;
  version: string;
  protocolVersion: string;
  capabilities: ServerCapabilities;
}

interface ServerCapabilities {
  experimental?: Record<string, any>;
  logging?: Record<string, any>;
  prompts?: {
    listChanged?: boolean;
  };
  resources?: {
    subscribe?: boolean;
    listChanged?: boolean;
  };
  tools?: {
    listChanged?: boolean;
  };
}

Transport Types

type TransportType = 'stdio' | 'http' | 'sse' | string;

interface TransportConfig {
  type: TransportType;
  options: any;
}

interface StdioTransportConfig {
  type: 'stdio';
  options: {
    command: string;
    args?: string[];
    env?: Record<string, string>;
    cwd?: string;
    shell?: boolean | string;
    timeout?: number;
    windowsHide?: boolean;
  };
}

interface HTTPTransportConfig {
  type: 'http';
  options: {
    url: string | URL;
    headers?: Record<string, string>;
    auth?: AuthOptions;
    query?: Record<string, string>;
  };
}

interface SSETransportConfig {
  type: 'sse';
  options: {
    url: string | URL;
    headers?: Record<string, string>;
    lastEventId?: string;
    retry?: number;
  };
}

type AuthOptions = 
  | { username: string; password: string }
  | { bearer: string }
  | { apiKey: string };

Protocol Types

Tool Types

interface Tool {
  name: string;
  description?: string;
  inputSchema: ToolInputSchema;
}

interface ToolInputSchema {
  type: 'object';
  properties?: Record<string, JSONSchema>;
  required?: string[];
  additionalProperties?: boolean;
}

interface CallToolRequest {
  name: string;
  arguments?: Record<string, any>;
  _meta?: Record<string, any>;
}

interface CallToolResult {
  content: Array<TextContent | ImageContent | EmbeddedResource>;
  isError?: boolean;
  _meta?: Record<string, any>;
}

Resource Types

interface Resource {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
}

interface ReadResourceRequest {
  uri: string;
}

interface ReadResourceResult {
  contents: Array<TextResourceContents | BlobResourceContents>;
}

interface TextResourceContents {
  uri: string;
  mimeType?: string;
  text: string;
}

interface BlobResourceContents {
  uri: string;
  mimeType?: string;
  blob: string; // base64 encoded
}

interface ResourceUpdatedNotification {
  uri: string;
}

Prompt Types

interface Prompt {
  name: string;
  description?: string;
  arguments?: PromptArgument[];
}

interface PromptArgument {
  name: string;
  description?: string;
  required?: boolean;
}

interface GetPromptRequest {
  name: string;
  arguments?: Record<string, string>;
}

interface GetPromptResult {
  description?: string;
  messages: PromptMessage[];
}

interface PromptMessage {
  role: 'user' | 'assistant';
  content: TextContent | ImageContent | EmbeddedResource;
}

Content Types

interface TextContent {
  type: 'text';
  text: string;
}

interface ImageContent {
  type: 'image';
  data: string;      // base64 encoded
  mimeType: string;
}

interface EmbeddedResource {
  type: 'resource';
  resource: TextResourceContents | BlobResourceContents;
}

type Content = TextContent | ImageContent | EmbeddedResource;

Request/Response Types

JSON-RPC Types

interface JSONRPCRequest {
  jsonrpc: '2.0';
  method: string;
  params?: any;
  id: string | number;
}

interface JSONRPCResponse {
  jsonrpc: '2.0';
  result?: any;
  error?: JSONRPCError;
  id: string | number;
}

interface JSONRPCError {
  code: number;
  message: string;
  data?: any;
}

interface JSONRPCNotification {
  jsonrpc: '2.0';
  method: string;
  params?: any;
}

Method Types

// Initialize
interface InitializeRequest {
  protocolVersion: string;
  capabilities: ClientCapabilities;
  clientInfo: ClientInfo;
}

interface InitializeResult {
  protocolVersion: string;
  capabilities: ServerCapabilities;
  serverInfo: ServerInfo;
}

// Tool methods
interface ListToolsRequest {
  cursor?: string;
}

interface ListToolsResult {
  tools: Tool[];
  nextCursor?: string;
}

// Resource methods
interface ListResourcesRequest {
  cursor?: string;
}

interface ListResourcesResult {
  resources: Resource[];
  nextCursor?: string;
}

// Prompt methods
interface ListPromptsRequest {
  cursor?: string;
}

interface ListPromptsResult {
  prompts: Prompt[];
  nextCursor?: string;
}

Error Types

// Base error class
class MCPError extends Error {
  errorCode: string;
  context: ErrorContext;
  retryable: boolean;
  
  constructor(
    message: string,
    errorCode: string,
    context?: ErrorContext,
    retryable?: boolean
  );
  
  getUserMessage(): string;
  getDebugInfo(): object;
}

interface ErrorContext {
  timestamp: Date;
  operation?: string;
  transport?: string;
  serverInfo?: ServerInfo;
  request?: any;
  response?: any;
  retryCount?: number;
  [key: string]: any;
}

// Specific error types
class ConnectionError extends MCPError {
  constructor(message: string, context?: ErrorContext);
}

class TimeoutError extends MCPError {
  timeout: number;
  constructor(message: string, timeout: number, context?: ErrorContext);
}

class ValidationError extends MCPError {
  validationErrors: ValidationIssue[];
  constructor(
    message: string, 
    validationErrors: ValidationIssue[], 
    context?: ErrorContext
  );
}

interface ValidationIssue {
  path: string;
  message: string;
  value?: any;
}

class AuthenticationError extends MCPError {
  constructor(message: string, context?: ErrorContext);
}

class RateLimitError extends MCPError {
  retryAfter?: number;
  constructor(
    message: string, 
    retryAfter?: number, 
    context?: ErrorContext
  );
}

Event Types

interface MCPClientEvents {
  // Connection events
  connected: (serverInfo: ServerInfo) => void;
  disconnected: (reason?: string) => void;
  error: (error: MCPError) => void;
  
  // Protocol events
  notification: (method: string, params: any) => void;
  toolsChanged: () => void;
  resourcesChanged: () => void;
  promptsChanged: () => void;
  
  // Resource events
  resourceUpdated: (uri: string) => void;
}

// Type-safe event emitter
interface TypedEventEmitter<T> {
  on<K extends keyof T>(event: K, listener: T[K]): this;
  off<K extends keyof T>(event: K, listener: T[K]): this;
  emit<K extends keyof T>(
    event: K,
    ...args: Parameters<T[K]>
  ): boolean;
}

AI Integration Types

interface AIProviderConfig {
  provider: 'openai' | 'anthropic' | string;
  apiKey: string;
  baseURL?: string;
  defaultModel?: string;
  defaultSystemPrompt?: string;
}

interface AIQueryOptions {
  model?: string;
  temperature?: number;
  maxTokens?: number;
  systemPrompt?: string;
  messages?: ChatMessage[];
  stream?: boolean;
  tools?: string[];
  toolChoice?: 'auto' | 'none' | { type: 'tool'; name: string };
  
  // Callbacks
  onToken?: (token: string) => void;
  onToolCall?: (tool: string, args: any) => void;
  onError?: (error: Error, tool?: string) => string | void;
}

interface ChatMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  name?: string;
  tool_call_id?: string;
  tool_calls?: ToolCall[];
}

interface ToolCall {
  id: string;
  type: 'function';
  function: {
    name: string;
    arguments: string;
  };
}

Utility Types

// JSON Schema types
type JSONSchema = 
  | NullSchema
  | BooleanSchema
  | NumberSchema
  | StringSchema
  | ArraySchema
  | ObjectSchema;

interface BaseSchema {
  description?: string;
  default?: any;
  examples?: any[];
}

interface NullSchema extends BaseSchema {
  type: 'null';
}

interface BooleanSchema extends BaseSchema {
  type: 'boolean';
}

interface NumberSchema extends BaseSchema {
  type: 'number' | 'integer';
  minimum?: number;
  maximum?: number;
  exclusiveMinimum?: number;
  exclusiveMaximum?: number;
  multipleOf?: number;
}

interface StringSchema extends BaseSchema {
  type: 'string';
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  format?: string;
  enum?: string[];
}

interface ArraySchema extends BaseSchema {
  type: 'array';
  items?: JSONSchema;
  minItems?: number;
  maxItems?: number;
  uniqueItems?: boolean;
}

interface ObjectSchema extends BaseSchema {
  type: 'object';
  properties?: Record<string, JSONSchema>;
  required?: string[];
  additionalProperties?: boolean | JSONSchema;
  minProperties?: number;
  maxProperties?: number;
}

// Retry options
interface RetryOptions {
  maxAttempts?: number;
  initialDelay?: number;
  maxDelay?: number;
  backoffFactor?: number;
  jitter?: boolean;
  shouldRetry?: (error: any, attempt: number) => boolean;
  onRetry?: (attempt: number, error: any, delay: number) => void;
}

// Deep partial type
type DeepPartial<T> = T extends object ? {
  [P in keyof T]?: DeepPartial<T[P]>;
} : T;

// Promisable type
type Promisable<T> = T | Promise<T>;

Type Guards

// Error type guards
function isConnectionError(error: any): error is ConnectionError {
  return error instanceof ConnectionError;
}

function isTimeoutError(error: any): error is TimeoutError {
  return error instanceof TimeoutError;
}

function isValidationError(error: any): error is ValidationError {
  return error instanceof ValidationError;
}

// Content type guards
function isTextContent(content: Content): content is TextContent {
  return content.type === 'text';
}

function isImageContent(content: Content): content is ImageContent {
  return content.type === 'image';
}

function isEmbeddedResource(content: Content): content is EmbeddedResource {
  return content.type === 'resource';
}

// Transport config type guards
function isStdioConfig(config: TransportConfig): config is StdioTransportConfig {
  return config.type === 'stdio';
}

function isHTTPConfig(config: TransportConfig): config is HTTPTransportConfig {
  return config.type === 'http';
}

function isSSEConfig(config: TransportConfig): config is SSETransportConfig {
  return config.type === 'sse';
}

Next Steps

• Review client API
• See transport implementations
• Explore usage examples