DOCSEARCHbyAlgolia
Submit Docs

FastApps Framework

repository·main·Indexed 42 days ago

https://github.com/sumelabs/fastapps

A zero-boilerplate framework for building interactive ChatGPT widgets using the Model Context Protocol (MCP). It provides a Python backend for tool logic and a React frontend package with hooks like useWidgetProps, useWidgetState, and useOpenAiGlobal to manage state, environment properties, and display modes within the ChatGPT interface.

Tokens
19.8K
Snippets
74
Records
97
Agent score
52%

What's inside FastApps

  1. Define Widget Authentication Levels

    main

    FastApps provides three primary decorators to control how widgets handle authentication and authorization:

    1. Protected Widgets: Use @auth_required(scopes=[...]). These require a valid authentication token and specific OAuth2 scopes. If a user is not authenticated, the tool will prompt for login.
    2. Public Widgets: Use @no_auth. These require no authentication and are accessible to everyone immediately.
    3. Flexible Widgets: Use @optional_auth(scopes=[...]). These allow for 'freemium' logic where the widget behaves differently depending on whether the user is authenticated or anonymous.

    Example usage of decorators:

    @auth_required(scopes=["user", "read:data"])
# ... widget logic

@no_auth
# ... widget logic

@optional_auth(scopes=["user"])
# ... widget logic

  2. Summary of Widget Authentication Decorators

    main

    FastApps uses decorators to define how widgets handle authentication. Use this table to understand the expected behavior for different access levels:

    Widget TypeDecoratorAnonymous AccessAuthenticated Access
    Protected@auth_required❌ Error✅ Works, shows user info
    Public@no_auth✅ Works✅ Works, notes auth status
    Flexible@optional_auth✅ Basic features✅ Premium features

  4. Test your MCP server endpoint

    main

    The MCP server is exposed at the /mcp endpoint of your FastApps server (e.g., https://your-public-url.trycloudflare.com/mcp).

    Option A: Test on MCPJam Inspector

    Use the following command to inspect your server:

    npx @mcpjam/inspector@latest

    Option B: Test on ChatGPT

    Add your public URL + /mcp to ChatGPT's Settings > Connectors.

  5. Initialize a FastApps test project

    main

    Follow these steps to set up a local development environment for testing FastApps with OAuth:

    1. Create a directory and a Python virtual environment.
    2. Install FastApps in editable mode using uv.
    3. Install required dependencies: httpx, PyJWT, and cryptography.
    4. Initialize the project using the fastapps init command.
    5. Install JavaScript dependencies via npm.
    mkdir auth-test && cd auth-test
python3 -m venv venv
source venv/bin/activate

uv pip install -e ../FastApps
uv pip install httpx PyJWT cryptography

uv run fastapps init auth-test-project
cd auth-test-project
npm install

  6. Python Naming Conventions and Style

    main

    Follow these naming and structural guidelines for Python code:

    Naming

    • Classes: PascalCase (e.g., MyWidget)
    • Functions/Methods: snake_case (e.g., process_data)
    • Variables: snake_case
    • Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES)
    • Private members: Prefix with a single underscore (e.g., _internal_method)

    Best Practices

    • Imports: Organize in order: 1. Standard library, 2. Third-party, 3. Local application imports. Ruff handles this via the I rule.
    • Docstrings: Use Google-style docstrings for all public APIs.
    • Type Hints: Use type hints for all function signatures.
    • String Formatting: Prefer f-strings over % or .format().
    • Error Handling: Be specific with exceptions; avoid catching generic Exception unless necessary.
    # Example of correct style
MAX_RETRIES = 3

class MyWidget(Widget):
    def process_data(self, input_data: Dict) -> Dict:
        """Google-style docstring.

        Args:
            input_data: Description of input.

        Returns:
            Description of return.
        """
        _temp_value = self._calculate_internal()
        return {"result": _temp_value}

    def _calculate_internal(self) -> int:
        return 42

  7. Manage FastApps dependencies with uv

    main

    FastApps projects use pyproject.toml and uv.lock for dependency management. Use these commands to manage your environment:

    • uv sync: Installs all dependencies defined in pyproject.toml and updates uv.lock. Run this after pulling changes or editing dependencies.
    • uv add <package>: Adds a new dependency and updates both pyproject.toml and uv.lock immediately.
    • uv run <command>: Executes CLI tools (like fastapps dev) within the synced environment without needing to manually activate a virtualenv.

    Note: If uv is not installed, FastApps commands that manage dependencies (e.g., fastapps init, fastapps use) will fail.

    uv sync
uv add <package>
uv run fastapps dev

  8. Lint Python code with Ruff

    main

    Ruff is used for fast linting and import sorting. It replaces tools like Flake8 and isort.

    Installation:

    uv pip install ruff

    Common Commands:

    • Lint all files: uv run ruff check .
    • Auto-fix linting issues: uv run ruff check --fix .
    • Lint a specific file: uv run ruff check path/to/file.py
    uv run ruff check --fix .

  9. Quick Start: Initialize and run a FastApps project

    main

    To create a new application and start the development server, follow these steps:

    1. Initialize a new app: uv run fastapps init my-app
    2. Navigate to the directory: cd my-app
    3. Sync dependencies: uv sync
    4. Start the development server: uv run fastapps dev

    Running fastapps dev will generate a public URL via a Cloudflare tunnel. This URL is one-time use.

    uv run fastapps init my-app
cd my-app
uv sync
uv run fastapps dev

  10. Set up Auth0 for OAuth testing

    main

    To test per-widget authentication in FastApps, configure an Auth0 tenant with the following settings:

    1. Create an API:
      • Name: FastApps Test API
      • Identifier: A unique URL (e.g., https://fastapps-test.example.com). This becomes your auth_audience.
      • Signing Algorithm: RS256.
    2. Add Permissions (Scopes): In the API's Permissions tab, add user, read:data, write:data, and admin.
    3. Enable RBAC: In API Settings, toggle ON Enable RBAC and Add Permissions in the Access Token.
    4. Enable Dynamic Client Registration: In Dashboard Settings -> API Authorization Settings, toggle ON OIDC Dynamic Application Registration.
    5. Create a Test User: Create a user in User Management and manually assign the API permissions to that user in their Permissions tab.
    Required Configuration Values:
ISSUER_URL: https://YOUR_TENANT.us.auth0.com
RESOURCE_SERVER_URL: https://YOUR_NGROK_URL.ngrok-free.app/mcp
AUDIENCE: https://fastapps-test.example.com

  11. Create new widgets and use templates

    main

    You can generate new widgets using the CLI. You can also use pre-built templates to jumpstart development:

    Basic widget creation:

    uv run fastapps create additional-widget

    Widget templates:

    • list: Vertical list with items
    • carousel: Horizontal scrolling cards
    • albums: Photo gallery viewer

    Example usage:

    uv run fastapps create my-list --template list
uv run fastapps create my-carousel --template carousel
uv run fastapps create my-albums --template albums
    uv run fastapps create my-list --template list

  12. Connect FastApps to ChatGPT via MCP

    main

    To test your FastApps widgets within ChatGPT, you must add your server as a connector using the Model Context Protocol (MCP) path.

    1. Open ChatGPT and navigate to Settings (gear icon).
    2. Select Connectors and click Add Connector.
    3. Enter your ngrok URL appended with the /mcp path (e.g., https://abc123.ngrok-free.app/mcp).
    4. When prompted, click Authenticate to be redirected to Auth0.
    5. Log in with your test user and grant the necessary permissions to complete the handshake.
    https://abc123.ngrok-free.app/mcp