@leanmcp/core 0.3.11 → 0.3.13

package/README.md

@@ -36,6 +36,7 @@
 - **Schema Generation** — Declarative JSON Schema with `@SchemaConstraint` decorators
 - **HTTP Transport** — Production-ready HTTP server with session management
 - **Input Validation** — Built-in AJV validation for all inputs
+- **Structured Content** — Automatic `structuredContent` for ChatGPT Apps SDK compatibility
 - **MCP Compliant** — Built on official `@modelcontextprotocol/sdk`
 
 ## Installation
@@ -358,6 +359,42 @@ export class SlackService {
 
 ---
 
+## Structured Content
+
+Tool return values are automatically exposed as `structuredContent` in the MCP response, enabling ChatGPT Apps SDK compatibility.
+
+**Automatic Handling:**
+
+```typescript
+@Tool({ description: 'List channels' })
+async listChannels() {
+  // Return a plain object - it becomes structuredContent automatically
+  return { channels: [...] };
+}
+```
+
+The response includes both `content` (text) and `structuredContent` (object):
+
+```json
+{
+  "content": [{ "type": "text", "text": "{\"channels\": [...]}" }],
+  "structuredContent": { "channels": [...] }
+}
+```
+
+**Manual MCP Response:**
+
+If your tool returns a manual MCP response (with `content` array), the SDK extracts data from `content[0].text`:
+
+```typescript
+return {
+  content: [{ type: 'text', text: JSON.stringify({ channels }) }]
+};
+// structuredContent will be { channels: [...] }
+```
+
+---
+
 ## HTTP Endpoints
 
 | Endpoint | Method | Description |

package/dist/chunk-LPEX4YW6.mjs

@@ -0,0 +1,13 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __name,
+  __require
+};

package/dist/index.d.mts

@@ -1,8 +1,36 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
+/**
+ * Security scheme for MCP tools (per MCP authorization spec)
+ *
+ * @example
+ * ```typescript
+ * @Tool({
+ *   description: 'Fetch user data',
+ *   securitySchemes: [{ type: 'oauth2', scopes: ['read:user'] }],
+ * })
+ * async fetchUser() { ... }
+ * ```
+ */
+interface SecurityScheme {
+    /** Type of security - 'noauth' for anonymous, 'oauth2' for OAuth */
+    type: 'noauth' | 'oauth2';
+    /** Required OAuth scopes (for oauth2 type) */
+    scopes?: string[];
+}
 interface ToolOptions {
     description?: string;
     inputClass?: any;
+    /**
+     * Security schemes for this tool (MCP authorization spec)
+     *
+     * - `noauth`: Tool is callable anonymously
+     * - `oauth2`: Tool requires OAuth 2.0 access token
+     *
+     * If both are listed, tool works anonymously but OAuth unlocks more features.
+     * If omitted, tool inherits server-level defaults.
+     */
+    securitySchemes?: SecurityScheme[];
 }
 interface PromptOptions {
     description?: string;
@@ -30,6 +58,14 @@ interface PromptOptions {
  * async analyzeSentiment(args: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
  *   // Tool name will be: "analyzeSentiment"
  * }
+ *
+ * @example
+ * // Tool with OAuth requirement
+ * @Tool({
+ *   description: 'Fetch private user data',
+ *   securitySchemes: [{ type: 'oauth2', scopes: ['read:user'] }],
+ * })
+ * async fetchPrivateData() { ... }
  */
 declare function Tool(options?: ToolOptions): MethodDecorator;
 /**
@@ -253,6 +289,49 @@ interface HTTPServerOptions {
     sessionTimeout?: number;
     stateless?: boolean;
     dashboard?: boolean;
+    /** OAuth/Auth configuration (MCP authorization spec) */
+    auth?: HTTPServerAuthOptions;
+}
+/**
+ * OAuth/Auth configuration for MCP server
+ *
+ * Enables MCP authorization spec compliance by exposing
+ * `/.well-known/oauth-protected-resource` (RFC 9728)
+ */
+interface HTTPServerAuthOptions {
+    /** Resource identifier (defaults to server URL) */
+    resource?: string;
+    /** Authorization servers (defaults to self) */
+    authorizationServers?: string[];
+    /** Supported OAuth scopes */
+    scopesSupported?: string[];
+    /** Documentation URL */
+    documentationUrl?: string;
+    /** Enable built-in OAuth authorization server */
+    enableOAuthServer?: boolean;
+    /** OAuth server options (when enableOAuthServer is true) */
+    oauthServerOptions?: {
+        /** Session secret for signing tokens/state */
+        sessionSecret: string;
+        /** JWT signing secret (defaults to sessionSecret if not provided) */
+        jwtSigningSecret?: string;
+        /** JWT encryption secret for encrypting upstream tokens */
+        jwtEncryptionSecret?: Buffer;
+        /** Issuer URL for JWTs */
+        issuer?: string;
+        /** Access token TTL in seconds (default: 3600) */
+        tokenTTL?: number;
+        /** Upstream OAuth provider configuration */
+        upstreamProvider?: {
+            id: string;
+            authorizationEndpoint: string;
+            tokenEndpoint: string;
+            clientId: string;
+            clientSecret: string;
+            scopes?: string[];
+            userInfoEndpoint?: string;
+        };
+    };
 }
 interface MCPServerFactory {
     (): Server | Promise<Server>;
@@ -348,6 +427,107 @@ declare function validateNonEmpty(value: string, fieldName: string): void;
  */
 declare function validateUrl(url: string, allowedProtocols?: string[]): void;
 
+/**
+ * MCP Authorization Helpers
+ *
+ * Utilities for implementing MCP authorization spec in tools.
+ * Provides helpers for auth error responses and token verification.
+ */
+/**
+ * Options for creating an auth error response
+ */
+interface AuthErrorOptions {
+    /** URL to the protected resource metadata */
+    resourceMetadataUrl: string;
+    /** OAuth error code */
+    error?: 'invalid_token' | 'expired_token' | 'insufficient_scope';
+    /** Human-readable error description */
+    errorDescription?: string;
+    /** Required scopes that were missing */
+    requiredScopes?: string[];
+}
+/**
+ * MCP-compliant auth error result structure
+ */
+interface AuthErrorResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    _meta: {
+        'mcp/www_authenticate': string[];
+    };
+    isError: true;
+}
+/**
+ * Create an MCP-compliant auth error result
+ *
+ * Returns the proper `_meta["mcp/www_authenticate"]` format that triggers
+ * ChatGPT's OAuth linking UI.
+ *
+ * @example
+ * ```typescript
+ * @Tool({
+ *   description: 'Fetch private data',
+ *   securitySchemes: [{ type: 'oauth2', scopes: ['read:private'] }],
+ * })
+ * async fetchPrivateData(): Promise<any> {
+ *   const token = this.getAccessToken();
+ *
+ *   if (!token) {
+ *     return createAuthError('Please authenticate to access this feature', {
+ *       resourceMetadataUrl: `${process.env.PUBLIC_URL}/.well-known/oauth-protected-resource`,
+ *       error: 'invalid_token',
+ *       errorDescription: 'No access token provided',
+ *     });
+ *   }
+ *
+ *   // Proceed with authenticated request...
+ * }
+ * ```
+ *
+ * @param message - User-facing error message
+ * @param options - Auth error options
+ * @returns MCP-compliant auth error result
+ */
+declare function createAuthError(message: string, options: AuthErrorOptions): AuthErrorResult;
+/**
+ * Check if a result is an auth error
+ */
+declare function isAuthError(result: unknown): result is AuthErrorResult;
+/**
+ * Extract access token from Authorization header
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The bearer token, or null if not present/valid
+ */
+declare function extractBearerToken(authHeader: string | undefined): string | null;
+/**
+ * Protected Resource Metadata (RFC 9728)
+ */
+interface ProtectedResourceMetadata {
+    /** Canonical resource identifier */
+    resource: string;
+    /** Authorization servers that can authorize access */
+    authorization_servers: string[];
+    /** Scopes supported by this resource */
+    scopes_supported?: string[];
+    /** Resource documentation URL */
+    resource_documentation?: string;
+}
+/**
+ * Generate Protected Resource Metadata document
+ *
+ * @param options - Metadata options
+ * @returns RFC 9728 compliant metadata
+ */
+declare function createProtectedResourceMetadata(options: {
+    resource: string;
+    authorizationServers?: string[];
+    scopesSupported?: string[];
+    documentationUrl?: string;
+}): ProtectedResourceMetadata;
+
 interface MCPServerOptions {
     servicesDir: string;
     port?: number;
@@ -488,16 +668,10 @@ declare class MCPServer {
         method: string;
         params?: {
             [x: string]: unknown;
-            task?: {
-                [x: string]: unknown;
-                ttl?: number | null | undefined;
-                pollInterval?: number | undefined;
-            } | undefined;
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -508,8 +682,8 @@ declare class MCPServer {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -518,8 +692,8 @@ declare class MCPServer {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
             "io.modelcontextprotocol/related-task"?: {
-                [x: string]: unknown;
                 taskId: string;
             } | undefined;
         } | undefined;
@@ -549,16 +723,10 @@ declare class MCPServerRuntime {
         method: string;
         params?: {
             [x: string]: unknown;
-            task?: {
-                [x: string]: unknown;
-                ttl?: number | null | undefined;
-                pollInterval?: number | undefined;
-            } | undefined;
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -569,8 +737,8 @@ declare class MCPServerRuntime {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -579,8 +747,8 @@ declare class MCPServerRuntime {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
             "io.modelcontextprotocol/related-task"?: {
-                [x: string]: unknown;
                 taskId: string;
             } | undefined;
         } | undefined;
@@ -594,4 +762,4 @@ declare class MCPServerRuntime {
  */
 declare function startMCPServer(options: MCPServerOptions): Promise<MCPServerRuntime>;
 
-export { Auth, type AuthOptions, Deprecated, type HTTPServerInput, type HTTPServerOptions, LogLevel, type LogPayload, Logger, type LoggerHandler, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, Render, Resource, type ResourceOptions, SchemaConstraint, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createHTTPServer, defaultLogger, getDecoratedMethods, getMethodMetadata, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };
+export { Auth, type AuthErrorOptions, type AuthErrorResult, type AuthOptions, Deprecated, type HTTPServerAuthOptions, type HTTPServerInput, type HTTPServerOptions, LogLevel, type LogPayload, Logger, type LoggerHandler, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, type ProtectedResourceMetadata, Render, Resource, type ResourceOptions, SchemaConstraint, type SecurityScheme, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createAuthError, createHTTPServer, createProtectedResourceMetadata, defaultLogger, extractBearerToken, getDecoratedMethods, getMethodMetadata, isAuthError, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };

package/dist/index.d.ts

@@ -1,8 +1,36 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
+/**
+ * Security scheme for MCP tools (per MCP authorization spec)
+ *
+ * @example
+ * ```typescript
+ * @Tool({
+ *   description: 'Fetch user data',
+ *   securitySchemes: [{ type: 'oauth2', scopes: ['read:user'] }],
+ * })
+ * async fetchUser() { ... }
+ * ```
+ */
+interface SecurityScheme {
+    /** Type of security - 'noauth' for anonymous, 'oauth2' for OAuth */
+    type: 'noauth' | 'oauth2';
+    /** Required OAuth scopes (for oauth2 type) */
+    scopes?: string[];
+}
 interface ToolOptions {
     description?: string;
     inputClass?: any;
+    /**
+     * Security schemes for this tool (MCP authorization spec)
+     *
+     * - `noauth`: Tool is callable anonymously
+     * - `oauth2`: Tool requires OAuth 2.0 access token
+     *
+     * If both are listed, tool works anonymously but OAuth unlocks more features.
+     * If omitted, tool inherits server-level defaults.
+     */
+    securitySchemes?: SecurityScheme[];
 }
 interface PromptOptions {
     description?: string;
@@ -30,6 +58,14 @@ interface PromptOptions {
  * async analyzeSentiment(args: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
  *   // Tool name will be: "analyzeSentiment"
  * }
+ *
+ * @example
+ * // Tool with OAuth requirement
+ * @Tool({
+ *   description: 'Fetch private user data',
+ *   securitySchemes: [{ type: 'oauth2', scopes: ['read:user'] }],
+ * })
+ * async fetchPrivateData() { ... }
  */
 declare function Tool(options?: ToolOptions): MethodDecorator;
 /**
@@ -253,6 +289,49 @@ interface HTTPServerOptions {
     sessionTimeout?: number;
     stateless?: boolean;
     dashboard?: boolean;
+    /** OAuth/Auth configuration (MCP authorization spec) */
+    auth?: HTTPServerAuthOptions;
+}
+/**
+ * OAuth/Auth configuration for MCP server
+ *
+ * Enables MCP authorization spec compliance by exposing
+ * `/.well-known/oauth-protected-resource` (RFC 9728)
+ */
+interface HTTPServerAuthOptions {
+    /** Resource identifier (defaults to server URL) */
+    resource?: string;
+    /** Authorization servers (defaults to self) */
+    authorizationServers?: string[];
+    /** Supported OAuth scopes */
+    scopesSupported?: string[];
+    /** Documentation URL */
+    documentationUrl?: string;
+    /** Enable built-in OAuth authorization server */
+    enableOAuthServer?: boolean;
+    /** OAuth server options (when enableOAuthServer is true) */
+    oauthServerOptions?: {
+        /** Session secret for signing tokens/state */
+        sessionSecret: string;
+        /** JWT signing secret (defaults to sessionSecret if not provided) */
+        jwtSigningSecret?: string;
+        /** JWT encryption secret for encrypting upstream tokens */
+        jwtEncryptionSecret?: Buffer;
+        /** Issuer URL for JWTs */
+        issuer?: string;
+        /** Access token TTL in seconds (default: 3600) */
+        tokenTTL?: number;
+        /** Upstream OAuth provider configuration */
+        upstreamProvider?: {
+            id: string;
+            authorizationEndpoint: string;
+            tokenEndpoint: string;
+            clientId: string;
+            clientSecret: string;
+            scopes?: string[];
+            userInfoEndpoint?: string;
+        };
+    };
 }
 interface MCPServerFactory {
     (): Server | Promise<Server>;
@@ -348,6 +427,107 @@ declare function validateNonEmpty(value: string, fieldName: string): void;
  */
 declare function validateUrl(url: string, allowedProtocols?: string[]): void;
 
+/**
+ * MCP Authorization Helpers
+ *
+ * Utilities for implementing MCP authorization spec in tools.
+ * Provides helpers for auth error responses and token verification.
+ */
+/**
+ * Options for creating an auth error response
+ */
+interface AuthErrorOptions {
+    /** URL to the protected resource metadata */
+    resourceMetadataUrl: string;
+    /** OAuth error code */
+    error?: 'invalid_token' | 'expired_token' | 'insufficient_scope';
+    /** Human-readable error description */
+    errorDescription?: string;
+    /** Required scopes that were missing */
+    requiredScopes?: string[];
+}
+/**
+ * MCP-compliant auth error result structure
+ */
+interface AuthErrorResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    _meta: {
+        'mcp/www_authenticate': string[];
+    };
+    isError: true;
+}
+/**
+ * Create an MCP-compliant auth error result
+ *
+ * Returns the proper `_meta["mcp/www_authenticate"]` format that triggers
+ * ChatGPT's OAuth linking UI.
+ *
+ * @example
+ * ```typescript
+ * @Tool({
+ *   description: 'Fetch private data',
+ *   securitySchemes: [{ type: 'oauth2', scopes: ['read:private'] }],
+ * })
+ * async fetchPrivateData(): Promise<any> {
+ *   const token = this.getAccessToken();
+ *
+ *   if (!token) {
+ *     return createAuthError('Please authenticate to access this feature', {
+ *       resourceMetadataUrl: `${process.env.PUBLIC_URL}/.well-known/oauth-protected-resource`,
+ *       error: 'invalid_token',
+ *       errorDescription: 'No access token provided',
+ *     });
+ *   }
+ *
+ *   // Proceed with authenticated request...
+ * }
+ * ```
+ *
+ * @param message - User-facing error message
+ * @param options - Auth error options
+ * @returns MCP-compliant auth error result
+ */
+declare function createAuthError(message: string, options: AuthErrorOptions): AuthErrorResult;
+/**
+ * Check if a result is an auth error
+ */
+declare function isAuthError(result: unknown): result is AuthErrorResult;
+/**
+ * Extract access token from Authorization header
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The bearer token, or null if not present/valid
+ */
+declare function extractBearerToken(authHeader: string | undefined): string | null;
+/**
+ * Protected Resource Metadata (RFC 9728)
+ */
+interface ProtectedResourceMetadata {
+    /** Canonical resource identifier */
+    resource: string;
+    /** Authorization servers that can authorize access */
+    authorization_servers: string[];
+    /** Scopes supported by this resource */
+    scopes_supported?: string[];
+    /** Resource documentation URL */
+    resource_documentation?: string;
+}
+/**
+ * Generate Protected Resource Metadata document
+ *
+ * @param options - Metadata options
+ * @returns RFC 9728 compliant metadata
+ */
+declare function createProtectedResourceMetadata(options: {
+    resource: string;
+    authorizationServers?: string[];
+    scopesSupported?: string[];
+    documentationUrl?: string;
+}): ProtectedResourceMetadata;
+
 interface MCPServerOptions {
     servicesDir: string;
     port?: number;
@@ -488,16 +668,10 @@ declare class MCPServer {
         method: string;
         params?: {
             [x: string]: unknown;
-            task?: {
-                [x: string]: unknown;
-                ttl?: number | null | undefined;
-                pollInterval?: number | undefined;
-            } | undefined;
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -508,8 +682,8 @@ declare class MCPServer {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -518,8 +692,8 @@ declare class MCPServer {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
             "io.modelcontextprotocol/related-task"?: {
-                [x: string]: unknown;
                 taskId: string;
             } | undefined;
         } | undefined;
@@ -549,16 +723,10 @@ declare class MCPServerRuntime {
         method: string;
         params?: {
             [x: string]: unknown;
-            task?: {
-                [x: string]: unknown;
-                ttl?: number | null | undefined;
-                pollInterval?: number | undefined;
-            } | undefined;
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -569,8 +737,8 @@ declare class MCPServerRuntime {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -579,8 +747,8 @@ declare class MCPServerRuntime {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
             "io.modelcontextprotocol/related-task"?: {
-                [x: string]: unknown;
                 taskId: string;
             } | undefined;
         } | undefined;
@@ -594,4 +762,4 @@ declare class MCPServerRuntime {
  */
 declare function startMCPServer(options: MCPServerOptions): Promise<MCPServerRuntime>;
 
-export { Auth, type AuthOptions, Deprecated, type HTTPServerInput, type HTTPServerOptions, LogLevel, type LogPayload, Logger, type LoggerHandler, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, Render, Resource, type ResourceOptions, SchemaConstraint, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createHTTPServer, defaultLogger, getDecoratedMethods, getMethodMetadata, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };
+export { Auth, type AuthErrorOptions, type AuthErrorResult, type AuthOptions, Deprecated, type HTTPServerAuthOptions, type HTTPServerInput, type HTTPServerOptions, LogLevel, type LogPayload, Logger, type LoggerHandler, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, type ProtectedResourceMetadata, Render, Resource, type ResourceOptions, SchemaConstraint, type SecurityScheme, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createAuthError, createHTTPServer, createProtectedResourceMetadata, defaultLogger, extractBearerToken, getDecoratedMethods, getMethodMetadata, isAuthError, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };