Type Definitions

interface Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolParameters> {
  name: string;
  description?: string;
  parameters?: Params;
  execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<string | Content | ContentResult | void>;
  canAccess?: (auth: T) => boolean;
  timeoutMs?: number;
  annotations?: ToolAnnotations;
  _meta?: {
    ui?: {
      resourceUri?: string;
    };
    [key: string]: unknown;
  };
}

interface ToolAnnotations {
  title?: string;              // Human-readable title for UI display
  readOnlyHint?: boolean;      // Tool does not modify environment (default: false)
  destructiveHint?: boolean;   // Tool may perform destructive updates (default: true)
  idempotentHint?: boolean;    // Repeated calls have no additional effect (default: false)
  openWorldHint?: boolean;     // Tool may interact with external entities (default: true)
}

interface Resource<T extends FastMCPSessionAuth> {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
  load: (auth?: T) => Promise<ResourceResult | ResourceResult[]>;
  canAccess?: (auth: T) => boolean;
  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
}

interface ResourceTemplate<
  T extends FastMCPSessionAuth,
  Arguments extends ResourceTemplateArgument<T>[] = ResourceTemplateArgument<T>[]
> {
  uriTemplate: string;
  name: string;
  description?: string;
  mimeType?: string;
  arguments: Arguments;
  load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
}

type ResourceResult =
  | {
      text: string;
      mimeType?: string;
      uri?: string;
    }
  | {
      blob: string;  // Base64-encoded
      mimeType?: string;
      uri?: string;
    };

interface ResourceTemplateArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> {
  name: string;
  description?: string;
  required?: boolean;
  complete?: ArgumentValueCompleter<T>;
}

interface Prompt<
  T extends FastMCPSessionAuth = FastMCPSessionAuth,
  Arguments extends PromptArgument<T>[] = PromptArgument<T>[],
  Args = PromptArgumentsToObject<Arguments>
> {
  name: string;
  description?: string;
  arguments?: PromptArgument<T>[];
  load: (args: Args, auth?: T) => Promise<PromptResult>;
  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
}

interface PromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> {
  name: string;
  description?: string;
  required?: boolean;
  enum?: string[];
  complete?: ArgumentValueCompleter<T>;
}

type PromptResult = string | {
  messages: Array<{
    role: "user" | "assistant";
    content: {
      type: string;
      text: string;
    };
  }>;
};

type Content = 
  | TextContent
  | ImageContent
  | AudioContent
  | ResourceContent
  | ResourceLink;

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

interface ImageContent {
  type: "image";
  data: string;      // Base64-encoded
  mimeType: string;  // e.g., "image/png"
}

interface AudioContent {
  type: "audio";
  data: string;      // Base64-encoded
  mimeType: string;  // e.g., "audio/mpeg"
}

interface ResourceContent {
  type: "resource";
  resource: {
    uri: string;
    text?: string;
    blob?: string;     // Base64-encoded
    mimeType?: string;
  };
}

interface ResourceLink {
  type: "resource_link";
  uri: string;
  name: string;
  title?: string;
  description?: string;
  mimeType?: string;
}

interface ContentResult {
  content: Content[];
  isError?: boolean;
}

type FastMCPSessionAuth = Record<string, unknown> | undefined;

interface Context<T extends FastMCPSessionAuth> {
  session: T | undefined;
  sessionId?: string;
  requestId?: string;
  client: {
    version: string;
  };
  log: {
    debug: (message: string, data?: SerializableValue) => void;
    info: (message: string, data?: SerializableValue) => void;
    warn: (message: string, data?: SerializableValue) => void;
    error: (message: string, data?: SerializableValue) => void;
  };
  reportProgress: (progress: Progress) => Promise<void>;
  streamContent: (content: Content | Content[]) => Promise<void>;
}

interface Progress {
  progress: number;  // Current progress value
  total?: number;    // Total value if known
}

interface Logger {
  debug(...args: unknown[]): void;
  info(...args: unknown[]): void;
  log(...args: unknown[]): void;
  warn(...args: unknown[]): void;
  error(...args: unknown[]): void;
}

interface FastMCPRequest<T extends FastMCPSessionAuth = FastMCPSessionAuth> {
  url: string;
  method: string;
  headers: http.IncomingHttpHeaders;
  params: Record<string, string>;
  query: Record<string, string | string[]>;
  body?: unknown;
  auth?: T;
  json(): Promise<unknown>;
  text(): Promise<string>;
}

interface FastMCPResponse {
  status(code: number): FastMCPResponse;
  setHeader(name: string, value: string | number | string[]): FastMCPResponse;
  json(data: unknown): void;
  send(data: string | Buffer): void;
  end(data?: string | Buffer): void;
}

type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";

type RouteHandler<T extends FastMCPSessionAuth = FastMCPSessionAuth> = (
  req: FastMCPRequest<T>,
  res: FastMCPResponse,
) => void | Promise<void>;

interface RouteOptions {
  public?: boolean;  // Bypass authentication (default: false)
}

interface Completion {
  values: string[];        // Completion suggestions (max 100)
  total?: number;          // Total available completions
  hasMore?: boolean;       // More completions available
}

type ArgumentValueCompleter<T extends FastMCPSessionAuth = FastMCPSessionAuth> = (
  value: string,
  auth?: T
) => Promise<Completion>;

class UserError extends Error {
  extras?: Record<string, unknown>;
  
  constructor(message: string, extras?: Record<string, unknown>);
}

class UnexpectedStateError extends Error {
  extras?: Record<string, unknown>;
  
  constructor(message: string, extras?: Record<string, unknown>);
}

type SerializableValue =
  | string
  | number
  | boolean
  | null
  | undefined
  | SerializableValue[]
  | { [key: string]: SerializableValue };

type ToolParameters = StandardSchemaV1;