@andrewcaires/api 5.7.2 → 5.8.0

package/dist/index.d.ts

@@ -1,14 +1,15 @@
 /*!
- * @andrewcaires/api v5.7.2
+ * @andrewcaires/api v5.8.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, HttpError } from '@andrewcaires/express';
+import { Context, Application as Application$1, ExpressOptions } from '@andrewcaires/express';
 import { ModelFindOptions, ModelUpdateOptions, Model as Model$1, Sequelize } from '@andrewcaires/sequelize';
-import { TypeAnyObject, TypeObjectString, TypeAnyFunction, TypeAnyConstructor, EventEmitter, TypeObject, ValidationBase, ValidationShape } from '@andrewcaires/utils.js';
+import { ValidationBase, ValidationShape, TypeAnyObject, TypeObjectString, TypeAnyFunction, TypeAnyConstructor, EventEmitter, TypeObject } from '@andrewcaires/utils.js';
 import { WebSocketServer } from 'ws';
 import { Model, CreateOptions, Attributes, FindOptions, IncludeOptions, FindAttributeOptions, ModelStatic } from 'sequelize';
+import { CallToolResult, fromJsonSchema, AuthInfo, McpRequestContext, ToolAnnotations } from '@modelcontextprotocol/server';
 import { Env as Env$1 } from '@andrewcaires/node';
 import { Store, SessionData } from 'express-session';
 
@@ -101,6 +102,104 @@ declare module "express-serve-static-core" {
     }
 }
 
+type McpCallToolResult = CallToolResult;
+
+type McpErrorSource = "handler" | "tool";
+
+interface McpErrorLog {
+    source: McpErrorSource;
+    errorName: string;
+    toolName?: string;
+}
+
+interface McpHttpRequestLike {
+    originalUrl?: string;
+    path?: string;
+    url?: string;
+}
+
+type McpToolCallError = "execution_failed" | "invalid_input" | "invalid_output" | "permission_denied" | "tool_error";
+
+interface McpToolCallLog {
+    toolName: string;
+    durationMs: number;
+    success: boolean;
+    error?: McpToolCallError;
+}
+
+interface McpLogger {
+    error?(_log: McpErrorLog): void | Promise<void>;
+    toolCall(_log: McpToolCallLog): void | Promise<void>;
+}
+
+interface McpPreparedValidation {
+    schema: ReturnType<typeof fromJsonSchema>;
+    validation: ValidationBase;
+}
+
+interface McpPrincipalTenant {
+    id: string;
+    name: string;
+}
+
+interface McpPrincipal {
+    accessId: string;
+    userId: string;
+    groups: Array<string>;
+    permissions: Array<string>;
+    tenants: Array<McpPrincipalTenant>;
+    tenantId?: string;
+}
+
+interface McpToolContext {
+    authInfo?: AuthInfo;
+    era: McpRequestContext["era"];
+    principal?: McpPrincipal;
+    signal: AbortSignal;
+}
+
+interface McpToolDeclaration {
+    name: string;
+    title: string;
+    description: string;
+    input: ValidationShape;
+    output?: ValidationShape;
+    annotations?: ToolAnnotations;
+    public?: boolean;
+    requiredPermissions: ReadonlyArray<string>;
+}
+
+type McpToolOutput = unknown;
+
+type McpToolHandlerResult = McpCallToolResult | McpToolOutput;
+
+type McpToolInput = Record<string, unknown>;
+
+interface McpRegisteredTool extends McpToolDeclaration {
+    run(_argumentsValue: McpToolInput, _context: McpToolContext): Promise<McpToolHandlerResult> | McpToolHandlerResult;
+}
+
+interface McpPreparedTool {
+    input: McpPreparedValidation;
+    output?: McpPreparedValidation;
+    tool: McpRegisteredTool;
+}
+
+interface McpServerHandlerOptions {
+    logger?: McpLogger;
+    maxRequestBodySize?: number;
+    serverName?: string;
+    serverVersion?: string;
+}
+
+interface McpToolMetadata extends McpToolDeclaration {
+    propertyKey: string | symbol;
+}
+
+type McpToolOptions = Omit<McpToolDeclaration, "requiredPermissions"> & {
+    requiredPermissions?: ReadonlyArray<string>;
+};
+
 interface ModelArgumentsBase<M extends Model<M>> {
     ctx?: Context;
 }
@@ -198,6 +297,13 @@ declare enum UserStatus {
     ARCHIVED = "archived"
 }
 
+interface SetupOptions {
+    email: string;
+    name: string;
+    password: string;
+    username: string;
+}
+
 type WorkerInstance = {
     handler: () => void | Promise<void>;
 };
@@ -533,7 +639,11 @@ declare class AuthService extends Service {
         token: string;
     }>;
     revokeApiKey(ctx: Context, id: string, user: UserModel): Promise<boolean>;
+    mcpAuth(ctx: Context): Promise<AuthResult & {
+        token: string;
+    }>;
     private attachAuthContext;
+    private authenticate;
     private safeEqual;
     private verifyJwt;
 }
@@ -562,6 +672,12 @@ declare class ModelService<M extends Model<any>> extends Service {
     update(options: ModelArgumentsUpdate<M>): Promise<boolean>;
 }
 
+declare class SetupService extends Service {
+    private readonly userService;
+    setup(options: SetupOptions): Promise<void>;
+    private validate;
+}
+
 declare class UserService extends Service {
     private hashOptions;
     canAssignPassword(user_id: string, password: string): Promise<boolean>;
@@ -574,14 +690,18 @@ declare class UserService extends Service {
         id: string;
         name: string;
     }>>;
+    hashPassword(value: string): string;
 }
 
 declare class Application<T extends ApplicationEvents = ApplicationEvents> extends Application$1<T> {
     authService: AuthService;
     userService: UserService;
+    readonly mcpPath: string;
+    readonly mcpPublicPath: string;
     private _webSocket?;
     private _prepared;
     constructor(controllers: Array<object | TypeAnyConstructor<object>>, options?: ExpressOptions);
+    close(): Promise<void>;
     error(error: any, source?: string): void;
     log(message: string, source?: string): void;
     listen(): Promise<void>;
@@ -697,6 +817,7 @@ declare class GroupsRolesController extends ModelController<RoleModel> {
     private addRoles;
     private ensureGroup;
     private ensureRoles;
+    private touchGroup;
 }
 
 declare class HealthController {
@@ -710,20 +831,14 @@ declare class LogsController extends ModelController<LogModel> {
 }
 
 declare class McpController extends BaseController {
-    private readonly tools;
-    private toolsRegistered;
-    private readonly handler;
+    private handlers;
+    private mounted;
+    close(): Promise<void>;
     sync(app?: Application): Promise<void>;
-    protected get(ctx: Context): Promise<void>;
-    protected options(ctx: Context): Promise<void>;
-    protected post(ctx: Context<any, Application>): Promise<void>;
-    protected delete(ctx: Context<any, Application>): Promise<void>;
-    private isJsonParseError;
-    private isMcpEndpoint;
-    private jsonParseErrorResponse;
-    private respond;
-    private setResponseHeaders;
-    private getAllowedOrigin;
+    private authenticate;
+    private cors;
+    private handle;
+    private toNodeHandler;
 }
 
 declare class PagesController extends CrudController<PageModel> {
@@ -789,11 +904,7 @@ declare class RolesPermissionsController extends ModelController<PermissionModel
     private addPermissions;
     private ensurePermissions;
     private ensureRole;
-}
-
-declare class SetupController extends BaseController {
-    protected readonly userService: UserService;
-    protected setup(ctx: Context): Promise<void>;
+    private touchRole;
 }
 
 declare class TenantsController extends CrudController<TenantModel> {
@@ -808,247 +919,6 @@ declare class TenantsController extends CrudController<TenantModel> {
     private ensureTenant;
 }
 
-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 HttpError {
-    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 McpSession {
-    sessionId: string;
-    createdAt: number;
-    expiresAt: number;
-    protocolVersion: McpProtocolVersion;
-    initialized: boolean;
-    access?: unknown;
-    groups?: Array<string>;
-    permissions?: Array<string>;
-    tenants?: Array<{
-        id: string;
-        name: string;
-    }>;
-    user?: unknown;
-    userId?: string;
-}
-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 {
-    session: McpSession;
-    access?: unknown;
-    groups?: Array<string>;
-    permissions?: Array<string>;
-    tenants?: Array<{
-        id: string;
-        name: string;
-    }>;
-    user?: unknown;
-    userId?: string;
-}
-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 McpHttpResponse {
-    status: number;
-    headers?: Record<string, string>;
-    body?: unknown;
-}
-interface McpToolCallLog {
-    sessionId: string;
-    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): 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 normalizeSchema;
-    private outputValidationError;
-    private toolInputValidationError;
-    private validateAdditionalProperties;
-}
-
-interface McpHttpHandlerOptions {
-    sessions: McpSessionStore;
-    tools: McpToolRegistry;
-    logger?: McpLogger;
-    serverName?: string;
-    serverVersion?: string;
-    allowedHeaders?: Array<string>;
-    allowedOrigins?: Array<string>;
-}
-declare const MCP_HTTP_ALLOWED_METHODS: readonly ["POST", "DELETE", "OPTIONS"];
-declare const MCP_HTTP_ALLOW: string;
-declare const MCP_HTTP_DEFAULT_ALLOWED_HEADERS: readonly ["Content-Type", "Accept", "MCP-Session-Id", "MCP-Protocol-Version"];
-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 logger?;
-    private readonly serverName;
-    private readonly serverVersion;
-    private readonly allowedHeaders;
-    private readonly allowedOrigins;
-    constructor(options: McpHttpHandlerOptions);
-    post(ctx: Context): Promise<McpHttpResponse>;
-    delete(ctx: Context): McpHttpResponse;
-    get(ctx?: Context): McpHttpResponse;
-    options(ctx?: Context): McpHttpResponse;
-    private initialize;
-    private initialized;
-    private callTool;
-    private requireRequestId;
-    private withSession;
-    private withInitializedSession;
-    private requireSession;
-    private negotiateProtocolVersion;
-    private parseToolCallParams;
-    private validateObjectParams;
-    private withTransportHeaders;
-    private errorResponse;
-    private getBody;
-    private getHeader;
-    private getHeaderFromRequest;
-    private getHeaderFromRecord;
-    private normalizeHeaderValue;
-    private normalizeAllowedHeaders;
-    private getAllowedOrigin;
-    private getAuthContext;
-}
-
-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 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 const getMcpToolMetadata: (target: object | TypeAnyConstructor<object>) => Array<McpToolMetadata>;
-declare const discoverMcpTools: (controllers: Array<object>) => Array<McpRegisteredTool>;
-
 declare class TestController extends BaseController {
     protected json(ctx: Context): Promise<void>;
     protected workerSum(): Promise<{
@@ -1131,6 +1001,7 @@ declare class UsersGroupsController extends ModelController<GroupModel> {
     private addGroups;
     private ensureGroups;
     private ensureUser;
+    private touchUser;
 }
 
 declare class UsersKeysController extends ModelController<UserKeyModel> {
@@ -1159,6 +1030,7 @@ declare class UsersTenantsController extends ModelController<TenantModel> {
     private addTenants;
     private ensureTenants;
     private ensureUser;
+    private touchUser;
 }
 
 declare const sequelize: Sequelize;
@@ -1197,7 +1069,6 @@ declare const ReqTenants: (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;
@@ -1206,7 +1077,7 @@ declare const RegisterWorker: (name: string) => ClassDecorator & MethodDecorator
 
 declare class Env extends Env$1 {
     static readonly AUDIT_IGNORE: string[];
-    static readonly BASE_NAME: string;
+    static readonly API_NAME: string;
     static readonly CONSOLE_ERROR: boolean;
     static readonly DATABASE_URI: string;
     static readonly DATABASE_LOG: boolean;
@@ -1226,7 +1097,9 @@ 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_SESSION_TTL: number;
+    static readonly MCP_ALLOWED_HOSTS: string[];
+    static readonly MCP_ALLOWED_ORIGINS: string[];
+    static readonly MCP_MAX_REQUEST_BODY_SIZE: number;
     static readonly PASSWORD_ALGORITHM: number;
     static readonly PASSWORD_MEMORY_COST: number;
     static readonly PASSWORD_PARALLELISM: number;
@@ -1273,5 +1146,5 @@ declare class WorkerRegistry {
     private static normalizeWorkerName;
 }
 
-export { Application, Audit, AuditModel, AuditTypes, AuditsController, AuthController, AuthService, BaseController, CanCreate, CanDelete, CanRead, CanUpdate, Config, ConfigModel, CrudController, Env, FilesController, ForgotController, ForgotModel, GroupModel, GroupRoleModel, GroupTypes, GroupsController, GroupsPermissionsController, GroupsRolesController, HasGroups, HasPermissions, HasScope, HealthController, IsAuthenticated, Log, LogLevels, LogModel, Loggable, LogsController, MCP_DEFAULT_PROTOCOL_VERSION, MCP_HTTP_ALLOW, MCP_HTTP_ALLOWED_METHODS, MCP_HTTP_DEFAULT_ALLOWED_HEADERS, 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, McpServerError, McpSessionStore, McpTool, McpToolNotFoundError, McpToolRegistry, MigrationModel, ModelController, ModelService, PageModel, PageTypes, PagesController, PermissionModel, PermissionsController, ProfileController, RegisterController, RegisterModel, RegisterWorker, ReqAccess, ReqGroup, ReqGroups, ReqPermission, ReqPermissions, ReqTenant, ReqTenants, ReqUser, RoleModel, RolePermissionModel, RolesController, RolesPermissionsController, Secret, SecretModel, Service, SessionModel, SessionStore, SetupController, TenantModel, TenantStatus, TenantsController, TestController, UserAuthModel, UserGroupModel, UserKeyModel, UserModel, UserPasswordModel, UserService, UserStatus, UserTenantModel, UsersController, UsersGroupsController, UsersKeysController, UsersTenantsController, WorkerRegistry, assertValidMcpToolDefinition, canFactory, discoverMcpTools, getMcpToolMetadata, isJsonParseError, isJsonRpcId, jsonParseErrorResponse, jsonRpcError, jsonRpcErrorFromCode, jsonRpcResult, parseJsonRpcRequest, sequelize };
-export type { ApplicationEvents, AuthEvents, AuthResult, ForgotEvents, McpCallToolResult, McpDecoratedToolHandler, McpHttpHandlerOptions, McpHttpResponse, McpJsonRpcErrorBody, McpJsonRpcErrorResult, McpJsonRpcId, McpJsonRpcRequest, McpJsonRpcResult, McpLogger, McpNormalizedValidation, McpProtocolVersion, McpRegisteredTool, McpSession, McpToolCallLog, McpToolContext, McpToolDeclaration, McpToolDefinition, McpToolHandlerResult, McpToolInput, McpToolMetadata, McpToolOptions, McpToolOutput, ModelArgumentsBase, ModelArgumentsCount, ModelArgumentsCreate, ModelArgumentsDelete, ModelArgumentsFindAll, ModelArgumentsFindOne, ModelArgumentsInclude, ModelArgumentsUpdate, ModelCallbackFindAll, ModelCallbackFindOne, ModelOptions, ModelResultFindAll, RegisterEvents, WorkerConstructor, WorkerDefinition, WorkerInstance };
+export { Application, Audit, AuditModel, AuditTypes, AuditsController, AuthController, AuthService, BaseController, CanCreate, CanDelete, CanRead, CanUpdate, Config, ConfigModel, CrudController, Env, FilesController, ForgotController, ForgotModel, GroupModel, GroupRoleModel, GroupTypes, GroupsController, GroupsPermissionsController, GroupsRolesController, HasGroups, HasPermissions, HasScope, HealthController, IsAuthenticated, Log, LogLevels, LogModel, Loggable, LogsController, McpController, McpTool, MigrationModel, ModelController, ModelService, PageModel, PageTypes, PagesController, PermissionModel, PermissionsController, ProfileController, RegisterController, RegisterModel, RegisterWorker, ReqAccess, ReqGroup, ReqGroups, ReqPermission, ReqPermissions, ReqTenant, ReqTenants, ReqUser, RoleModel, RolePermissionModel, RolesController, RolesPermissionsController, Secret, SecretModel, Service, SessionModel, SessionStore, SetupService, TenantModel, TenantStatus, TenantsController, TestController, UserAuthModel, UserGroupModel, UserKeyModel, UserModel, UserPasswordModel, UserService, UserStatus, UserTenantModel, UsersController, UsersGroupsController, UsersKeysController, UsersTenantsController, WorkerRegistry, canFactory, sequelize };
+export type { ApplicationEvents, AuthEvents, AuthResult, ForgotEvents, McpCallToolResult, McpErrorLog, McpErrorSource, McpHttpRequestLike, McpLogger, McpPreparedTool, McpPreparedValidation, McpPrincipal, McpPrincipalTenant, McpRegisteredTool, McpServerHandlerOptions, McpToolCallError, McpToolCallLog, McpToolContext, McpToolDeclaration, McpToolHandlerResult, McpToolInput, McpToolMetadata, McpToolOptions, McpToolOutput, ModelArgumentsBase, ModelArgumentsCount, ModelArgumentsCreate, ModelArgumentsDelete, ModelArgumentsFindAll, ModelArgumentsFindOne, ModelArgumentsInclude, ModelArgumentsUpdate, ModelCallbackFindAll, ModelCallbackFindOne, ModelOptions, ModelResultFindAll, RegisterEvents, SetupOptions, WorkerConstructor, WorkerDefinition, WorkerInstance };