Merge pull request #13 from keycardai/feat/refactor-fastmcp-api

feat(keycardai-mcp-fastmcp): refactor API for the provider

Author: kamil-keycard

packages/mcp-fastmcp/README.md

@@ -10,73 +10,69 @@ pip install keycardai-mcp-fastmcp
 
 ## Quick Start
 
-```python
-from fastmcp import FastMCP, Context
-from keycardai.mcp.integrations.fastmcp import KeycardAuthProvider, OAuthClientMiddleware, get_access_token_for_resource
+Add KeyCard authentication to your existing FastMCP server:
 
-# Create FastMCP server with KeyCard authentication
-mcp = FastMCP("My Secure Service")
+### Install the Package
 
-# Add KeyCard authentication
-auth = KeycardAuthProvider(
-    zone_url="https://abc1234.keycard.cloud",
-    mcp_server_name="My MCP Service"
-)
-mcp.set_auth_provider(auth)
+```bash
+pip install keycardai-mcp-fastmcp
+```
 
-# Add OAuth client middleware for token exchange
-oauth_middleware = OAuthClientMiddleware(
-    zone_url="https://abc1234.keycard.cloud",
-    client_name="My MCP Service"
-)
-mcp.add_middleware(oauth_middleware)
+### Get Your KeyCard Zone ID
 
-# Use decorator for automatic token exchange
-@mcp.tool()
-@get_access_token_for_resource("https://www.googleapis.com/calendar/v3")
-async def get_calendar_events(ctx: Context, maxResults: int = 10) -> dict:
-    # ctx.access_token is automatically available with Google Calendar access
-    access_token = ctx.access_token
-    # Make API calls with the exchanged token...
-    return {"events": [...], "totalEvents": 5}
-```
+1. Sign up at [keycard.ai](https://keycard.ai)
+2. Navigate to Zone Settings to get your zone ID
+3. Configure your preferred identity provider (Google, Microsoft, etc.)
+4. Create an MCP resource in your zone
 
-## 🏗️ Architecture & Features
+### Add Authentication to Your FastMCP Server
 
-This integration package provides FastMCP-specific components for KeyCard OAuth:
+```python
+from fastmcp import FastMCP, Context
+from keycardai.mcp.integrations.fastmcp import AuthProvider
 
-### Core Components
+# Configure KeyCard authentication (recommended: use zone_id)
+auth_provider = AuthProvider(
+    zone_id="your-zone-id",  # Get this from keycard.ai
+    mcp_server_name="My Secure FastMCP Server",
+    mcp_server_url="http://127.0.0.1:8000/"
+)
 
-| Component | Module | Description |
-|-----------|---------|-------------|
-| **KeycardAuthProvider** | `provider.py` | **FastMCP Authentication** - Integrates KeyCard zone tokens with FastMCP auth system |
-| **OAuthClientMiddleware** | `middleware.py` | **Client Lifecycle** - Manages OAuth client initialization and context injection |
-| **Token Exchange Decorators** | `decorators.py` | **Automated Exchange** - Decorators for seamless resource-specific token exchange |
+# Get the RemoteAuthProvider for FastMCP
+auth = auth_provider.get_remote_auth_provider()
 
-### Authentication Flow
+# Create authenticated FastMCP server
+mcp = FastMCP("My Secure FastMCP Server", auth=auth)
 
-1. **Token Verification**: `KeycardAuthProvider` validates incoming JWT tokens using KeyCard zone JWKS
-2. **Client Management**: `OAuthClientMiddleware` provides OAuth client to tools via FastMCP context
-3. **Token Exchange**: `@get_access_token_for_resource()` decorator automates RFC 8693 token exchange
-4. **API Access**: Tools receive resource-specific access tokens transparently
+@mcp.tool()
+def hello_world(name: str) -> str:
+    return f"Hello, {name}!"
 
-## Development
+# Example with token exchange for external API access
+@mcp.tool()
+@auth_provider.grant("https://api.example.com")
+def call_external_api(ctx: Context, query: str) -> str:
+    # Access delegated token through context namespace
+    token = ctx.get_state("keycardai").access("https://api.example.com").access_token
+    # Use token to call external API
+    return f"Results for {query}"
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")
+```
 
-This package is part of the [KeycardAI Python SDK](../../README.md). 
+### 🎉 Your FastMCP server is now protected with KeyCard authentication! 🎉
 
-To develop:
+## Examples
+
+For complete examples and advanced usage patterns, see our [documentation](https://docs.keycard.ai).
 
-```bash
-# From workspace root
-uv sync
-uv run --package keycardai-mcp-fastmcp pytest
-```
 ## License
 
-MIT License - see [LICENSE](../../LICENSE) file for details.
+MIT License - see [LICENSE](https://github.com/keycardai/python-sdk/blob/main/LICENSE) file for details.
 
 ## Support
 
+- 📖 [Documentation](https://docs.keycard.ai)
 - 🐛 [Issue Tracker](https://github.com/keycardai/python-sdk/issues)
-- 💬 [Community Discussions](https://github.com/keycardai/python-sdk/discussions)
 - 📧 [Support Email](mailto:support@keycard.ai)

packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/__init__.py

@@ -1,107 +1,87 @@
 """FastMCP integration for KeyCard OAuth client.
 
 This module provides seamless integration between KeyCard's OAuth client
-and FastMCP servers, following the sync/async API design standard.
+and FastMCP servers, enabling secure authentication and authorization.
 
 Components:
-- KeycardAuthProvider: FastMCP authentication provider using KeyCard zone tokens
-- AccessMiddleware: Middleware that manages OAuth client lifecycle and provides grant decorator
-- Access token management through grant decorators
+- AuthProvider: KeyCard authentication provider with RemoteAuthProvider creation and grant decorator
+- AccessContext: Context object for accessing delegated tokens (used in FastMCP Context namespace)
+- Auth strategies: BasicAuth, MultiZoneBasicAuth, NoneAuth for different authentication scenarios
 
-Example Usage:
+Basic Usage:
 
-    # Basic FastMCP server setup with KeyCard authentication
-    import fastmcp
-    from keycardai.mcp.integrations.fastmcp import (
-        KeycardAuthProvider,
-        AccessMiddleware,
-    )
-
-    # Create MCP server with KeyCard authentication
-    mcp = fastmcp.MCP("My KeyCard Server")
+    from fastmcp import FastMCP, Context
+    from keycardai.mcp.integrations.fastmcp import AuthProvider
 
-    # Add authentication provider
-    auth_provider = KeycardAuthProvider(
-        zone_url="https://my-keycard-zone.com",
-        audience="my-mcp-server"
+    # Create authentication provider
+    auth_provider = AuthProvider(
+        zone_id="abc1234",
+        mcp_server_name="My Server",
+        mcp_server_url="http://localhost:8000"
     )
-    mcp.add_auth_provider(auth_provider)
 
-    # Add access middleware for automatic token management
-    access = AccessMiddleware(
-        zone_url="https://my-keycard-zone.com"
-    )
-    mcp.add_middleware(access)
+    # Get the RemoteAuthProvider for FastMCP
+    auth = auth_provider.get_remote_auth_provider()
+    mcp = FastMCP("My Server", auth=auth)
 
-    # Use the grant decorator for automatic token exchange in tools
-    @mcp.tool()
-    @access.grant("https://api.example.com")
-    async def call_external_api(ctx: Context, query: str) -> str:
-        '''Call an external API on behalf of the authenticated user.
-
-        The decorator automatically exchanges the user's token for one
-        that can access the specified resource.
-        '''
-        # Use the token to call the external API
-        async with httpx.AsyncClient() as client:
-            response = await client.get(
-                "https://api.example.com/search",
-                params={"q": query},
-                headers={"Authorization": create_auth_header(ctx.get_state("keycardai").access("https://api.example.com").access_token)}
-            )
-            return response.json()
-
-    # Simplified setup for common scenarios
+    # Use grant decorator for token exchange
     @mcp.tool()
-    @access.grant("https://www.googleapis.com/calendar/v3")
-    async def get_calendar_events(ctx: Context) -> list:
-        '''Get user's calendar events with automatic token delegation.'''
-        # Calendar API call with delegated token
-        from keycardai.oauth.utils.bearer import create_auth_header
-        token = ctx.get_state("keycardai").access("https://www.googleapis.com/calendar/v3").access_token
-        headers = {"Authorization": create_auth_header(token)}
-        # ... implementation details ...
-        return events
-
-    # Run the server
-    if __name__ == "__main__":
-        mcp.run()
+    @auth_provider.grant("https://api.example.com")
+    def call_external_api(ctx: Context, query: str):
+        token = ctx.get_state("keycardai").access("https://api.example.com").access_token
+        # Use token to call external API
+        return f"Results for {query}"
 
 Advanced Configuration:
 
-    # Custom access middleware configuration
-    access = AccessMiddleware(
-        zone_url="https://my-keycard-zone.com",
-        client_name="My Custom Client"
-    )
+    # With custom authentication (production)
+    from keycardai.mcp.integrations.fastmcp import BasicAuth
 
-    # Custom authentication with specific requirements
-    auth_provider = KeycardAuthProvider(
-        zone_url="https://my-keycard-zone.com",
-        audience="my-specific-audience",
-        mcp_server_name="My Custom Server",
-        resource_server_url="https://my-resource-server.com/"
+    auth_provider = AuthProvider(
+        zone_id="abc1234",
+        mcp_server_name="Production Server",
+        mcp_server_url="https://my-server.com",
+        auth=BasicAuth("client_id", "client_secret")
     )
 
-    # Multiple resource access with single decorator
+    # Multiple resource access
     @mcp.tool()
-    @access.grant(["https://www.googleapis.com/calendar/v3", "https://www.googleapis.com/drive/v3"])
+    @auth_provider.grant(["https://www.googleapis.com/calendar/v3", "https://www.googleapis.com/drive/v3"])
     async def sync_calendar_to_drive(ctx: Context):
-        '''Sync calendar events to Google Drive with multiple token exchanges.'''
-        from keycardai.oauth.utils.bearer import create_auth_header
         calendar_token = ctx.get_state("keycardai").access("https://www.googleapis.com/calendar/v3").access_token
         drive_token = ctx.get_state("keycardai").access("https://www.googleapis.com/drive/v3").access_token
-        calendar_headers = {"Authorization": create_auth_header(calendar_token)}
-        drive_headers = {"Authorization": create_auth_header(drive_token)}
-
         # Use both tokens for cross-service operations
-        # ... implementation ...
+        return "Sync completed"
+
+    # Multi-zone support
+    from keycardai.mcp.integrations.fastmcp import MultiZoneBasicAuth
+
+    auth_provider = AuthProvider(
+        zone_url="https://keycard.cloud",
+        mcp_server_url="https://my-server.com",
+        auth=MultiZoneBasicAuth({
+            "tenant1": ("id1", "secret1"),
+            "tenant2": ("id2", "secret2"),
+        })
+    )
 """
 
-from .middleware import AccessMiddleware
-from .provider import KeycardAuthProvider
+# Re-export commonly used auth strategies for convenience
+from keycardai.oauth.http.auth import (
+    AuthStrategy,
+    BasicAuth,
+    MultiZoneBasicAuth,
+    NoneAuth,
+)
+
+from .provider import AccessContext, AuthProvider
 
 __all__ = [
-    "KeycardAuthProvider",
-    "AccessMiddleware",
+    "AuthProvider",
+    "AccessContext",
+    # Auth strategies
+    "AuthStrategy",
+    "BasicAuth",
+    "MultiZoneBasicAuth",
+    "NoneAuth",
 ]