[pull] main from modelcontextprotocol:main

[pull]

See Commits and Changes for more details.

---

Created by pull[bot] (v2.0.0-alpha.1)

Can you help keep this open source service alive? 💖 Please sponsor : )

Summary by Sourcery

Introduce OAuth 2.0 Resource Indicators support (RFC 8707) by adding shared utilities for resource URL handling, integrating resource parameter propagation in auth flows, and enabling optional strict resource validation in the simple-auth example.

New Features:

• Add mcp.shared.auth_utils module with RFC 8707 resource indicator utilities for canonicalizing and validating resource URLs
• Enable optional strict resource validation in token introspection and include resource claims in AccessToken

Enhancements:

• Propagate 'resource' parameter through authorization, token exchange, and refresh processes across client and server implementations

Documentation:

• Update simple-auth example README to document --oauth-strict flag for enabling strict resource validation

Tests:

• Add unit tests for resource_url_from_server_url and check_resource_allowed functions to verify RFC 8707 compliance

[gitnotebooks]

Review these changes at https://app.gitnotebooks.com/Stars1233/python-sdk/pull/85

[sourcery-ai]

Reviewer's Guide

This PR adds OAuth 2.0 Resource Indicators support (RFC 8707) by introducing resource URL normalization and hierarchical matching utilities, extending token introspection and authorization flows to carry and strictly validate a “resource” parameter, updating server settings and CLI flags for strict validation, and covering the new logic with tests.

Sequence diagram for OAuth client authorization flow with resource indicator

sequenceDiagram
    participant ClientApp
    participant OAuthClientProvider
    participant AuthServer
    ClientApp->>OAuthClientProvider: Initiate authorization
    OAuthClientProvider->>AuthServer: /authorize (includes resource)
    AuthServer-->>OAuthClientProvider: Authorization code
    OAuthClientProvider->>AuthServer: /token (includes resource)
    AuthServer-->>OAuthClientProvider: Access token (resource bound)
    OAuthClientProvider-->>ClientApp: Access token

Loading

Sequence diagram for resource server token introspection with strict resource validation

sequenceDiagram
    participant ResourceServer
    participant IntrospectionTokenVerifier
    participant AuthServer
    ResourceServer->>IntrospectionTokenVerifier: verify_token(token)
    IntrospectionTokenVerifier->>AuthServer: /introspect
    AuthServer-->>IntrospectionTokenVerifier: token data (aud = resource)
    IntrospectionTokenVerifier->>IntrospectionTokenVerifier: _validate_resource(token_data)
    alt Resource valid
        IntrospectionTokenVerifier-->>ResourceServer: AccessToken
    else Resource invalid
        IntrospectionTokenVerifier-->>ResourceServer: None (reject)
    end

Loading

Class diagram for updated OAuth token and authorization models (RFC 8707 support)

classDiagram
    class AuthorizationParams {
        +str|None resource
    }
    class AuthorizationCode {
        +str|None resource
    }
    class AccessToken {
        +str|None resource
    }
    class RefreshToken {
        +str|None resource
    }
    class AuthorizationRequest {
        +str|None resource
    }
    class AuthorizationCodeRequest {
        +str|None resource
    }
    class RefreshTokenRequest {
        +str|None resource
    }
    AuthorizationParams <|-- AuthorizationCode
    AuthorizationCode <|-- AccessToken
    AuthorizationRequest <|-- AuthorizationCodeRequest
    AuthorizationCodeRequest <|-- RefreshTokenRequest

Loading

Class diagram for IntrospectionTokenVerifier with RFC 8707 resource validation

classDiagram
    class TokenVerifier {
        <<abstract>>
    }
    class IntrospectionTokenVerifier {
        -str introspection_endpoint
        -str server_url
        -bool validate_resource
        -str resource_url
        +verify_token(token: str) AccessToken|None
        +_validate_resource(token_data: dict) bool
        +_is_valid_resource(resource: str) bool
    }
    TokenVerifier <|-- IntrospectionTokenVerifier

Loading

Class diagram for new auth_utils resource utilities

classDiagram
    class auth_utils {
        +resource_url_from_server_url(url: str|HttpUrl|AnyUrl) str
        +check_resource_allowed(requested_resource: str, configured_resource: str) bool
    }

Loading

File-Level Changes

Change	Details	Files
Implement RFC 8707 resource validation in token introspection	Import resource utilities into the verifier Add server_url, validate_resource flags and compute canonical resource_url Implement _validate_resource and _is_valid_resource logic Include resource claim in returned AccessToken	examples/servers/simple-auth/mcp_simple_auth/token_verifier.py
Add strict resource validation option in server settings and CLI	Add oauth_strict flag to ResourceServerSettings Pass server_url and validate_resource into IntrospectionTokenVerifier Expose --oauth-strict option in CLI and update README	examples/servers/simple-auth/mcp_simple_auth/server.py examples/servers/simple-auth/README.md
Propagate resource indicator through OAuth client flows	Import auth_utils and add get_resource_url helper Include resource parameter in authorize, token exchange, and refresh requests	src/mcp/client/auth.py
Propagate resource indicator in GitHub OAuth provider	Allow None in state_mapping values Include resource in authorize payload and state Extract, assert, and forward resource in callback and exchange	examples/servers/simple-auth/mcp_simple_auth/github_oauth_provider.py
Extend auth server data models to carry resource field	Add resource field to AuthorizationRequest, TokenRequest, RefreshTokenRequest Extend AuthorizationParams, AuthorizationCode, and AccessToken models	src/mcp/server/auth/handlers/authorize.py src/mcp/server/auth/handlers/token.py src/mcp/server/auth/provider.py
Include audience claim in introspection responses	Return aud claim from AccessToken.resource in introspect_handler	examples/servers/simple-auth/mcp_simple_auth/auth_server.py
Introduce auth_utils and tests for resource indicator utilities	Create resource_url_from_server_url and check_resource_allowed functions Add comprehensive tests covering normalization and hierarchical matching	src/mcp/shared/auth_utils.py tests/shared/test_auth_utils.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.