mcp-use 1.6.2 → 1.7.0-canary.1

package/dist/src/server/oauth/providers.d.ts

@@ -0,0 +1,208 @@
+/**
+ * OAuth Provider Factory Functions
+ *
+ * Export factory functions for creating OAuth providers with better
+ * type safety and developer experience.
+ */
+import type { OAuthProvider } from "./providers/types.js";
+import type { UserInfo } from "./providers/types.js";
+/**
+ * Configuration for Supabase OAuth provider
+ */
+export interface SupabaseProviderConfig {
+    projectId: string;
+    jwtSecret?: string;
+    skipVerification?: boolean;
+}
+/**
+ * Configuration for Auth0 OAuth provider
+ */
+export interface Auth0ProviderConfig {
+    domain: string;
+    audience: string;
+    verifyJwt?: boolean;
+}
+/**
+ * Configuration for Keycloak OAuth provider
+ */
+export interface KeycloakProviderConfig {
+    serverUrl: string;
+    realm: string;
+    clientId?: string;
+    verifyJwt?: boolean;
+}
+/**
+ * Configuration for WorkOS OAuth provider
+ */
+export interface WorkOSProviderConfig {
+    subdomain: string;
+    clientId?: string;
+    apiKey?: string;
+    verifyJwt?: boolean;
+}
+/**
+ * Configuration for Custom OAuth provider
+ */
+export interface CustomProviderConfig {
+    issuer: string;
+    jwksUrl: string;
+    authEndpoint: string;
+    tokenEndpoint: string;
+    scopesSupported?: string[];
+    grantTypesSupported?: string[];
+    verifyToken: (token: string) => Promise<any>;
+    getUserInfo?: (payload: any) => UserInfo;
+}
+/**
+ * Create a Supabase OAuth provider
+ *
+ * Supports zero-config setup via environment variables:
+ * - MCP_USE_OAUTH_SUPABASE_PROJECT_ID (required)
+ * - MCP_USE_OAUTH_SUPABASE_JWT_SECRET (optional)
+ *
+ * @param config - Optional Supabase configuration (overrides environment variables)
+ * @returns OAuthProvider instance
+ *
+ * @example Zero-config with environment variables
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthSupabaseProvider()
+ * });
+ * ```
+ *
+ * @example With explicit configuration
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthSupabaseProvider({
+ *     projectId: 'my-project',
+ *     jwtSecret: process.env.SUPABASE_JWT_SECRET
+ *   })
+ * });
+ * ```
+ */
+export declare function oauthSupabaseProvider(config?: Partial<SupabaseProviderConfig>): OAuthProvider;
+/**
+ * Create an Auth0 OAuth provider
+ *
+ * Supports zero-config setup via environment variables:
+ * - MCP_USE_OAUTH_AUTH0_DOMAIN (required)
+ * - MCP_USE_OAUTH_AUTH0_AUDIENCE (required)
+ *
+ * @param config - Optional Auth0 configuration (overrides environment variables)
+ * @returns OAuthProvider instance
+ *
+ * @example Zero-config with environment variables
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthAuth0Provider()
+ * });
+ * ```
+ *
+ * @example With explicit configuration
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthAuth0Provider({
+ *     domain: 'my-tenant.auth0.com',
+ *     audience: 'https://my-api.com'
+ *   })
+ * });
+ * ```
+ */
+export declare function oauthAuth0Provider(config?: Partial<Auth0ProviderConfig>): OAuthProvider;
+/**
+ * Create a Keycloak OAuth provider
+ *
+ * Supports zero-config setup via environment variables:
+ * - MCP_USE_OAUTH_KEYCLOAK_SERVER_URL (required)
+ * - MCP_USE_OAUTH_KEYCLOAK_REALM (required)
+ * - MCP_USE_OAUTH_KEYCLOAK_CLIENT_ID (optional)
+ *
+ * @param config - Optional Keycloak configuration (overrides environment variables)
+ * @returns OAuthProvider instance
+ *
+ * @example Zero-config with environment variables
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthKeycloakProvider()
+ * });
+ * ```
+ *
+ * @example With explicit configuration
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthKeycloakProvider({
+ *     serverUrl: 'https://keycloak.example.com',
+ *     realm: 'my-realm',
+ *     clientId: 'my-client'
+ *   })
+ * });
+ * ```
+ */
+export declare function oauthKeycloakProvider(config?: Partial<KeycloakProviderConfig>): OAuthProvider;
+/**
+ * Create a WorkOS OAuth provider
+ *
+ * Supports two OAuth modes:
+ *
+ * **1. Dynamic Client Registration (DCR)** - Recommended for MCP
+ * - Don't set MCP_USE_OAUTH_WORKOS_CLIENT_ID
+ * - MCP clients register themselves automatically with WorkOS
+ * - Enable DCR in WorkOS Dashboard under Connect → Configuration
+ *
+ * **2. Pre-registered OAuth Client** - For custom setups
+ * - Set MCP_USE_OAUTH_WORKOS_CLIENT_ID to your OAuth client ID from WorkOS Dashboard
+ * - Create the client in WorkOS Dashboard under Connect → OAuth Applications
+ * - Configure redirect URIs in the dashboard to match your MCP client
+ *
+ * Environment variables:
+ * - MCP_USE_OAUTH_WORKOS_SUBDOMAIN (required)
+ * - MCP_USE_OAUTH_WORKOS_CLIENT_ID (optional, for pre-registered client)
+ * - MCP_USE_OAUTH_WORKOS_API_KEY (optional, for WorkOS API calls)
+ *
+ * @param config - Optional WorkOS configuration (overrides environment variables)
+ * @returns OAuthProvider instance
+ *
+ * @example Dynamic Client Registration (recommended)
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthWorkOSProvider({
+ *     subdomain: 'my-company'
+ *   })
+ * });
+ * ```
+ *
+ * @example Pre-registered OAuth Client
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthWorkOSProvider({
+ *     subdomain: 'my-company',
+ *     clientId: 'client_01KB5DRXBDDY1VGCBKY108SKJW'
+ *   })
+ * });
+ * ```
+ */
+export declare function oauthWorkOSProvider(config?: Partial<WorkOSProviderConfig>): OAuthProvider;
+/**
+ * Create a custom OAuth provider
+ *
+ * @param config - Custom provider configuration
+ * @returns OAuthProvider instance
+ *
+ * @example
+ * ```typescript
+ * const server = createMCPServer('my-server', {
+ *   oauth: oauthCustomProvider({
+ *     issuer: 'https://oauth.example.com',
+ *     jwksUrl: 'https://oauth.example.com/.well-known/jwks.json',
+ *     authEndpoint: 'https://oauth.example.com/authorize',
+ *     tokenEndpoint: 'https://oauth.example.com/token',
+ *     verifyToken: async (token) => {
+ *       // Custom verification logic
+ *       return jwtVerify(token, ...);
+ *     }
+ *   })
+ * });
+ * ```
+ */
+export declare function oauthCustomProvider(config: CustomProviderConfig): OAuthProvider;
+//# sourceMappingURL=providers.d.ts.map

package/dist/src/server/oauth/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../../src/server/oauth/providers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAM1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGrD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7C,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,QAAQ,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC3C,aAAa,CAmBf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM,GACxC,aAAa,CAwBf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC3C,aAAa,CA4Bf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM,GACzC,aAAa,CAwCf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,GAC3B,aAAa,CAKf"}

package/dist/src/server/oauth/routes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OAuth Routes
+ *
+ * Sets up OAuth 2.0 endpoints based on the provider's mode:
+ *
+ * **Direct Mode** (e.g., WorkOS):
+ * - Clients communicate directly with the OAuth provider
+ * - MCP server only provides metadata endpoints for discovery
+ * - No proxying of OAuth requests
+ *
+ * **Proxy Mode** (legacy):
+ * - MCP server proxies OAuth requests to the provider
+ * - Provides /authorize and /token endpoints
+ */
+import type { Hono } from "hono";
+import type { OAuthProvider } from "./providers/types.js";
+/**
+ * Setup OAuth routes on the Hono app
+ *
+ * In direct mode (e.g., WorkOS), creates:
+ * - GET /.well-known/oauth-authorization-server - Proxies provider's OAuth metadata
+ * - GET /.well-known/oauth-protected-resource - Protected resource metadata
+ *
+ * In proxy mode (legacy), also creates:
+ * - GET/POST /authorize - Authorization endpoint
+ * - POST /token - Token exchange endpoint
+ *
+ * @param app - The Hono application instance
+ * @param provider - The OAuth provider
+ * @param baseUrl - The base URL of this server (for metadata)
+ */
+export declare function setupOAuthRoutes(app: Hono, provider: OAuthProvider, baseUrl: string): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/src/server/oauth/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../../src/server/oauth/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,MAAM,GACd,IAAI,CA4PN"}

package/dist/src/server/oauth/utils.d.ts

@@ -0,0 +1,155 @@
+/**
+ * OAuth Utility Helpers
+ *
+ * Provides convenience functions for scope/permission checking and
+ * accessing authentication information in tool callbacks and middleware.
+ */
+import type { Context, Next } from "hono";
+/**
+ * Authentication information extracted from context
+ */
+export interface AuthInfo {
+    user: any;
+    payload: any;
+    accessToken: string;
+    scopes: string[];
+    permissions: string[];
+}
+/**
+ * Get authentication info from context
+ *
+ * Works in both middleware and tool callbacks (via requestContext parameter).
+ *
+ * Note: With the new API, you can access auth directly via `requestContext.auth`
+ * This function is kept for backward compatibility.
+ *
+ * @param context - Hono context (from middleware or tool requestContext)
+ * @returns Authentication information
+ *
+ * @example
+ * ```typescript
+ * // New way (preferred):
+ * server.tool({
+ *   name: 'my-tool',
+ *   cb: async (params, ctx, requestContext) => {
+ *     const auth = requestContext.auth;
+ *     console.log(auth.user.email);
+ *     console.log(auth.scopes);
+ *   }
+ * });
+ *
+ * // Old way (still works):
+ * server.tool({
+ *   name: 'my-tool',
+ *   cb: async (params, ctx, req) => {
+ *     const auth = getAuth(req);
+ *     console.log(auth.user.email);
+ *   }
+ * });
+ * ```
+ */
+export declare function getAuth(context: Context): AuthInfo;
+/**
+ * Check if user has specific scope(s) or permission(s)
+ *
+ * Checks both OAuth scopes and permissions (Auth0 style).
+ * If multiple scopes are provided, ALL must be present.
+ * Use this inside tool callbacks to check scopes and return appropriate errors.
+ *
+ * @param context - Hono context (from tool requestContext parameter)
+ * @param needed - Single scope/permission or array of required scopes/permissions
+ * @returns true if user has all required scopes/permissions
+ *
+ * @example
+ * ```typescript
+ * // Check scope inside tool callback
+ * server.tool({
+ *   name: 'delete-data',
+ *   cb: async (params, ctx, requestContext) => {
+ *     if (!hasScope(requestContext, 'delete:data')) {
+ *       return {
+ *         content: [{ type: 'text', text: 'Insufficient permissions' }],
+ *         isError: true
+ *       };
+ *     }
+ *     // ... tool implementation
+ *   }
+ * });
+ *
+ * // Check multiple scopes
+ * if (hasScope(requestContext, ['read:data', 'write:data'])) {
+ *   // User has both read:data AND write:data
+ * }
+ * ```
+ */
+export declare function hasScope(context: Context, needed: string | string[]): boolean;
+/**
+ * Check if user has ANY of the provided scopes/permissions
+ *
+ * @param context - Hono context
+ * @param needed - Array of scopes/permissions (user needs at least one)
+ * @returns true if user has at least one of the required scopes/permissions
+ *
+ * @example
+ * ```typescript
+ * if (hasAnyScope(req, ['admin', 'moderator'])) {
+ *   // User is either an admin OR moderator
+ * }
+ * ```
+ */
+export declare function hasAnyScope(context: Context, needed: string[]): boolean;
+/**
+ * Create middleware that requires specific scope(s)/permission(s)
+ *
+ * Returns 403 Forbidden if user doesn't have the required scope(s).
+ * If multiple scopes are provided, ALL must be present.
+ * Note: For tool-level scope checking, use hasScope() inside the tool callback instead.
+ *
+ * @param needed - Single scope/permission or array of required scopes/permissions
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```typescript
+ * // Use on custom routes
+ * app.post('/admin/users', requireScope('admin'), async (c) => {
+ *   // Only users with 'admin' scope can access
+ * });
+ *
+ * // Require multiple scopes on a route
+ * app.delete('/data/:id', requireScope(['admin', 'delete:data']), async (c) => {
+ *   // User must have both scopes
+ * });
+ * ```
+ */
+export declare function requireScope(needed: string | string[]): (c: Context, next: Next) => Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+    required: string[];
+    granted_scopes: string[];
+    granted_permissions: string[];
+    message: string;
+}, 403, "json">) | undefined>;
+/**
+ * Create middleware that requires ANY of the provided scopes/permissions
+ *
+ * Returns 403 Forbidden if user doesn't have at least one required scope.
+ * Note: For tool-level scope checking, use hasAnyScope() inside the tool callback instead.
+ *
+ * @param needed - Array of scopes/permissions (user needs at least one)
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```typescript
+ * // Use on custom routes - user needs to be either admin OR moderator
+ * app.post('/moderate', requireAnyScope(['admin', 'moderator']), async (c) => {
+ *   // User has at least one of the required scopes
+ * });
+ * ```
+ */
+export declare function requireAnyScope(needed: string[]): (c: Context, next: Next) => Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+    required_any: string[];
+    granted_scopes: string[];
+    granted_permissions: string[];
+    message: string;
+}, 403, "json">) | undefined>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/server/oauth/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/server/oauth/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,GAAG,CAAC;IACV,OAAO,EAAE,GAAG,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAQ7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAOvE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,IACtC,GAAG,OAAO,EAAE,MAAM,IAAI;;;;;;8BAkBrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAChC,GAAG,OAAO,EAAE,MAAM,IAAI;;;;;;8BAiBrC"}

package/dist/src/server/types/common.d.ts

@@ -1,6 +1,7 @@
 /**
  * Common type definitions shared across different MCP components
  */
+import type { OAuthProvider } from "../oauth/providers/types.js";
 export interface ServerConfig {
     name: string;
     version: string;
@@ -66,6 +67,52 @@ export interface ServerConfig {
      * ```
      */
     autoCreateSessionOnInvalidId?: boolean;
+    /**
+     * OAuth authentication configuration
+     *
+     * When provided, automatically sets up OAuth authentication for the server including:
+     * - OAuth routes (/authorize, /token, .well-known/*)
+     * - JWT verification middleware
+     * - Bearer token authentication on all /mcp routes
+     * - User information extraction and context attachment
+     *
+     * Use provider factory functions for type-safe configuration:
+     * - oauthSupabaseProvider() - Supabase OAuth
+     * - oauthAuth0Provider() - Auth0 OAuth
+     * - oauthKeycloakProvider() - Keycloak OAuth
+     * - oauthCustomProvider() - Custom OAuth implementation
+     *
+     * @example
+     * ```typescript
+     * import { createMCPServer, oauthSupabaseProvider } from 'mcp-use/server';
+     *
+     * // Supabase OAuth
+     * const server = createMCPServer('my-server', {
+     *   oauth: oauthSupabaseProvider({
+     *     projectId: 'my-project',
+     *     jwtSecret: process.env.SUPABASE_JWT_SECRET
+     *   })
+     * });
+     *
+     * // Auth0 OAuth
+     * const server = createMCPServer('my-server', {
+     *   oauth: oauthAuth0Provider({
+     *     domain: 'my-tenant.auth0.com',
+     *     audience: 'https://my-api.com'
+     *   })
+     * });
+     *
+     * // Keycloak OAuth
+     * const server = createMCPServer('my-server', {
+     *   oauth: oauthKeycloakProvider({
+     *     serverUrl: 'https://keycloak.example.com',
+     *     realm: 'my-realm',
+     *     clientId: 'my-client'
+     *   })
+     * });
+     * ```
+     */
+    oauth?: OAuthProvider;
 }
 export interface InputDefinition {
     name: string;

package/dist/src/server/types/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/server/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/server/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/src/server/types/context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Extended Hono Context types for MCP server
+ */
+import type { Context as HonoContext } from "hono";
+import type { AuthInfo } from "../oauth/utils.js";
+/**
+ * Base MCP Context without OAuth
+ */
+export interface McpContextBase extends HonoContext {
+    auth?: never;
+}
+/**
+ * MCP Context with OAuth configured
+ *
+ * When OAuth is configured, the auth property is automatically populated
+ * by the OAuth middleware and guaranteed to be available in tool callbacks.
+ */
+export interface McpContextWithAuth extends HonoContext {
+    /**
+     * Authentication information from OAuth provider
+     *
+     * Includes user info, JWT payload, access token, scopes, and permissions.
+     * Always available when OAuth is configured since tools are protected by default.
+     *
+     * TypeScript knows this is always defined (non-undefined) when OAuth is configured.
+     */
+    auth: AuthInfo;
+    readonly __hasOAuth?: true;
+}
+/**
+ * Conditional MCP Context type based on OAuth configuration
+ */
+export type McpContext<HasOAuth extends boolean = false> = HasOAuth extends true ? McpContextWithAuth : McpContextBase;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/server/types/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/server/types/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,IAAI,CAAC,EAAE,KAAK,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;OAOG;IACH,IAAI,EAAE,QAAQ,CAAC;IAGf,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,SAAS,OAAO,GAAG,KAAK,IAAI,QAAQ,SAAS,IAAI,GAC5E,kBAAkB,GAClB,cAAc,CAAC"}

package/dist/src/server/types/index.d.ts

@@ -2,7 +2,8 @@
  * Centralized type exports for MCP server
  */
 export { ServerConfig, InputDefinition, ResourceAnnotations, } from "./common.js";
+export { McpContext } from "./context.js";
 export { ReadResourceCallback, ReadResourceTemplateCallback, ResourceTemplateConfig, ResourceTemplateDefinition, ResourceDefinition, UIResourceContent, WidgetProps, UIEncoding, RemoteDomFramework, UIResourceDefinition, ExternalUrlUIResource, RawHtmlUIResource, RemoteDomUIResource, AppsSdkUIResource, WidgetConfig, WidgetManifest, DiscoverWidgetsOptions, AppsSdkMetadata, AppsSdkToolMetadata, } from "./resource.js";
-export { ToolCallback, ToolDefinition } from "./tool.js";
+export { ToolCallback, ToolDefinition, InferToolInput, InferToolOutput, EnhancedToolContext, } from "./tool.js";
 export { PromptCallback, PromptDefinition } from "./prompt.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/server/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,sBAAsB,EAEtB,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,sBAAsB,EAEtB,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/server/types/tool.d.ts

@@ -1,28 +1,96 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { InputDefinition } from "./common.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import type { ToolContext } from "../mcp-server.js";
+import type { McpContext } from "./context.js";
+import type { z } from "zod";
+import type { TypedCallToolResult } from "../utils/response-helpers.js";
+/**
+ * Enhanced Tool Context that combines ToolContext methods with Hono request context.
+ *
+ * This unified context provides:
+ * - `sample()` - LLM sampling method from ToolContext
+ * - `reportProgress()` - Progress reporting from ToolContext
+ * - `auth` - Authentication info (when OAuth is configured)
+ * - `req` - Hono request object
+ * - All other Hono Context properties and methods
+ *
+ * @template HasOAuth - Whether OAuth is configured (affects auth availability)
+ */
+export type EnhancedToolContext<HasOAuth extends boolean = false> = ToolContext & McpContext<HasOAuth>;
 /**
  * Callback function for tool execution.
- * Can optionally receive a ToolContext as the second parameter for sampling support.
+ *
+ * Accepts input parameters and an enhanced context object that provides:
+ * - LLM sampling via `ctx.sample()`
+ * - Progress reporting via `ctx.reportProgress()`
+ * - Authentication info via `ctx.auth` (when OAuth is configured)
+ * - HTTP request via `ctx.req`
+ * - All Hono Context properties and methods
+ *
+ * @template TInput - Input parameters type
+ * @template TOutput - Output type (constrains the structuredContent property when outputSchema is defined)
+ * @template HasOAuth - Whether OAuth is configured (affects ctx.auth availability)
+ *
+ * @example
+ * ```typescript
+ * // Simple tool without context
+ * cb: async ({ name }) => ({
+ *   content: [{ type: 'text', text: `Hello, ${name}!` }]
+ * })
+ *
+ * // Tool with sampling
+ * cb: async ({ text }, ctx) => {
+ *   const result = await ctx.sample({
+ *     messages: [{ role: 'user', content: { type: 'text', text } }]
+ *   });
+ *   return { content: result.content };
+ * }
+ *
+ * // Tool with authentication
+ * cb: async ({ userId }, ctx) => {
+ *   return { content: [{ type: 'text', text: `User: ${ctx.auth.user.email}` }] };
+ * }
+ * ```
+ */
+export type ToolCallback<TInput = Record<string, any>, TOutput extends Record<string, unknown> = Record<string, unknown>, HasOAuth extends boolean = false> = ((params: TInput) => Promise<TypedCallToolResult<TOutput>>) | ((params: TInput, ctx: EnhancedToolContext<HasOAuth>) => Promise<TypedCallToolResult<TOutput>>);
+/**
+ * Generic callback with full context support for better type inference.
+ * This variant always requires the context parameter.
+ */
+export type ToolCallbackWithContext<TInput = Record<string, any>, TOutput extends Record<string, unknown> = Record<string, unknown>, HasOAuth extends boolean = false> = (params: TInput, ctx: EnhancedToolContext<HasOAuth>) => Promise<TypedCallToolResult<TOutput>>;
+/**
+ * Extract input type from a tool definition's schema
+ */
+export type InferToolInput<T> = T extends {
+    schema: infer S;
+} ? S extends z.ZodTypeAny ? z.infer<S> : Record<string, any> : Record<string, any>;
+/**
+ * Extract output type from a tool definition's output schema
  */
-export type ToolCallback = (params: Record<string, any>, ctx?: ToolContext) => Promise<CallToolResult>;
-export interface ToolDefinition {
+export type InferToolOutput<T> = T extends {
+    outputSchema: infer S;
+} ? S extends z.ZodTypeAny ? z.infer<S> : Record<string, unknown> : Record<string, unknown>;
+export interface ToolDefinition<TInput = Record<string, any>, TOutput extends Record<string, unknown> = Record<string, unknown>, HasOAuth extends boolean = false> {
     /** Unique identifier for the tool */
     name: string;
     /** Human-readable title for the tool (displayed in UI) */
     title?: string;
-    /** Description of what the tool does */
+    /** Description of what the tool does (optional) */
     description?: string;
-    /** Input parameter definitions */
+    /** Input parameter definitions (legacy, use schema instead) */
+    /** @deprecated Use schema instead */
     inputs?: InputDefinition[];
+    /** Zod schema for input validation (alias for inputs, preferred) */
+    schema?: z.ZodObject<any>;
+    /** Zod schema for structured output validation */
+    outputSchema?: z.ZodObject<any>;
     /**
      * Async callback function that executes the tool.
-     * Receives tool parameters and optionally a ToolContext for sampling support.
+     * Receives tool parameters and an enhanced context with sampling, auth, and request info.
      *
      * @example
      * ```typescript
-     * // Simple tool without sampling
+     * // Simple tool without context
      * cb: async ({ name }) => ({
      *   content: [{ type: 'text', text: `Hello, ${name}!` }]
      * })
@@ -34,9 +102,14 @@ export interface ToolDefinition {
      *   });
      *   return { content: result.content };
      * }
+     *
+     * // Tool with authentication
+     * cb: async ({ userId }, ctx) => {
+     *   return { content: [{ type: 'text', text: `User: ${ctx.auth.user.email}` }] };
+     * }
      * ```
      */
-    cb: ToolCallback;
+    cb?: ToolCallback<TInput, TOutput, HasOAuth>;
     /** Tool annotations */
     annotations?: ToolAnnotations;
     /** Metadata for the tool */

package/dist/src/server/types/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../src/server/types/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,GAAG,CAAC,EAAE,WAAW,KACd,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,EAAE,EAAE,YAAY,CAAC;IACjB,uBAAuB;IACvB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../src/server/types/tool.ts"],"names":[],"mappings":"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"}

package/dist/src/server/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Server utility functions
+ */
+export * from "./response-helpers.js";
+export * from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map