@mcp-ts/sdk 1.0.0

package/src/shared/events.ts

@@ -0,0 +1,166 @@
+/**
+ * Simple event emitter pattern for MCP connection events
+ * Inspired by Cloudflare's agents pattern but adapted for serverless
+ */
+
+export type Disposable = {
+  dispose(): void;
+};
+
+export type Event<T> = (listener: (event: T) => void) => Disposable;
+
+/**
+ * Event emitter class for type-safe event handling
+ * Similar to Cloudflare's Emitter but simplified for our use case
+ */
+export class Emitter<T> {
+  private listeners: Set<(event: T) => void> = new Set();
+
+  /**
+   * Subscribe to events
+   * @param listener - Callback function to handle events
+   * @returns Disposable to unsubscribe
+   */
+  get event(): Event<T> {
+    return (listener: (event: T) => void) => {
+      this.listeners.add(listener);
+      return {
+        dispose: () => {
+          this.listeners.delete(listener);
+        },
+      };
+    };
+  }
+
+  /**
+   * Fire an event to all listeners
+   * @param event - Event data to emit
+   */
+  fire(event: T): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error('[Emitter] Error in event listener:', error);
+      }
+    }
+  }
+
+  /**
+   * Clear all listeners
+   */
+  dispose(): void {
+    this.listeners.clear();
+  }
+
+  /**
+   * Get number of active listeners
+   */
+  get listenerCount(): number {
+    return this.listeners.size;
+  }
+}
+
+/**
+ * Connection state types matching your existing ConnectionStatus
+ * Extended with more granular states for better observability
+ */
+export type McpConnectionState =
+  | 'DISCONNECTED'      // Not connected
+  | 'CONNECTING'        // Establishing transport connection to MCP server
+  | 'AUTHENTICATING'    // OAuth flow in progress
+  | 'AUTHENTICATED'     // OAuth complete, pre-connect
+  | 'DISCOVERING'       // Discovering server capabilities (tools, resources, prompts)
+  | 'CONNECTED'         // Transport connection established
+  | 'READY'             // Fully connected and ready to use
+  | 'VALIDATING'        // Validating existing session
+  | 'RECONNECTING'      // Attempting to reconnect
+  | 'INITIALIZING'      // Initializing session or connection
+  | 'FAILED';           // Connection error at some point
+
+/**
+ * MCP Connection Event Types
+ * Discriminated union for type-safe event handling
+ */
+export type McpConnectionEvent =
+  | {
+    type: 'state_changed';
+    sessionId: string;
+    serverId: string;
+    serverName: string;
+    state: McpConnectionState;
+    previousState: McpConnectionState;
+    timestamp: number;
+  }
+  | {
+    type: 'tools_discovered';
+    sessionId: string;
+    serverId: string;
+    toolCount: number;
+    tools: any[];
+    timestamp: number;
+  }
+  | {
+    type: 'auth_required';
+    sessionId: string;
+    serverId: string;
+    authUrl: string;
+    timestamp: number;
+  }
+  | {
+    type: 'error';
+    sessionId: string;
+    serverId: string;
+    error: string;
+    errorType: 'connection' | 'auth' | 'validation' | 'unknown';
+    timestamp: number;
+  }
+  | {
+    type: 'disconnected';
+    sessionId: string;
+    serverId: string;
+    reason?: string;
+    timestamp: number;
+  }
+  | {
+    type: 'progress';
+    sessionId: string;
+    serverId: string;
+    message: string;
+    timestamp: number;
+  };
+
+/**
+ * Observability event for debugging and monitoring
+ */
+export interface McpObservabilityEvent {
+  type?: string;
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  message?: string;
+  displayMessage?: string;
+  sessionId?: string;
+  serverId?: string;
+  payload?: Record<string, any>;
+  metadata?: Record<string, any>; // Kept for backward compatibility
+  timestamp: number;
+  id?: string;
+}
+
+/**
+ * DisposableStore for managing multiple disposables
+ * Useful for cleanup in React hooks
+ */
+export class DisposableStore {
+  private disposables: Set<Disposable> = new Set();
+
+  add(disposable: Disposable): void {
+    this.disposables.add(disposable);
+  }
+
+  dispose(): void {
+    for (const disposable of this.disposables) {
+      disposable.dispose();
+    }
+    this.disposables.clear();
+  }
+}

package/src/shared/index.ts

@@ -0,0 +1,70 @@
+/**
+ * MCP Redis Shared Package
+ * Shared types and utilities for both server and client
+ */
+
+// Events
+export {
+  Emitter,
+  DisposableStore,
+  type Disposable,
+  type Event,
+  type McpConnectionState,
+  type McpConnectionEvent,
+  type McpObservabilityEvent,
+} from './events';
+
+// Constants
+export * from './constants';
+
+// Errors
+export * from './errors';
+
+// Types
+export type {
+  ToolInfo,
+  McpRpcRequest,
+  McpRpcResponse,
+  McpRpcMethod,
+  McpRpcParams,
+  TransportType,
+  // API types
+  ConnectRequest,
+  ConnectResponse,
+  ConnectSuccessResponse,
+  ConnectAuthRequiredResponse,
+  ConnectErrorResponse,
+  ListToolsResponse,
+  CallToolRequest,
+  CallToolResponse,
+  // RPC param types
+  ConnectParams,
+  DisconnectParams,
+  SessionParams,
+  CallToolParams,
+  GetPromptParams,
+  ReadResourceParams,
+  FinishAuthParams,
+  // RPC result types
+  SessionInfo,
+  SessionListResult,
+  ConnectResult,
+  DisconnectResult,
+  RestoreSessionResult,
+  FinishAuthResult,
+  ListToolsRpcResult,
+  ListPromptsResult,
+  ListResourcesResult,
+} from './types';
+
+export {
+  isConnectSuccess,
+  isConnectAuthRequired,
+  isConnectError,
+  isListToolsSuccess,
+  isCallToolSuccess,
+} from './types';
+
+// Utilities
+export { sanitizeServerLabel } from './utils';
+

package/src/shared/types.ts

@@ -0,0 +1,274 @@
+/**
+ * Type definitions for MCP operations
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+// Connect API types
+export interface ConnectRequest {
+  serverUrl: string;
+  callbackUrl: string;
+}
+
+export interface ConnectSuccessResponse {
+  success: true;
+  sessionId: string;
+}
+
+export interface ConnectAuthRequiredResponse {
+  requiresAuth: true;
+  authUrl: string;
+  sessionId: string;
+}
+
+export interface ConnectErrorResponse {
+  error: string;
+}
+
+export type ConnectResponse =
+  | ConnectSuccessResponse
+  | ConnectAuthRequiredResponse
+  | ConnectErrorResponse;
+
+// Callback API types
+export interface CallbackSuccessResponse {
+  success: true;
+  message: string;
+}
+
+export interface CallbackErrorResponse {
+  error: string;
+}
+
+export type CallbackResponse = CallbackSuccessResponse | CallbackErrorResponse;
+
+// Disconnect API types
+export interface DisconnectRequest {
+  sessionId: string;
+}
+
+export interface DisconnectSuccessResponse {
+  success: true;
+  message: string;
+}
+
+export interface DisconnectErrorResponse {
+  error: string;
+}
+
+export type DisconnectResponse =
+  | DisconnectSuccessResponse
+  | DisconnectErrorResponse;
+
+// List Tools API types
+export interface ListToolsSuccessResponse {
+  tools: Tool[];
+}
+
+export interface ListToolsErrorResponse {
+  error: string;
+}
+
+export type ListToolsResponse =
+  | ListToolsSuccessResponse
+  | ListToolsErrorResponse;
+
+// Call Tool API types
+export interface CallToolRequest {
+  sessionId: string;
+  toolName: string;
+  toolArgs: Record<string, unknown>;
+}
+
+export interface CallToolSuccessResponse {
+  content: Array<{
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+  }>;
+  isError: boolean;
+}
+
+export interface CallToolErrorResponse {
+  error: string;
+}
+
+export type CallToolResponse =
+  | CallToolSuccessResponse
+  | CallToolErrorResponse;
+
+// Helper type guards
+export function isConnectSuccess(
+  response: ConnectResponse
+): response is ConnectSuccessResponse {
+  return 'success' in response && response.success === true;
+}
+
+export function isConnectAuthRequired(
+  response: ConnectResponse
+): response is ConnectAuthRequiredResponse {
+  return 'requiresAuth' in response && response.requiresAuth === true;
+}
+
+export function isConnectError(
+  response: ConnectResponse
+): response is ConnectErrorResponse {
+  return 'error' in response;
+}
+
+export function isListToolsSuccess(
+  response: ListToolsResponse
+): response is ListToolsSuccessResponse {
+  return 'tools' in response;
+}
+
+export function isCallToolSuccess(
+  response: CallToolResponse
+): response is CallToolSuccessResponse {
+  return 'content' in response;
+}
+
+// Generic tool info type
+export type ToolInfo = {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+};
+
+// Transport type
+export type TransportType = 'sse' | 'streamable_http';
+
+// SSE/RPC types
+export type McpRpcMethod =
+  | 'connect'
+  | 'disconnect'
+  | 'listTools'
+  | 'callTool'
+  | 'getSessions'
+  | 'restoreSession'
+  | 'finishAuth'
+  | 'listPrompts'
+  | 'getPrompt'
+  | 'listResources'
+  | 'readResource';
+
+export interface McpRpcRequest {
+  id: string;
+  method: McpRpcMethod;
+  params?: McpRpcParams;
+}
+
+export interface McpRpcResponse<T = unknown> {
+  id: string;
+  result?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+// RPC Parameter Types
+export interface ConnectParams {
+  serverId: string;
+  serverName: string;
+  serverUrl: string;
+  callbackUrl: string;
+  transportType?: TransportType;
+}
+
+export interface DisconnectParams {
+  sessionId: string;
+}
+
+export interface SessionParams {
+  sessionId: string;
+}
+
+export interface CallToolParams {
+  sessionId: string;
+  toolName: string;
+  toolArgs: Record<string, unknown>;
+}
+
+export interface GetPromptParams {
+  sessionId: string;
+  name: string;
+  args?: Record<string, string>;
+}
+
+export interface ReadResourceParams {
+  sessionId: string;
+  uri: string;
+}
+
+export interface FinishAuthParams {
+  sessionId: string;
+  code: string;
+}
+
+export type McpRpcParams =
+  | ConnectParams
+  | DisconnectParams
+  | SessionParams
+  | CallToolParams
+  | GetPromptParams
+  | ReadResourceParams
+  | FinishAuthParams
+  | undefined;
+
+// RPC Result Types
+export interface SessionInfo {
+  sessionId: string;
+  serverId?: string;
+  serverName?: string;
+  serverUrl: string;
+  transport: TransportType;
+}
+
+export interface SessionListResult {
+  sessions: SessionInfo[];
+}
+
+export interface ConnectResult {
+  sessionId: string;
+  success: boolean;
+}
+
+export interface DisconnectResult {
+  success: boolean;
+}
+
+export interface RestoreSessionResult {
+  success: boolean;
+  toolCount: number;
+}
+
+export interface FinishAuthResult {
+  success: boolean;
+  toolCount: number;
+}
+
+export interface ListToolsRpcResult {
+  tools: Tool[];
+}
+
+export interface ListPromptsResult {
+  prompts: Array<{
+    name: string;
+    description?: string;
+    arguments?: Array<{
+      name: string;
+      description?: string;
+      required?: boolean;
+    }>;
+  }>;
+}
+
+export interface ListResourcesResult {
+  resources: Array<{
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+  }>;
+}

package/src/shared/utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Sanitize server name to create a valid server label
+ * Must start with a letter and contain only letters, digits, '-' and '_'
+ */
+export function sanitizeServerLabel(name: string): string {
+  let sanitized = name
+    .replace(/[^a-zA-Z0-9-_]/g, '_')
+    .replace(/_{2,}/g, '_')
+    .toLowerCase();
+
+  if (!/^[a-zA-Z]/.test(sanitized)) {
+    sanitized = 's_' + sanitized;
+  }
+
+  return sanitized;
+}