diff --git a/packages/agents/src/keycardai/agents/__init__.py b/packages/agents/src/keycardai/agents/__init__.py index 2e86fec..c25c86c 100644 --- a/packages/agents/src/keycardai/agents/__init__.py +++ b/packages/agents/src/keycardai/agents/__init__.py @@ -30,16 +30,17 @@ crewai = None __all__ = [ - # Configuration + # === Configuration === "AgentServiceConfig", - # Client + # === Client (Calling Agent Services) === "AgentClient", "ServiceDiscovery", - # Server + # === Server (Building Agent Services) === "AgentServer", "create_agent_card_server", "serve_agent", + # === Server-to-Server Delegation === "DelegationClient", - # Integrations - "crewai", + # === Framework Integrations (Optional) === + "crewai", # May be None if crewai not installed ] diff --git a/packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/__init__.py b/packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/__init__.py index 15cb6b5..f4f7321 100644 --- a/packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/__init__.py +++ b/packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/__init__.py @@ -9,6 +9,14 @@ - Application credentials: ClientSecret, WebIdentity, EKSWorkloadIdentity for different authentication scenarios - Auth strategies: BasicAuth, MultiZoneBasicAuth, NoneAuth for HTTP client authentication +Re-export Guide: + Local definitions (primary API): AuthProvider, AccessContext + From keycardai.mcp.server.auth: ApplicationCredential, ClientSecret, EKSWorkloadIdentity, WebIdentity + From keycardai.mcp.server.auth.client_factory: ClientFactory, DefaultClientFactory + From keycardai.oauth.http.auth: AuthStrategy, BasicAuth, MultiZoneBasicAuth, NoneAuth + From keycardai.mcp.server.exceptions: All exceptions + For canonical imports, use the source packages directly. + Basic Usage: from fastmcp import FastMCP, Context @@ -102,43 +110,41 @@ async def sync_calendar_to_drive(ctx: Context): from .testing import mock_access_context __all__ = [ - # Core classes + # === Primary API (Local Definitions) === "AuthProvider", "AccessContext", - - # Application credentials + # === Application Credentials (re-exported from keycardai.mcp.server.auth) === "ApplicationCredential", "ClientSecret", "EKSWorkloadIdentity", "WebIdentity", - - # Client factory + # === Client Factory (Advanced - re-exported from keycardai.mcp.server.auth) === + # Use ClientFactory protocol for custom implementations; DefaultClientFactory for defaults "ClientFactory", "DefaultClientFactory", - - # Auth strategies + # === HTTP Auth Strategies (re-exported from keycardai.oauth.http.auth) === "AuthStrategy", "BasicAuth", "MultiZoneBasicAuth", "NoneAuth", - - # Exceptions - Base + # === Exceptions (re-exported from keycardai.mcp.server.exceptions) === + # Base "MCPServerError", - - # Exceptions - Specific + # Configuration "AuthProviderConfigurationError", + "OAuthClientConfigurationError", + "EKSWorkloadIdentityConfigurationError", + "ClientInitializationError", + # Runtime "AuthProviderInternalError", "AuthProviderRemoteError", - "ClientInitializationError", - "EKSWorkloadIdentityConfigurationError", "EKSWorkloadIdentityRuntimeError", - "JWKSValidationError", - "MissingContextError", - "OAuthClientConfigurationError", - "ResourceAccessError", "TokenExchangeError", + "ResourceAccessError", + "MissingContextError", + # Validation + "JWKSValidationError", "MetadataDiscoveryError", - - # Testing utilities + # === Testing Utilities === "mock_access_context", ] diff --git a/packages/mcp/src/keycardai/mcp/client/__init__.py b/packages/mcp/src/keycardai/mcp/client/__init__.py index d7f66c4..a4c2029 100644 --- a/packages/mcp/src/keycardai/mcp/client/__init__.py +++ b/packages/mcp/src/keycardai/mcp/client/__init__.py @@ -1,3 +1,17 @@ +"""Keycard MCP Client. + +This module provides the MCP client for connecting to MCP servers with OAuth authentication. + +Primary API: + Client: High-level client for MCP operations + ClientManager: Manage multiple client instances + Context: Client context with auth state + +Advanced API (for custom implementations): + Session, SessionStatus, SessionStatusCategory: Low-level session management + AuthCoordinator subclasses: Custom auth coordination +""" + from .auth.coordinators import ( AuthCoordinator, LocalAuthCoordinator, @@ -20,35 +34,36 @@ from .types import AuthChallenge, ToolInfo __all__ = [ - # Core primitives + # === Primary API === "Client", "ClientManager", "Context", - # Storage + # === Storage === "StorageBackend", "InMemoryBackend", "SQLiteBackend", "NamespacedStorage", - # Auth coordination + # === Auth Coordination === "AuthCoordinator", "LocalAuthCoordinator", "StarletteAuthCoordinator", - # Auth strategies + # === Auth Strategies === "AuthStrategy", "OAuthStrategy", "ApiKeyStrategy", "NoAuthStrategy", "create_auth_strategy", - # Types + # === Types === "AuthChallenge", "ToolInfo", - # Exceptions - "MCPClientError", + # === Exceptions === + "MCPClientError", # Base exception for MCP client errors "ClientConfigurationError", - # Logging + # === Logging === "configure_logging", "get_logger", - # Lower-level primitives (advanced usage) + # === Advanced (Low-level Session Management) === + # Use these only when building custom MCP client implementations "Session", "SessionStatus", "SessionStatusCategory", diff --git a/packages/mcp/src/keycardai/mcp/server/auth/__init__.py b/packages/mcp/src/keycardai/mcp/server/auth/__init__.py index 6c7e4c9..3cfe97e 100644 --- a/packages/mcp/src/keycardai/mcp/server/auth/__init__.py +++ b/packages/mcp/src/keycardai/mcp/server/auth/__init__.py @@ -1,3 +1,15 @@ +"""Keycard MCP Server Authentication. + +This module provides authentication providers and token verification for MCP servers. + +Local Definitions: + AuthProvider, AccessContext, TokenVerifier: Core server auth components + ApplicationCredential, ClientSecret, WebIdentity, EKSWorkloadIdentity: Credential providers + +Re-exports (from keycardai.oauth): + AuthStrategy, BasicAuth, BearerAuth, MultiZoneBasicAuth, NoneAuth: HTTP auth strategies +""" + # Re-export auth strategies from keycardai.oauth for convenience from keycardai.oauth import ( AuthStrategy, @@ -27,24 +39,32 @@ from .verifier import TokenVerifier __all__ = [ + # === Core Authentication (Local) === "AuthProvider", "AccessContext", "TokenVerifier", + # === Application Credentials (Local) === "ApplicationCredential", "ClientSecret", "EKSWorkloadIdentity", "WebIdentity", + # === HTTP Auth Strategies (re-exported from keycardai.oauth) === "AuthStrategy", "BasicAuth", "BearerAuth", "MultiZoneBasicAuth", "NoneAuth", + # === Exceptions (re-exported from ..exceptions) === + # Configuration errors "AuthProviderConfigurationError", "EKSWorkloadIdentityConfigurationError", + # Runtime errors "EKSWorkloadIdentityRuntimeError", + "TokenExchangeError", + "ResourceAccessError", + # Context errors - MissingContextError is for FastMCP Context parameter, + # MissingAccessContextError is for Keycard AccessContext parameter "MissingAccessContextError", "MissingContextError", - "ResourceAccessError", - "TokenExchangeError", "MetadataDiscoveryError", ] diff --git a/packages/oauth/src/keycardai/oauth/__init__.py b/packages/oauth/src/keycardai/oauth/__init__.py index 5816032..ffb644e 100644 --- a/packages/oauth/src/keycardai/oauth/__init__.py +++ b/packages/oauth/src/keycardai/oauth/__init__.py @@ -63,18 +63,18 @@ from .utils.bearer import extract_bearer_token, validate_bearer_format __all__ = [ - # Core clients + # === Core Clients === "AsyncClient", "Client", - # Exceptions - "OAuthError", + # === Exceptions === + "OAuthError", # Base exception for all OAuth errors "OAuthHttpError", "OAuthProtocolError", "NetworkError", "ConfigError", "AuthenticationError", "TokenExchangeError", - # Models and types + # === Data Models === "TokenResponse", "ClientRegistrationResponse", "PKCE", @@ -83,7 +83,7 @@ "ClientRegistrationRequest", "TokenExchangeRequest", "AuthorizationServerMetadata", - # Enums + # === OAuth Enums === "GrantType", "ResponseType", "TokenEndpointAuthMethod", @@ -91,13 +91,13 @@ "TokenTypeHint", "PKCECodeChallengeMethod", "WellKnownEndpoint", - # Auth strategies + # === HTTP Auth Strategies === "AuthStrategy", "BasicAuth", "BearerAuth", "NoneAuth", "MultiZoneBasicAuth", - # Utility functions + # === Utility Functions === "extract_bearer_token", "validate_bearer_format", ]