mcpresso/dist/index.d.ts

TypeScript package for Model Context Protocol (MCP) utilities and tools

import { z } from "zod";
import type { Express } from "express";
import { type MCPAuthConfig, type UserProfile, type JWTPayload } from "./auth.js";
export declare function getCurrentUser(): UserProfile | JWTPayload | undefined;
/**
 * Configuration for exponential back-off retries on handler failures.
 */
export interface RetryConfig {
    /** The maximum number of retry attempts.
     * @default 3
     */
    retries?: number;
    /** The exponential factor to use.
     * @default 2
     */
    factor?: number;
    /** The minimum (initial) timeout in milliseconds.
     * @default 1000
     */
    minTimeout?: number;
    /** The maximum timeout in milliseconds.
     * @default 30000
     */
    maxTimeout?: number;
}
/**
 * Configuration for basic rate limiting on incoming requests.
 * Uses `express-rate-limit`.
 */
export interface RateLimitConfig {
    /** The time window in milliseconds.
     * @default 900000 (15 minutes)
     */
    windowMs?: number;
    /** The maximum number of requests to allow from an IP within the window.
     * @default 100
     */
    limit?: number;
    /**
     * Whether to send `RateLimit` and `RateLimit-Policy` headers.
     * Can be a boolean or a specific draft version.
     * @see https://www.npmjs.com/package/express-rate-limit#standardheaders
     * @default true
     */
    standardHeaders?: boolean | "draft-6" | "draft-7";
    /**
     * Whether to send legacy `X-RateLimit-*` headers.
     * @default false
     */
    legacyHeaders?: boolean;
}
/**
 * Server metadata that can be exposed as an MCP resource.
 */
export interface ServerMetadata {
    /** The name of the server. */
    name: string;
    /** The version of the server. */
    version: string;
    /** A description of the server. */
    description?: string;
    /** The canonical URL of the server. */
    url?: string;
    /** Contact information for the server maintainers. */
    contact?: {
        name?: string;
        email?: string;
        url?: string;
    };
    /** License information. */
    license?: {
        name: string;
        url?: string;
    };
    /** Available resources and their descriptions. */
    resources?: Array<{
        name: string;
        description?: string;
        methods: string[];
    }>;
    /** Server capabilities and features. */
    capabilities?: {
        authentication?: boolean;
        rateLimiting?: boolean;
        retries?: boolean;
        streaming?: boolean;
    };
}
/**
 * Configuration for dynamic tools management.
 */
export interface DynamicToolsConfig {
    /** Whether to enable dynamic tools management. */
    enabled?: boolean;
    /** Minimum interval between tool changes in milliseconds. */
    minInterval?: number;
    /** Maximum interval between tool changes in milliseconds. */
    maxInterval?: number;
    /** Maximum number of dynamic tools to maintain. */
    maxTools?: number;
    /** List of tool names that can be dynamically added/removed. */
    availableTools?: Array<{
        name: string;
        description: string;
        inputSchema: z.ZodObject<any>;
        handler: (args: any) => Promise<any>;
    }>;
}
/** Represents a relationship to another resource type. */
interface Relation {
    /** The name of the resource type being referenced. */
    type: string;
}
/**
 * The fully processed configuration for a single resource tool/method.
 * This is generated by the `createResource` function.
 * @internal
 */
interface Method<TInput = unknown, TOutput = unknown> {
    description: string;
    inputSchema: z.ZodObject<any, any, any>;
    outputSchema: z.ZodTypeAny;
    handler: (args: TInput, user?: any) => Promise<TOutput>;
    returnsResourceList?: boolean;
}
/**
 * A user-defined method. The `createResource` factory uses this to build
 * the final `Method` configuration.
 */
export type MethodDefinition<TInput extends z.ZodObject<any, any, any> | z.ZodTypeAny, TOutput> = {
    description?: string;
    inputSchema?: TInput;
    outputSchema?: z.ZodType<TOutput>;
    handler: (args: z.infer<TInput>, user?: any) => Promise<TOutput>;
};
type CreateInputType<T extends z.ZodObject<any>> = Omit<z.infer<T>, "id" | "createdAt" | "updatedAt">;
type UpdateInputType<T extends z.ZodObject<any>> = Partial<z.infer<T>> & {
    id: string;
};
/**
 * The final, fully processed configuration for a resource.
 * This is the output of the `createResource` factory function.
 * @internal
 */
export interface ResourceConfig<T extends z.ZodObject<any, any, any>> {
    name: string;
    schema: T;
    uri_template: string;
    relations?: Partial<Record<keyof T["shape"], Relation>>;
    get?: (args: {
        id: string;
    }, user?: any) => Promise<z.infer<T> | undefined>;
    methods: Record<string, Method<unknown, unknown>>;
}
/**
 * The user-facing blueprint for defining a resource and its methods.
 * This object is passed to the `createResource` factory.
 * @template T The main Zod schema for the resource.
 */
export interface ResourceBlueprint<T extends z.ZodObject<any, any, any>> {
    /** The singular, lowercase name of the resource (e.g., "note", "user"). */
    name: string;
    /** The Zod schema that defines the resource's data structure and validation rules. */
    schema: T;
    /**
     * A URI template for generating unique URIs for each resource instance.
     * Must include an `{id}` placeholder. Example: "notes/{id}".
     */
    uri_template: string;
    /**
     * Defines relationships to other resources. The keys must be fields in the schema.
     * This is used to enrich the exposed type schemas with `$ref` links.
     */
    relations?: Partial<Record<keyof T["shape"], Relation>>;
    /**
     * An object defining the tools (methods) for this resource.
     * The library provides default schemas and descriptions for standard
     * methods like `create`, `update`, `list`, and `delete`.
     */
    methods?: {
        get?: {
            handler: (args: {
                id: string;
            }, user?: any) => Promise<z.infer<T> | undefined>;
            description?: string;
            inputSchema?: z.ZodObject<any>;
            outputSchema?: z.ZodType<any>;
        };
        create?: {
            handler: (args: CreateInputType<T>, user?: any) => Promise<z.infer<T>>;
            description?: string;
            inputSchema?: z.ZodObject<any>;
            outputSchema?: z.ZodType<any>;
        };
        update?: {
            handler: (args: UpdateInputType<T>, user?: any) => Promise<z.infer<T>>;
            description?: string;
            inputSchema?: z.ZodObject<any>;
            outputSchema?: z.ZodType<any>;
        };
        delete?: {
            handler: (args: {
                id: string;
            }, user?: any) => Promise<{
                success: boolean;
            }>;
            description?: string;
            inputSchema?: z.ZodObject<any>;
            outputSchema?: z.ZodType<any>;
        };
        list?: {
            handler: (args: {}, user?: any) => Promise<z.infer<T>[]>;
            description?: string;
            inputSchema?: z.ZodObject<any>;
            outputSchema?: z.ZodType<any>;
        };
        [customMethodName: string]: MethodDefinition<any, any> | undefined;
    };
}
/** Configuration for the main MCP server. */
export interface MCPServerConfig {
    /** The name of the server, used in resource URIs. */
    name: string;
    /** The public-facing canonical URL of this server. Used for authentication (as audience) and in resource URIs. */
    serverUrl?: string;
    /**
     * An array of resource configurations.
     * This is now an array of the fully processed `ResourceConfig` objects.
     */
    resources: ResourceConfig<any>[];
    /**
     * If `true`, exposes JSON schemas for all resources.
     * If an array is provided, exposes schemas only for those resources.
     * This is crucial for enabling language models to understand the server's data model.
     */
    exposeTypes?: boolean | ResourceConfig<any>[];
    /**
     * Optional configuration to enable authentication.
     *
     * Three modes:
     * 1. No auth: Don't provide this field
     * 2. External OAuth: Provide issuer + userLookup
     * 3. Integrated OAuth: Provide oauth server instance
     */
    auth?: MCPAuthConfig;
    /** Optional configuration for exponential back-off retry on handler failures. */
    retry?: RetryConfig;
    /** Optional configuration for rate limiting. */
    rateLimit?: RateLimitConfig;
    /** Optional server metadata to expose as an MCP resource. */
    serverMetadata?: ServerMetadata;
}
/**
 * Manages dynamic tools that can be added and removed at runtime.
 * Sends notifications when the tools list changes.
 */
/**
 * A factory function for creating a resource configuration object.
 * Provides type inference and helps ensure the configuration is valid.
 * @param config The resource configuration.
 * @returns The validated resource configuration object.
 */
export declare function createResource<T extends z.ZodObject<any, any, any>>(blueprint: ResourceBlueprint<T>): ResourceConfig<T>;
/**
 * Creates an Express app instance that serves a fully-functional MCP server.
 * @param config The server configuration object.
 * @returns An Express application instance.
 */
export declare function createMCPServer(config: MCPServerConfig): Express;
export {};
//# sourceMappingURL=index.d.ts.map