@andrewcaires/api 5.2.3 → 5.3.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 /*!
- * @andrewcaires/api v5.2.3
+ * @andrewcaires/api v5.3.0
  * Simple api for small applications using express, jsonwebtoken, sequelize and websocket
  * (c) 2026 Andrew Caires
  * @license: MIT
  */
-import { Context, Application as Application$1, ExpressOptions, IStore } from '@andrewcaires/express';
+import { Context, Application as Application$1, ExpressOptions, IStore, ResponseError } from '@andrewcaires/express';
 import { Hash, Env as Env$1 } from '@andrewcaires/node';
 import { ModelFindOptions, ModelUpdateOptions, Model as Model$1, Sequelize } from '@andrewcaires/sequelize';
-import { TypeAnyObject, TypeObjectString, TypeAnyFunction, TypeAnyConstructor, EventEmitter, TypeObject, ValidationBase } from '@andrewcaires/utils.js';
+import { TypeAnyObject, TypeObjectString, TypeAnyFunction, TypeAnyConstructor, EventEmitter, TypeObject, ValidationBase, ValidationShape } from '@andrewcaires/utils.js';
 import { WebSocketServer } from 'ws';
 import { Model, CreateOptions, Attributes, FindOptions, IncludeOptions, FindAttributeOptions, ModelStatic } from 'sequelize';
 import { Store, SessionData } from 'express-session';
@@ -499,7 +499,7 @@ declare abstract class CrudController<M extends Model<any>, T extends TypeAnyObj
     protected del(ctx: Context): Promise<void>;
     protected get(ctx: Context): Promise<void>;
     protected set(ctx: Context): Promise<void>;
-    protected validate(ctx: Context, obj: TypeObject<ValidationBase>): Promise<void>;
+    protected validate(ctx: Context, obj: TypeObject<ValidationBase>): void;
     protected validateCreate(ctx: Context): Promise<void>;
     protected validateUpdate(ctx: Context): Promise<void>;
 }
@@ -545,6 +545,25 @@ declare class LogsController extends ModelController<LogModel> {
     protected all(ctx: Context): Promise<void>;
 }
 
+declare class McpController extends BaseController {
+    private readonly tools;
+    private toolsRegistered;
+    private readonly handler;
+    private readonly rateLimiter;
+    sync(app?: Application): Promise<void>;
+    protected options(ctx: Context): Promise<void>;
+    protected post(ctx: Context): Promise<void>;
+    protected delete(ctx: Context): Promise<void>;
+    private getMcpToolMetadata;
+    private discoverMcpTools;
+    private createMcpToolFromMetadata;
+    private request;
+    private isJsonParseError;
+    private isMcpEndpoint;
+    private jsonParseErrorResponse;
+    private respond;
+}
+
 declare class PermissionsController extends CrudController<PermissionModel> {
     protected readonly model: typeof PermissionModel;
     private schemaCreate;
@@ -565,6 +584,301 @@ declare class SetupController extends BaseController {
     protected setup(ctx: Context): Promise<void>;
 }
 
+declare const McpErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly ServerError: -32000;
+    readonly InvalidSession: -32001;
+};
+type McpErrorCode = typeof McpErrorCode[keyof typeof McpErrorCode];
+declare class McpError extends ResponseError {
+    readonly code: McpErrorCode;
+    readonly data?: unknown;
+    constructor(message: string, code?: McpErrorCode, status?: number, data?: unknown);
+}
+declare class McpParseError extends McpError {
+    constructor(message?: string, data?: unknown);
+}
+declare class McpInvalidRequestError extends McpError {
+    constructor(message?: string, data?: unknown);
+}
+declare class McpMethodNotFoundError extends McpError {
+    constructor(method: string);
+}
+declare class McpInvalidParamsError extends McpError {
+    constructor(message?: string, data?: unknown);
+}
+declare class McpInternalError extends McpError {
+    constructor(message?: string, data?: unknown);
+}
+declare class McpServerError extends McpError {
+    constructor(message?: string, data?: unknown);
+}
+declare class McpInvalidSessionError extends McpError {
+    constructor(message?: string, status?: number);
+}
+declare class McpToolNotFoundError extends McpError {
+    constructor(toolName: string);
+}
+
+declare const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18"];
+declare const MCP_DEFAULT_PROTOCOL_VERSION: "2025-11-25";
+declare const MCP_PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version";
+declare const MCP_SESSION_ID_HEADER = "MCP-Session-Id";
+type McpProtocolVersion = typeof MCP_SUPPORTED_PROTOCOL_VERSIONS[number];
+type McpJsonRpcId = string | number;
+interface McpJsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: McpJsonRpcId;
+    method: string;
+    params?: unknown;
+}
+interface McpJsonRpcErrorBody {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface McpJsonRpcResult {
+    jsonrpc: "2.0";
+    id: McpJsonRpcId;
+    result: unknown;
+}
+interface McpJsonRpcErrorResult {
+    jsonrpc: "2.0";
+    id: McpJsonRpcId | null;
+    error: McpJsonRpcErrorBody;
+}
+interface McpSessionContext {
+    auth?: unknown;
+    groups?: unknown;
+    permissions?: unknown;
+    profile?: unknown;
+    user?: unknown;
+    userId?: string | number;
+}
+interface McpSession extends McpSessionContext {
+    sessionId: string;
+    createdAt: number;
+    expiresAt: number;
+    protocolVersion: McpProtocolVersion;
+    initialized: boolean;
+}
+interface McpToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+interface McpToolDeclaration {
+    name: string;
+    title: string;
+    description: string;
+    input?: ValidationShape;
+    output?: ValidationShape;
+}
+interface McpToolContext extends McpSessionContext {
+    session: McpSession;
+}
+type McpToolInput = Record<string, unknown>;
+type McpToolOutput = unknown;
+interface McpCallToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+type McpToolHandlerResult = McpCallToolResult | McpToolOutput;
+interface McpRegisteredTool extends McpToolDeclaration {
+    run(_argumentsValue: McpToolInput, _context: McpToolContext): Promise<McpToolHandlerResult> | McpToolHandlerResult;
+}
+interface McpHttpRequest {
+    body: unknown;
+    headers: Record<string, string | undefined>;
+    context?: McpSessionContext;
+    ip?: string;
+}
+interface McpHttpResponse {
+    status: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+interface McpToolCallLog {
+    sessionId: string;
+    userId?: string | number;
+    toolName: string;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+}
+interface McpLogger {
+    toolCall(_log: McpToolCallLog): void | Promise<void>;
+}
+
+declare class McpSessionStore {
+    private readonly sessions;
+    private readonly ttl;
+    private readonly now;
+    constructor(ttl?: number, now?: () => number);
+    create(protocolVersion: McpProtocolVersion, context?: McpSessionContext): McpSession;
+    get(sessionId: string): McpSession | undefined;
+    require(sessionId: string): McpSession;
+    markInitialized(sessionId: string): McpSession;
+    delete(sessionId: string): boolean;
+    cleanup(): void;
+    size(): number;
+    private isExpired;
+}
+
+interface McpNormalizedValidation {
+    schema: TypeAnyObject;
+    validation?: ValidationBase;
+}
+declare class McpToolRegistry {
+    private readonly tools;
+    constructor(tools?: Array<McpRegisteredTool>);
+    register(tool: McpRegisteredTool): void;
+    list(): Array<McpToolDefinition>;
+    call(name: string, argumentsValue: unknown, session: McpSession): Promise<McpCallToolResult>;
+    private isCallToolResult;
+    private normalizeMcpValidation;
+    private outputValidationError;
+    private toolInputValidationError;
+    private validateAdditionalProperties;
+}
+
+interface McpHttpHandlerOptions {
+    sessions: McpSessionStore;
+    tools: McpToolRegistry;
+    allowedOrigins?: Array<string>;
+    logger?: McpLogger;
+    serverName?: string;
+    serverVersion?: string;
+}
+declare const MCP_HTTP_ALLOWED_METHODS: readonly ["POST", "DELETE", "OPTIONS"];
+declare const MCP_HTTP_ALLOW: string;
+declare const isJsonParseError: (error: unknown) => error is Error & {
+    status?: number;
+    statusCode?: number;
+    type?: string;
+};
+declare const jsonParseErrorResponse: (error: unknown) => McpHttpResponse | undefined;
+declare class McpHttpHandler {
+    private readonly sessions;
+    private readonly tools;
+    private readonly allowedOrigins;
+    private readonly logger?;
+    private readonly serverName;
+    private readonly serverVersion;
+    constructor(options: McpHttpHandlerOptions);
+    post(request: McpHttpRequest): Promise<McpHttpResponse>;
+    delete(request: McpHttpRequest): McpHttpResponse;
+    get(request: McpHttpRequest): McpHttpResponse;
+    options(request: McpHttpRequest): McpHttpResponse;
+    private initialize;
+    private initialized;
+    private callTool;
+    private requireRequestId;
+    private withSession;
+    private withInitializedSession;
+    private requireSession;
+    private validateProtocolHeader;
+    private negotiateProtocolVersion;
+    private parseToolCallParams;
+    private validateObjectParams;
+    private validateOrigin;
+    private withTransportHeaders;
+    private transportHeaders;
+    private getAllowedOrigin;
+    private getSessionHeader;
+    private getHeader;
+    private errorResponse;
+}
+
+declare const isJsonRpcId: (value: unknown) => value is McpJsonRpcId;
+declare const jsonRpcResult: (id: McpJsonRpcId, result: unknown) => McpJsonRpcResult;
+declare const jsonRpcError: (id: McpJsonRpcId | null, error: McpError) => McpJsonRpcErrorResult;
+declare const jsonRpcErrorFromCode: (id: McpJsonRpcId | null, code: McpErrorCode, message: string, data?: unknown) => McpJsonRpcErrorResult;
+declare const parseJsonRpcRequest: (body: unknown) => McpJsonRpcRequest;
+
+declare class McpRateLimiter {
+    private readonly entries;
+    private readonly max;
+    private readonly windowMs;
+    private readonly now;
+    constructor(max?: number, windowMs?: number, now?: () => number);
+    consume(key: string): boolean;
+}
+
+declare const MCP_TOOL_METADATA: unique symbol;
+interface McpToolMetadata extends McpToolDeclaration {
+    propertyKey: string | symbol;
+}
+type McpDecoratedToolHandler = (_argumentsValue: Record<string, unknown>, _context: McpToolContext) => ReturnType<McpRegisteredTool["run"]>;
+declare const assertValidMcpToolDefinition: (definition: McpToolDeclaration) => void;
+
+declare class TestController extends BaseController {
+    protected json(ctx: Context): Promise<void>;
+    protected sum(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        value: number;
+    }>;
+    protected multiply(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        value: number;
+    }>;
+    protected average(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        value: number;
+        count: number;
+    }>;
+    protected validationString(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        length: number;
+        normalized: string;
+    }>;
+    protected validationNumber(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        doubled: number;
+    }>;
+    protected validationBoolean(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        active: any;
+    }>;
+    protected validationArray(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        count: number;
+    }>;
+    protected validationObject(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        summary: {
+            name: any;
+            adult: boolean;
+        };
+    }>;
+    protected validationEnum(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        status: any;
+    }>;
+    protected validationDate(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        iso: string;
+        timestamp: number;
+    }>;
+    protected validationOptional(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        nickname?: string | undefined;
+        name: any;
+        hasNickname: boolean;
+    }>;
+    protected validationDefaults(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        name: any;
+        limit: any;
+    }>;
+    protected validationParse(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        active: any;
+        amount: any;
+    }>;
+    protected validationNested(args: TypeAnyObject, _context: McpToolContext): Promise<{
+        userId: any;
+        scoreCount: number;
+    }>;
+}
+
 declare class UsersController extends ModelController<UserModel> {
     protected readonly model: typeof UserModel;
     path: string;
@@ -616,6 +930,9 @@ declare const ReqPermissions: (key?: string) => ParameterDecorator;
 
 declare const ReqUser: (key?: string) => ParameterDecorator;
 
+type McpToolOptions = Omit<McpToolMetadata, "propertyKey">;
+declare const McpTool: (options: McpToolOptions) => MethodDecorator;
+
 declare const Audit: (active?: boolean) => ClassDecorator;
 
 declare class Env extends Env$1 {
@@ -632,6 +949,10 @@ declare class Env extends Env$1 {
     static readonly HTTP_TLS_KEY: Buffer<ArrayBufferLike> | null;
     static readonly MODEL_LIMIT: number;
     static readonly MODEL_LIMIT_MAX: number;
+    static readonly MCP_ALLOWED_ORIGINS: string;
+    static readonly MCP_RATE_LIMIT_MAX: number;
+    static readonly MCP_RATE_LIMIT_WINDOW: number;
+    static readonly MCP_SESSION_TTL: number;
     static readonly PASSWORD_ALGORITHM: number;
     static readonly PASSWORD_MEMORY_COST: number;
     static readonly PASSWORD_PARALLELISM: number;
@@ -668,5 +989,5 @@ declare class Env extends Env$1 {
     static readonly API_WEBSOCKET_START: boolean;
 }
 
-export { Application, Audit, AuditModel, AuditTypes, AuditsController, AuthController, AuthService, BaseController, CanCreate, CanDelete, CanRead, CanUpdate, Config, ConfigModel, CrudController, Env, FilesController, ForgotController, ForgotModel, GroupModel, GroupPermissionModel, GroupsController, GroupsPermissionsController, HasGroups, HasPermissions, HealthController, IsAuthenticated, Log, LogModel, Loggable, Loglevels, LogsController, MigrationModel, ModelController, ModelService, PermissionModel, PermissionsController, RegisterController, RegisterModel, ReqAuth, ReqGroup, ReqGroups, ReqPermission, ReqPermissions, ReqUser, Service, SessionModel, SessionStore, SetupController, UserAuthModel, UserGroupModel, UserModel, UserPasswordModel, UserService, UserStatus, UsersController, UsersGroupsController, canFactory, sequelize };
-export type { ApplicationEvents, AuthEvents, ForgotEvents, IAuthParameters, ModelArgumentsBase, ModelArgumentsCount, ModelArgumentsCreate, ModelArgumentsDelete, ModelArgumentsFindAll, ModelArgumentsFindOne, ModelArgumentsInclude, ModelArgumentsUpdate, ModelCallbackFindAll, ModelCallbackFindOne, ModelOptions, ModelResultFindAll, RegisterEvents };
+export { Application, Audit, AuditModel, AuditTypes, AuditsController, AuthController, AuthService, BaseController, CanCreate, CanDelete, CanRead, CanUpdate, Config, ConfigModel, CrudController, Env, FilesController, ForgotController, ForgotModel, GroupModel, GroupPermissionModel, GroupsController, GroupsPermissionsController, HasGroups, HasPermissions, HealthController, IsAuthenticated, Log, LogModel, Loggable, Loglevels, LogsController, MCP_DEFAULT_PROTOCOL_VERSION, MCP_HTTP_ALLOW, MCP_HTTP_ALLOWED_METHODS, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_ID_HEADER, MCP_SUPPORTED_PROTOCOL_VERSIONS, MCP_TOOL_METADATA, McpController, McpError, McpErrorCode, McpHttpHandler, McpInternalError, McpInvalidParamsError, McpInvalidRequestError, McpInvalidSessionError, McpMethodNotFoundError, McpParseError, McpRateLimiter, McpServerError, McpSessionStore, McpTool, McpToolNotFoundError, McpToolRegistry, MigrationModel, ModelController, ModelService, PermissionModel, PermissionsController, RegisterController, RegisterModel, ReqAuth, ReqGroup, ReqGroups, ReqPermission, ReqPermissions, ReqUser, Service, SessionModel, SessionStore, SetupController, TestController, UserAuthModel, UserGroupModel, UserModel, UserPasswordModel, UserService, UserStatus, UsersController, UsersGroupsController, assertValidMcpToolDefinition, canFactory, isJsonParseError, isJsonRpcId, jsonParseErrorResponse, jsonRpcError, jsonRpcErrorFromCode, jsonRpcResult, parseJsonRpcRequest, sequelize };
+export type { ApplicationEvents, AuthEvents, ForgotEvents, IAuthParameters, McpCallToolResult, McpDecoratedToolHandler, McpHttpHandlerOptions, McpHttpRequest, McpHttpResponse, McpJsonRpcErrorBody, McpJsonRpcErrorResult, McpJsonRpcId, McpJsonRpcRequest, McpJsonRpcResult, McpLogger, McpNormalizedValidation, McpProtocolVersion, McpRegisteredTool, McpSession, McpSessionContext, McpToolCallLog, McpToolContext, McpToolDeclaration, McpToolDefinition, McpToolHandlerResult, McpToolInput, McpToolMetadata, McpToolOptions, McpToolOutput, ModelArgumentsBase, ModelArgumentsCount, ModelArgumentsCreate, ModelArgumentsDelete, ModelArgumentsFindAll, ModelArgumentsFindOne, ModelArgumentsInclude, ModelArgumentsUpdate, ModelCallbackFindAll, ModelCallbackFindOne, ModelOptions, ModelResultFindAll, RegisterEvents };