diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 74e3541da..548696b55 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -39,3 +39,10 @@ repos: - id: no-commit-to-branch name: prevent commits to main args: [--branch, main] + + - repo: https://github.com/codespell-project/codespell + rev: v2.4.1 + hooks: + - id: codespell # See pyproject.toml for args + additional_dependencies: + - tomli diff --git a/docs/changelog.mdx b/docs/changelog.mdx index 00f60cd2c..fabf26c6e 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -4,6 +4,124 @@ icon: "list-check" rss: true --- + + +**[v2.12.4: OIDC What You Did There](https://github.com/jlowin/fastmcp/releases/tag/v2.12.4)** + +FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser. + +## What's Changed +### New Features ๐ŸŽ‰ +* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/jlowin/fastmcp/pull/1817) +### Enhancements ๐Ÿ”ง +* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/jlowin/fastmcp/pull/1812) +* Refactor Logging and Structured Logging Middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/jlowin/fastmcp/pull/1805) +* Update pull_request_template.md by [@jlowin](https://github.com/jlowin) in [#1824](https://github.com/jlowin/fastmcp/pull/1824) +* chore: Set redirect_path default in function by [@ruhulio](https://github.com/ruhulio) in [#1833](https://github.com/jlowin/fastmcp/pull/1833) +* feat: Set instructions in code by [@attiks](https://github.com/attiks) in [#1838](https://github.com/jlowin/fastmcp/pull/1838) +* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/jlowin/fastmcp/pull/1779) +* chore: Cleanup Auth0 redirect_path initialization by [@ruhulio](https://github.com/ruhulio) in [#1842](https://github.com/jlowin/fastmcp/pull/1842) +* feat: Add support for Descope Authentication by [@anvibanga](https://github.com/anvibanga) in [#1853](https://github.com/jlowin/fastmcp/pull/1853) +* Update descope version badges by [@jlowin](https://github.com/jlowin) in [#1870](https://github.com/jlowin/fastmcp/pull/1870) +* Update welcome images by [@jlowin](https://github.com/jlowin) in [#1884](https://github.com/jlowin/fastmcp/pull/1884) +* Fix rounded edges of image by [@jlowin](https://github.com/jlowin) in [#1886](https://github.com/jlowin/fastmcp/pull/1886) +* optimize test suite by [@zzstoatzz](https://github.com/zzstoatzz) in [#1893](https://github.com/jlowin/fastmcp/pull/1893) +* Enhancement: client completions support context_arguments by [@isijoe](https://github.com/isijoe) in [#1906](https://github.com/jlowin/fastmcp/pull/1906) +* Update Descope icon by [@anvibanga](https://github.com/anvibanga) in [#1912](https://github.com/jlowin/fastmcp/pull/1912) +* Add AWS Cognito OAuth Provider for Enterprise Authentication by [@stephaneberle9](https://github.com/stephaneberle9) in [#1873](https://github.com/jlowin/fastmcp/pull/1873) +* Fix typos discovered by codespell by [@cclauss](https://github.com/cclauss) in [#1922](https://github.com/jlowin/fastmcp/pull/1922) +* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/jlowin/fastmcp/pull/1791) +### Fixes ๐Ÿž +* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/jlowin/fastmcp/pull/1821) +* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/jlowin/fastmcp/pull/1823) +* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/jlowin/fastmcp/pull/1820) +* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/jlowin/fastmcp/pull/1828) +* fix: Increase default 3s timeout on Pytest by [@dacamposol](https://github.com/dacamposol) in [#1866](https://github.com/jlowin/fastmcp/pull/1866) +* fix: Improve URL handling in OIDCConfiguration by [@ruhulio](https://github.com/ruhulio) in [#1850](https://github.com/jlowin/fastmcp/pull/1850) +* fix: correct typing for on_read_resource middleware method by [@strawgate](https://github.com/strawgate) in [#1858](https://github.com/jlowin/fastmcp/pull/1858) +* feat(experimental/openapi): replace $ref in additionalProperties; add tests by [@jlowin](https://github.com/jlowin) in [#1735](https://github.com/jlowin/fastmcp/pull/1735) +* Honor client supplied scopes during registration by [@dmikusa](https://github.com/dmikusa) in [#1860](https://github.com/jlowin/fastmcp/pull/1860) +* Fix: FastAPI list parameter parsing in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1834](https://github.com/jlowin/fastmcp/pull/1834) +* Add log level support for stdio and HTTP transports by [@jlowin](https://github.com/jlowin) in [#1840](https://github.com/jlowin/fastmcp/pull/1840) +* Fix OAuth pre-flight check to accept HTTP 200 responses by [@jlowin](https://github.com/jlowin) in [#1874](https://github.com/jlowin/fastmcp/pull/1874) +* Fix: Preserve OpenAPI parameter descriptions in experimental parser by [@shlomo666](https://github.com/shlomo666) in [#1877](https://github.com/jlowin/fastmcp/pull/1877) +* Add persistent storage for OAuth client registrations by [@jlowin](https://github.com/jlowin) in [#1879](https://github.com/jlowin/fastmcp/pull/1879) +* docs: update release dates based on github releases by [@lodu](https://github.com/lodu) in [#1890](https://github.com/jlowin/fastmcp/pull/1890) +* Small updates to Sampling types by [@strawgate](https://github.com/strawgate) in [#1882](https://github.com/jlowin/fastmcp/pull/1882) +* remove lockfile smart_home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#1892](https://github.com/jlowin/fastmcp/pull/1892) +* Fix: Remove JSON schema title metadata while preserving parameters named 'title' by [@jlowin](https://github.com/jlowin) in [#1872](https://github.com/jlowin/fastmcp/pull/1872) +* Fix: get_resource_url nested URL handling by [@raphael-linx](https://github.com/raphael-linx) in [#1914](https://github.com/jlowin/fastmcp/pull/1914) +* Clean up code for creating the resource url by [@jlowin](https://github.com/jlowin) in [#1916](https://github.com/jlowin/fastmcp/pull/1916) +* Fix route count logging in OpenAPI server by [@zzstoatzz](https://github.com/zzstoatzz) in [#1928](https://github.com/jlowin/fastmcp/pull/1928) +### Docs ๐Ÿ“š +* docs: make Gemini CLI integration discoverable by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1827](https://github.com/jlowin/fastmcp/pull/1827) +* docs: update NEW tags for AI assistant integrations by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1829](https://github.com/jlowin/fastmcp/pull/1829) +* Update wordmark by [@jlowin](https://github.com/jlowin) in [#1832](https://github.com/jlowin/fastmcp/pull/1832) +* docs: improve OAuth and OIDC Proxy documentation by [@jlowin](https://github.com/jlowin) in [#1880](https://github.com/jlowin/fastmcp/pull/1880) +* Update readme + welcome docs by [@jlowin](https://github.com/jlowin) in [#1883](https://github.com/jlowin/fastmcp/pull/1883) +* Update dark mode image in README by [@jlowin](https://github.com/jlowin) in [#1885](https://github.com/jlowin/fastmcp/pull/1885) + +## New Contributors +* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/jlowin/fastmcp/pull/1821) +* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/jlowin/fastmcp/pull/1812) +* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/jlowin/fastmcp/pull/1817) +* [@attiks](https://github.com/attiks) made their first contribution in [#1838](https://github.com/jlowin/fastmcp/pull/1838) +* [@anvibanga](https://github.com/anvibanga) made their first contribution in [#1853](https://github.com/jlowin/fastmcp/pull/1853) +* [@shlomo666](https://github.com/shlomo666) made their first contribution in [#1877](https://github.com/jlowin/fastmcp/pull/1877) +* [@lodu](https://github.com/lodu) made their first contribution in [#1890](https://github.com/jlowin/fastmcp/pull/1890) +* [@isijoe](https://github.com/isijoe) made their first contribution in [#1906](https://github.com/jlowin/fastmcp/pull/1906) +* [@raphael-linx](https://github.com/raphael-linx) made their first contribution in [#1914](https://github.com/jlowin/fastmcp/pull/1914) +* [@stephaneberle9](https://github.com/stephaneberle9) made their first contribution in [#1873](https://github.com/jlowin/fastmcp/pull/1873) +* [@cclauss](https://github.com/cclauss) made their first contribution in [#1922](https://github.com/jlowin/fastmcp/pull/1922) + +**Full Changelog**: [v2.12.3...v2.12.4](https://github.com/jlowin/fastmcp/compare/v2.12.3...v2.12.4) + + + + + +**[v2.12.3: Double Time](https://github.com/jlowin/fastmcp/releases/tag/v2.12.3)** + +FastMCP 2.12.3 focuses on performance and developer experience improvements based on community feedback. This release includes optimized auth provider imports that reduce server startup time, enhanced OIDC authentication flows with proper token management, and several reliability fixes for OAuth proxy configurations. The addition of automatic inline snapshot creation significantly improves the testing experience for contributors. + +## What's Changed +### New Features ๐ŸŽ‰ +* feat: Support setting MCP log level via transport configuration by [@jlowin](https://github.com/jlowin) in [#1756](https://github.com/jlowin/fastmcp/pull/1756) +### Enhancements ๐Ÿ”ง +* Add client-side auth support for mcp install cursor command by [@jlowin](https://github.com/jlowin) in [#1747](https://github.com/jlowin/fastmcp/pull/1747) +* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/jlowin/fastmcp/pull/1779) +* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/jlowin/fastmcp/pull/1791) +### Fixes ๐Ÿž +* fix: correct merge mistake during auth0 refactor by [@strawgate](https://github.com/strawgate) in [#1742](https://github.com/jlowin/fastmcp/pull/1742) +* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/jlowin/fastmcp/pull/1823) +* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/jlowin/fastmcp/pull/1820) +* fix: refactor OIDC configuration provider for proper token management by [@strawgate](https://github.com/strawgate) in [#1751](https://github.com/jlowin/fastmcp/pull/1751) +* Fix smart_home example imports by [@strawgate](https://github.com/strawgate) in [#1753](https://github.com/jlowin/fastmcp/pull/1753) +* fix: correct oauth proxy initialization of client by [@strawgate](https://github.com/strawgate) in [#1759](https://github.com/jlowin/fastmcp/pull/1759) +* Fix: return empty string when prompts have no arguments by [@jlowin](https://github.com/jlowin) in [#1766](https://github.com/jlowin/fastmcp/pull/1766) +* Fix async server callbacks by [@strawgate](https://github.com/strawgate) in [#1774](https://github.com/jlowin/fastmcp/pull/1774) +* Fix error when retrieving Completion API errors by [@strawgate](https://github.com/strawgate) in [#1785](https://github.com/jlowin/fastmcp/pull/1785) +* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/jlowin/fastmcp/pull/1828) +### Docs ๐Ÿ“š +* Add migration docs for 2.12 by [@jlowin](https://github.com/jlowin) in [#1745](https://github.com/jlowin/fastmcp/pull/1745) +* Update docs for default sampling implementation to mention OpenAI API Key by [@strawgate](https://github.com/strawgate) in [#1763](https://github.com/jlowin/fastmcp/pull/1763) +* Add tip about sampling prompts and user_context to sampling documentation by [@jlowin](https://github.com/jlowin) in [#1764](https://github.com/jlowin/fastmcp/pull/1764) +* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/jlowin/fastmcp/pull/1821) +### Other Changes ๐Ÿฆพ +* Replace Marvin with Claude Code in CI by [@jlowin](https://github.com/jlowin) in [#1800](https://github.com/jlowin/fastmcp/pull/1800) +* Refactor logging and structured logging middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/jlowin/fastmcp/pull/1805) +* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/jlowin/fastmcp/pull/1812) +* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/jlowin/fastmcp/pull/1817) + +## New Contributors +* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/jlowin/fastmcp/pull/1821) +* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/jlowin/fastmcp/pull/1812) +* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/jlowin/fastmcp/pull/1817) + +**Full Changelog**: [v2.12.2...v2.12.3](https://github.com/jlowin/fastmcp/compare/v2.12.2...v2.12.3) + + + **[v2.12.2: Perchance to Stream](https://github.com/jlowin/fastmcp/releases/tag/v2.12.2)** @@ -1757,7 +1875,7 @@ This release is highlighted by the ability to handle complex JSON objects as MCP ### New Features ๐ŸŽ‰ * Set up multiple os tests by [@jlowin](https://github.com/jlowin) in [#44](https://github.com/jlowin/fastmcp/pull/44) -* Changes to accomodate windows users. by [@justjoehere](https://github.com/justjoehere) in [#42](https://github.com/jlowin/fastmcp/pull/42) +* Changes to accommodate windows users. by [@justjoehere](https://github.com/justjoehere) in [#42](https://github.com/jlowin/fastmcp/pull/42) * Handle complex inputs by [@jurasofish](https://github.com/jurasofish) in [#31](https://github.com/jlowin/fastmcp/pull/31) ### Docs ๐Ÿ“š diff --git a/docs/docs.json b/docs/docs.json index 90aea2efd..758eca70f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -11,9 +11,6 @@ }, "decoration": "windows" }, - "contextual": { - "options": ["copy", "view"] - }, "banner": { "content": "Host your server on [FastMCP Cloud](https://fastmcp.cloud) for free!" }, @@ -22,6 +19,12 @@ "light": "#4cc9f0", "primary": "#2d00f7" }, + "contextual": { + "options": [ + "copy", + "view" + ] + }, "description": "The fast, Pythonic way to build MCP servers and clients.", "favicon": { "dark": "/assets/brand/favicon.svg", @@ -51,8 +54,8 @@ "links": [ { "href": "https://fastmcp.cloud", - "label": "FastMCP Cloud", - "icon": "cloud" + "icon": "cloud", + "label": "FastMCP Cloud" } ], "primary": { @@ -129,7 +132,10 @@ { "group": "Essentials", "icon": "cube", - "pages": ["clients/client", "clients/transports"] + "pages": [ + "clients/client", + "clients/transports" + ] }, { "group": "Core Operations", @@ -155,7 +161,10 @@ { "group": "Authentication", "icon": "user-shield", - "pages": ["clients/auth/oauth", "clients/auth/bearer"] + "pages": [ + "clients/auth/oauth", + "clients/auth/bearer" + ] } ] }, @@ -172,6 +181,7 @@ "integrations/azure", "integrations/descope", "integrations/github", + "integrations/scalekit", "integrations/google", "integrations/workos" ] @@ -237,7 +247,10 @@ "tab": "Documentation" }, { - "pages": ["updates", "changelog"], + "pages": [ + "updates", + "changelog" + ], "tab": "What's New" }, { @@ -321,16 +334,21 @@ "python-sdk/fastmcp-server-auth-__init__", "python-sdk/fastmcp-server-auth-auth", "python-sdk/fastmcp-server-auth-oauth_proxy", + "python-sdk/fastmcp-server-auth-oidc_proxy", { "group": "providers", "pages": [ "python-sdk/fastmcp-server-auth-providers-__init__", + "python-sdk/fastmcp-server-auth-providers-auth0", + "python-sdk/fastmcp-server-auth-providers-aws", "python-sdk/fastmcp-server-auth-providers-azure", "python-sdk/fastmcp-server-auth-providers-bearer", + "python-sdk/fastmcp-server-auth-providers-descope", "python-sdk/fastmcp-server-auth-providers-github", "python-sdk/fastmcp-server-auth-providers-google", "python-sdk/fastmcp-server-auth-providers-in_memory", "python-sdk/fastmcp-server-auth-providers-jwt", + "python-sdk/fastmcp-server-auth-providers-scalekit", "python-sdk/fastmcp-server-auth-providers-workos" ] }, @@ -411,6 +429,7 @@ ] }, "python-sdk/fastmcp-utilities-openapi", + "python-sdk/fastmcp-utilities-storage", "python-sdk/fastmcp-utilities-tests", "python-sdk/fastmcp-utilities-types" ] diff --git a/docs/integrations/chatgpt.mdx b/docs/integrations/chatgpt.mdx index 2b552fe3b..18028c69d 100644 --- a/docs/integrations/chatgpt.mdx +++ b/docs/integrations/chatgpt.mdx @@ -1,159 +1,157 @@ --- title: ChatGPT ๐Ÿค FastMCP sidebarTitle: ChatGPT -description: Connect FastMCP servers to ChatGPT Deep Research +description: Connect FastMCP servers to ChatGPT in Chat and Deep Research modes icon: message-smile - +tag: NEW --- -ChatGPT supports MCP servers through remote HTTP connections, allowing you to extend ChatGPT's capabilities with custom tools and knowledge from your FastMCP servers. - - -MCP integration with ChatGPT is currently limited to **Deep Research** functionality and is not available for general chat. This feature is available for ChatGPT Pro, Team, Enterprise, and Edu users. - +ChatGPT supports MCP servers through remote HTTP connections in two modes: **Chat mode** for interactive conversations and **Deep Research mode** for comprehensive information retrieval. -OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Check out their [simple Deep Research-style MCP server example](https://github.com/openai/sample-deep-research-mcp) for a quick reference similar to the one in this document, or their [more complete Deep Research example](https://github.com/openai/openai-cookbook/tree/main/examples/deep_research_api/how_to_build_a_deep_research_mcp_server) from the OpenAI Cookbook, which includes vector search and more. +**Developer Mode Required for Chat Mode**: To use MCP servers in regular ChatGPT conversations, you must first enable Developer Mode in your ChatGPT settings. This feature is available for ChatGPT Pro, Team, Enterprise, and Edu users. -## Deep Research + +OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Learn more from their [MCP documentation](https://platform.openai.com/docs/mcp) and [Developer Mode guide](https://platform.openai.com/docs/guides/developer-mode). + -ChatGPT's Deep Research feature requires MCP servers to be internet-accessible HTTP endpoints with **exactly two specific tools**: +## Build a Server -- **`search`**: For searching through your resources and returning matching IDs -- **`fetch`**: For retrieving the full content of specific resources by ID +First, let's create a simple FastMCP server: - -If your server doesn't implement both `search` and `fetch` tools with the correct signatures, ChatGPT will show the error: "This MCP server doesn't implement our specification". Both tools are required. - - -### Tool Descriptions Matter - -Since ChatGPT needs to understand how to use your tools effectively, **write detailed tool descriptions**. The description teaches ChatGPT how to form queries, what parameters to use, and what to expect from your data. Poor descriptions lead to poor search results. - -### Create a Server - -A Deep Research-compatible server must implement these two required tools: - -- **`search(query: str)`** - Takes a query of any kind and returns matching record IDs -- **`fetch(id: str)`** - Takes an ID and returns the record - -**Critical**: Write detailed docstrings for both tools. These descriptions teach ChatGPT how to use your tools effectively. Poor descriptions lead to poor search results. - -The `search` tool should take a query (of any kind!) and return IDs. The `fetch` tool should take an ID and return the record. - -Here's a reference server implementation you can adapt (see also [OpenAI's sample server](https://github.com/openai/sample-deep-research-mcp) for comparison): - -```python server.py [expandable] -import json -from pathlib import Path -from dataclasses import dataclass +```python server.py from fastmcp import FastMCP +import random -@dataclass -class Record: - id: str - title: str - text: str - metadata: dict +mcp = FastMCP("Demo Server") -def create_server( - records_path: Path | str, - name: str | None = None, - instructions: str | None = None, -) -> FastMCP: - """Create a FastMCP server that can search and fetch records from a JSON file.""" - records = json.loads(Path(records_path).read_text()) - - RECORDS = [Record(**r) for r in records] - LOOKUP = {r.id: r for r in RECORDS} - - mcp = FastMCP(name=name or "Deep Research MCP", instructions=instructions) - - @mcp.tool() - async def search(query: str): - """ - Simple unranked keyword search across title, text, and metadata. - Searches for any of the query terms in the record content. - Returns a list of matching record IDs for ChatGPT to fetch. - """ - toks = query.lower().split() - ids = [] - for r in RECORDS: - record_txt = " ".join( - [r.title, r.text, " ".join(r.metadata.values())] - ).lower() - if any(t in record_txt for t in toks): - ids.append(r.id) - - return {"ids": ids} - - @mcp.tool() - async def fetch(id: str): - """ - Fetch a record by ID. - Returns the complete record data for ChatGPT to analyze and cite. - """ - if id not in LOOKUP: - raise ValueError(f"Unknown record ID: {id}") - return LOOKUP[id] - - return mcp +@mcp.tool +def roll_dice(sides: int = 6) -> int: + """Roll a dice with the specified number of sides.""" + return random.randint(1, sides) if __name__ == "__main__": - mcp = create_server("path/to/records.json") mcp.run(transport="http", port=8000) ``` -### Deploy the Server +### Deploy Your Server -Your server must be deployed to a public URL in order for ChatGPT to access it. - -For development, you can use tools like `ngrok` to temporarily expose a locally-running server to the internet. We'll do that for this example (you may need to install `ngrok` and create a free account), but you can use any other method to deploy your server. - -Assuming you saved the above code as `server.py`, you can run the following two commands in two separate terminals to deploy your server and expose it to the internet: +Your server must be accessible from the internet. For development, use `ngrok`: -```bash FastMCP server +```bash Terminal 1 python server.py ``` -```bash ngrok +```bash Terminal 2 ngrok http 8000 ``` - -This exposes your unauthenticated server to the internet. Only run this command in a safe environment if you understand the risks. - +Note your public URL (e.g., `https://abc123.ngrok.io`) for the next steps. -### Connect to ChatGPT +## Chat Mode -Replace `https://your-server-url.com` with the actual URL of your server (such as your ngrok URL). +Chat mode lets you use MCP tools directly in ChatGPT conversations. See [OpenAI's Developer Mode guide](https://platform.openai.com/docs/guides/developer-mode) for the latest requirements. + +### Add to ChatGPT + +#### 1. Enable Developer Mode 1. Open ChatGPT and go to **Settings** โ†’ **Connectors** -2. Click **Add custom connector** -3. Enter your server details: - - **Name**: Library Catalog - - **URL**: Your server URL, including the path. - - **Note**: Ensure your URL includes the correct path for the transport youโ€™re using. The defaults are /sse/ for SSE (e.g., https://abc123.ngrok.io/sse/) and /mcp/ for HTTP (e.g., https://abc123.ngrok.io/mcp/). - - **Description**: A library catalog for searching and retrieving books +2. Under **Advanced**, toggle **Developer Mode** to enabled -#### Test the Connection +#### 2. Create Connector -1. Start a new chat in ChatGPT -2. Click **Tools** โ†’ **Run deep research** -3. Select your **Library Catalog** connector as a source -4. Ask questions like: - - "Search for Python programming books" - - "Find books about AI and machine learning" - - "Show me books by the Python Software Foundation" +1. In **Settings** โ†’ **Connectors**, click **Create** +2. Enter: + - **Name**: Your server name + - **Server URL**: `https://your-server.ngrok.io/mcp/` +3. Check **I trust this provider** +4. Add authentication if needed +5. Click **Create** -ChatGPT will use your server's search and fetch tools to find relevant information and cite the sources in its response. + +**Without Developer Mode**: If you don't have search/fetch tools, ChatGPT will reject the server. With Developer Mode enabled, you don't need search/fetch tools for Chat mode. + -### Troubleshooting +#### 3. Use in Chat -#### "This MCP server doesn't implement our specification" +1. Start a new chat +2. Click the **+** button โ†’ **More** โ†’ **Developer Mode** +3. **Enable your MCP server connector** (required - the connector must be explicitly added to each chat) +4. Now you can use your tools: +Example usage: +- "Roll a 20-sided dice" +- "Roll dice" (uses default 6 sides) + + +The connector must be explicitly enabled in each chat session through Developer Mode. Once added, it remains active for the entire conversation. + + +### Skip Confirmations + +Use `annotations={"readOnlyHint": True}` to skip confirmation prompts for read-only tools: + +```python +@mcp.tool(annotations={"readOnlyHint": True}) +def get_status() -> str: + """Check system status.""" + return "All systems operational" + +@mcp.tool() # No annotation - ChatGPT may ask for confirmation +def delete_item(id: str) -> str: + """Delete an item.""" + return f"Deleted {id}" +``` + +## Deep Research Mode + +Deep Research mode provides systematic information retrieval with citations. See [OpenAI's MCP documentation](https://platform.openai.com/docs/mcp) for the latest Deep Research specifications. + + +**Search and Fetch Required**: Without Developer Mode, ChatGPT will reject any server that doesn't have both `search` and `fetch` tools. Even in Developer Mode, Deep Research only uses these two tools. + + +### Tool Implementation + +Deep Research tools must follow this pattern: + +```python +@mcp.tool() +def search(query: str) -> dict: + """ + Search for records matching the query. + Must return {"ids": [list of string IDs]} + """ + # Your search logic + matching_ids = ["id1", "id2", "id3"] + return {"ids": matching_ids} + +@mcp.tool() +def fetch(id: str) -> dict: + """ + Fetch a complete record by ID. + Return the full record data for ChatGPT to analyze. + """ + # Your fetch logic + return { + "id": id, + "title": "Record Title", + "content": "Full record content...", + "metadata": {"author": "Jane Doe", "date": "2024"} + } +``` + +### Using Deep Research + +1. Ensure your server is added to ChatGPT's connectors (same as Chat mode) +2. Start a new chat +3. Click **+** โ†’ **Deep Research** +4. Select your MCP server as a source +5. Ask research questions + +ChatGPT will use your `search` and `fetch` tools to find and cite relevant information. -If you get this error, it most likely means that your server doesn't implement the required tools (`search` and `fetch`). To correct it, ensure that your server meets the service requirements. \ No newline at end of file diff --git a/docs/integrations/fastapi.mdx b/docs/integrations/fastapi.mdx index 77e6427b6..53bd9be9c 100644 --- a/docs/integrations/fastapi.mdx +++ b/docs/integrations/fastapi.mdx @@ -341,7 +341,7 @@ app.mount("/analytics", mcp_app) ## Offering an LLM-Friendly API -A common pattern is to generate an MCP server from your FastAPI app and mount it back into the same application. This provides an LLM-optimized interface alongside your regular API: +A common pattern is to generate an MCP server from your FastAPI app and serve both interfaces from the same application. This provides an LLM-optimized interface alongside your regular API: ```python # Assumes the FastAPI app from above is already defined @@ -354,13 +354,19 @@ mcp = FastMCP.from_fastapi(app=app, name="E-commerce MCP") # 2. Create the MCP's ASGI app mcp_app = mcp.http_app(path='/mcp') -# 3. Mount it back into your FastAPI app -app = FastAPI(title="E-commerce API", lifespan=mcp_app.lifespan) -app.mount("/llm", mcp_app) +# 3. Create a new FastAPI app that combines both sets of routes +combined_app = FastAPI( + title="E-commerce API with MCP", + routes=[ + *mcp_app.routes, # MCP routes + *app.routes, # Original API routes + ], + lifespan=mcp_app.lifespan, +) # Now you have: # - Regular API: http://localhost:8000/products -# - LLM-friendly MCP: http://localhost:8000/llm/mcp/ +# - LLM-friendly MCP: http://localhost:8000/mcp/ # Both served from the same FastAPI application! ``` diff --git a/docs/integrations/scalekit.mdx b/docs/integrations/scalekit.mdx new file mode 100644 index 000000000..89de64ef1 --- /dev/null +++ b/docs/integrations/scalekit.mdx @@ -0,0 +1,187 @@ +--- +title: Scalekit ๐Ÿค FastMCP +sidebarTitle: Scalekit +description: Secure your FastMCP server with Scalekit +icon: shield-check +tag: NEW +--- + +import { VersionBadge } from "/snippets/version-badge.mdx" + + + + +Install auth stack to your FastMCP server with [Scalekit](https://scalekit.com) using the [Remote OAuth](/servers/auth/remote-oauth) pattern: Scalekit handles user authentication, and the MCP server validates issued tokens. + +## Configuration + +### Prerequisites + +Before you begin + +1. Get a [Scalekit account](https://app.scalekit.com/) and grab API credentials such as **Client ID**, **Client Secret** and **Environment URL** from _Dashboard > Developers > Settings_. +2. Have your FastMCP server's endpoint ready (can be localhost for development, e.g., `http://localhost:8000/mcp`) + +### Step 1: Configure MCP server in Scalekit environment + + + + +In your Scalekit dashboard: + 1. Open the **MCP Servers** section, then select **Create new server** + 2. Enter server details: a name, a resource identifier, and the desired MCP client authentication settings + 3. Save, then copy the **Resource ID** (for example, res_92015146095) + +In your FastMCP project's `.env`: + +```sh +SCALEKIT_ENVIRONMENT_URL= +SCALEKIT_CLIENT_ID= # skc_7008EXAMPLE46 +SCALEKIT_RESOURCE_ID= # res_926EXAMPLE5878 +MCP_URL=http://localhost:8000/mcp +``` + + + + +### Step 2: Add auth to FastMCP server + +Create your FastMCP server file and use the ScalekitProvider to handle all the OAuth integration automatically: + +```python server.py +from fastmcp import FastMCP +from fastmcp.server.auth.providers.scalekit import ScalekitProvider + +# Discovers Scalekit endpoints and set up JWT token validation +auth_provider = ScalekitProvider( + environment_url=SCALEKIT_ENVIRONMENT_URL, # Scalekit environment URL + client_id=SCALEKIT_CLIENT_ID, # OAuth client ID + resource_id=SCALEKIT_RESOURCE_ID, # Resource server ID + mcp_url=SERVER_URL, # Is also aud claim +) + +# Create FastMCP server with auth +mcp = FastMCP(name="My Scalekit Protected Server", auth=auth_provider) + +@mcp.tool +def auth_status() -> dict: + """Show Scalekit authentication status.""" + # Extract user claims from the JWT + return { + "message": "This tool requires authentication via Scalekit", + "authenticated": True, + "provider": "Scalekit" + } + +``` + +## Testing + +### Start the MCP server + +```sh +uv run python server.py +``` + +Use any MCP client (for example, mcp-inspector, Claude, VS Code, or Windsurf) to connect to the running serve. Verify that authentication succeeds and requests are authorized as expected. + +### Provider selection + +Setting this environment variable allows the Scalekit provider to be used automatically without explicitly instantiating it in code. + + + +Set to `fastmcp.server.auth.providers.scalekit.ScalekitProvider` to use Scalekit authentication. + + + +### Scalekit-specific configuration + +These environment variables provide default values for the Scalekit provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`. + + + +Your Scalekit environment URL from the Admin Portal (e.g., `https://your-env.scalekit.com`) + + + +Your Scalekit OAuth application client ID from the Applications section + + + +Your Scalekit resource server ID from the Resources section + + + +Public URL of your FastMCP server (e.g., `https://your-server.com` or `http://localhost:8000/mcp` for development) + + + +Example `.env`: + +```bash +# Use the Scalekit provider +FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.scalekit.ScalekitProvider + +# Scalekit configuration +FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_ENVIRONMENT_URL=https://your-env.scalekit.com +FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_CLIENT_ID=skc_123 +FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_RESOURCE_ID=res_456 +FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_MCP_URL=https://your-server.com/mcp +``` + +With environment variables set, your server code simplifies to: + +```python server.py +from fastmcp import FastMCP + +# Authentication is automatically configured from environment +mcp = FastMCP(name="My Scalekit Protected Server") + +@mcp.tool +def protected_action() -> str: + """A tool that requires authentication.""" + return "Access granted via Scalekit!" +``` + +## Capabilities + +Scalekit supports OAuth 2.1 with Dynamic Client Registration for MCP clients and enterprise SSO, and provides builtโ€‘in JWT validation and security controls. + +**OAuth 2.1/DCR**: clients selfโ€‘register, use PKCE, and work with the Remote OAuth pattern without preโ€‘provisioned credentials. + +**Validation and SSO**: tokens are verified (keys, RS256, issuer, audience, expiry), and SAML, OIDC, OAuth 2.0, ADFS, Azure AD, and Google Workspace are supported; use HTTPS in production and review auth logs as needed. + +## Debugging + +Enable detailed logging to troubleshoot authentication issues: + +```python +import logging +logging.basicConfig(level=logging.DEBUG) +``` + +### Token inspection + +You can inspect JWT tokens in your tools to understand the user context: + +```python +from fastmcp.server.context import request_ctx +import jwt + +@mcp.tool +def inspect_token() -> dict: + """Inspect the current JWT token claims.""" + context = request_ctx.get() + + # Extract token from Authorization header + if hasattr(context, 'request') and hasattr(context.request, 'headers'): + auth_header = context.request.headers.get('authorization', '') + if auth_header.startswith('Bearer '): + token = auth_header[7:] + # Decode without verification (already verified by provider) + claims = jwt.decode(token, options={"verify_signature": False}) + return claims + + return {"error": "No token found"} +``` diff --git a/docs/python-sdk/fastmcp-cli-cli.mdx b/docs/python-sdk/fastmcp-cli-cli.mdx index 2e482fc7c..a6f4ee13b 100644 --- a/docs/python-sdk/fastmcp-cli-cli.mdx +++ b/docs/python-sdk/fastmcp-cli-cli.mdx @@ -74,7 +74,7 @@ fastmcp run server.py -- --config config.json --debug - `server_spec`: Python file, object specification (file\:obj), config file, URL, or None to auto-detect -### `inspect` +### `inspect` ```python inspect(server_spec: str | None = None) -> None @@ -105,7 +105,7 @@ fastmcp inspect # auto-detect fastmcp.json - `server_spec`: Python file to inspect, optionally with \:object suffix, or fastmcp.json -### `prepare` +### `prepare` ```python prepare(config_path: Annotated[str | None, cyclopts.Parameter(help='Path to fastmcp.json configuration file')] = None, output_dir: Annotated[str | None, cyclopts.Parameter(help='Directory to create the persistent environment in')] = None, skip_source: Annotated[bool, cyclopts.Parameter(help='Skip source preparation (e.g., git clone)')] = False) -> None diff --git a/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx b/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx index 1e2a647dd..7cbf60153 100644 --- a/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx +++ b/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx @@ -54,7 +54,7 @@ Install FastMCP server in Gemini CLI. - True if installation was successful, False otherwise -### `gemini_cli_command` +### `gemini_cli_command` ```python gemini_cli_command(server_spec: str) -> None diff --git a/docs/python-sdk/fastmcp-client-auth-oauth.mdx b/docs/python-sdk/fastmcp-client-auth-oauth.mdx index a5781a6aa..cc3dd7cf5 100644 --- a/docs/python-sdk/fastmcp-client-auth-oauth.mdx +++ b/docs/python-sdk/fastmcp-client-auth-oauth.mdx @@ -13,7 +13,7 @@ sidebarTitle: oauth default_cache_dir() -> Path ``` -### `check_if_auth_required` +### `check_if_auth_required` ```python check_if_auth_required(mcp_url: str, httpx_kwargs: dict[str, Any] | None = None) -> bool @@ -47,11 +47,12 @@ File-based token storage implementation for OAuth credentials and tokens. Implements the mcp.client.auth.TokenStorage protocol. Each instance is tied to a specific server URL for proper token isolation. +Uses JSONFileStorage internally for consistent file handling. **Methods:** -#### `get_base_url` +#### `get_base_url` ```python get_base_url(url: str) -> str @@ -60,16 +61,7 @@ get_base_url(url: str) -> str Extract the base URL (scheme + host) from a URL. -#### `get_cache_key` - -```python -get_cache_key(self) -> str -``` - -Generate a safe filesystem key from the server's base URL. - - -#### `get_tokens` +#### `get_tokens` ```python get_tokens(self) -> OAuthToken | None @@ -78,7 +70,7 @@ get_tokens(self) -> OAuthToken | None Load tokens from file storage. -#### `set_tokens` +#### `set_tokens` ```python set_tokens(self, tokens: OAuthToken) -> None @@ -87,7 +79,7 @@ set_tokens(self, tokens: OAuthToken) -> None Save tokens to file storage. -#### `get_client_info` +#### `get_client_info` ```python get_client_info(self) -> OAuthClientInformationFull | None @@ -96,7 +88,7 @@ get_client_info(self) -> OAuthClientInformationFull | None Load client information from file storage. -#### `set_client_info` +#### `set_client_info` ```python set_client_info(self, client_info: OAuthClientInformationFull) -> None @@ -105,7 +97,7 @@ set_client_info(self, client_info: OAuthClientInformationFull) -> None Save client information to file storage. -#### `clear` +#### `clear` ```python clear(self) -> None @@ -113,8 +105,11 @@ clear(self) -> None Clear all cached data for this server. +Note: This is a synchronous method for backward compatibility. +Uses direct file operations instead of async storage methods. -#### `clear_all` + +#### `clear_all` ```python clear_all(cls, cache_dir: Path | None = None) -> None @@ -123,7 +118,7 @@ clear_all(cls, cache_dir: Path | None = None) -> None Clear all cached data for all servers. -### `OAuth` +### `OAuth` OAuth client provider for MCP servers with browser-based authentication. @@ -134,7 +129,7 @@ a browser for user authorization and running a local callback server. **Methods:** -#### `redirect_handler` +#### `redirect_handler` ```python redirect_handler(self, authorization_url: str) -> None @@ -143,7 +138,7 @@ redirect_handler(self, authorization_url: str) -> None Open browser for authorization, with pre-flight check for invalid client. -#### `callback_handler` +#### `callback_handler` ```python callback_handler(self) -> tuple[str, str | None] @@ -152,7 +147,7 @@ callback_handler(self) -> tuple[str, str | None] Handle OAuth callback and return (auth_code, state). -#### `async_auth_flow` +#### `async_auth_flow` ```python async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response] diff --git a/docs/python-sdk/fastmcp-client-client.mdx b/docs/python-sdk/fastmcp-client-client.mdx index 87d8223d3..e089c8201 100644 --- a/docs/python-sdk/fastmcp-client-client.mdx +++ b/docs/python-sdk/fastmcp-client-client.mdx @@ -382,7 +382,8 @@ Send a completion request and return the complete MCP protocol result. **Args:** - `ref`: The reference to complete. - `argument`: Arguments to pass to the completion request. -- `context_arguments`: Optional context arguments to include with the completion request. Defaults to None. +- `context_arguments`: Optional context arguments to +include with the completion request. Defaults to None. **Returns:** - mcp.types.CompleteResult: The complete response object from the protocol, @@ -403,7 +404,8 @@ Send a completion request to the server. **Args:** - `ref`: The reference to complete. - `argument`: Arguments to pass to the completion request. -- `context_arguments`: Optional context arguments to include with the completion request. Defaults to None. +- `context_arguments`: Optional context arguments to +include with the completion request. Defaults to None. **Returns:** - mcp.types.Completion: The completion object. @@ -412,7 +414,7 @@ Send a completion request to the server. - `RuntimeError`: If called while the client is not connected. -#### `list_tools_mcp` +#### `list_tools_mcp` ```python list_tools_mcp(self) -> mcp.types.ListToolsResult @@ -428,7 +430,7 @@ containing the list of tools and any additional metadata. - `RuntimeError`: If called while the client is not connected. -#### `list_tools` +#### `list_tools` ```python list_tools(self) -> list[mcp.types.Tool] @@ -443,7 +445,7 @@ Retrieve a list of tools available on the server. - `RuntimeError`: If called while the client is not connected. -#### `call_tool_mcp` +#### `call_tool_mcp` ```python call_tool_mcp(self, name: str, arguments: dict[str, Any], progress_handler: ProgressHandler | None = None, timeout: datetime.timedelta | float | int | None = None) -> mcp.types.CallToolResult @@ -468,7 +470,7 @@ containing the tool result and any additional metadata. - `RuntimeError`: If called while the client is not connected. -#### `call_tool` +#### `call_tool` ```python call_tool(self, name: str, arguments: dict[str, Any] | None = None, timeout: datetime.timedelta | float | int | None = None, progress_handler: ProgressHandler | None = None, raise_on_error: bool = True) -> CallToolResult @@ -498,10 +500,10 @@ raw result object. - `RuntimeError`: If called while the client is not connected. -#### `generate_name` +#### `generate_name` ```python generate_name(cls, name: str | None = None) -> str ``` -### `CallToolResult` +### `CallToolResult` diff --git a/docs/python-sdk/fastmcp-server-auth-auth.mdx b/docs/python-sdk/fastmcp-server-auth-auth.mdx index 72525e8b3..d95e116d2 100644 --- a/docs/python-sdk/fastmcp-server-auth-auth.mdx +++ b/docs/python-sdk/fastmcp-server-auth-auth.mdx @@ -7,13 +7,13 @@ sidebarTitle: auth ## Classes -### `AccessToken` +### `AccessToken` AccessToken that includes all JWT claims. -### `AuthProvider` +### `AuthProvider` Base class for all FastMCP authentication providers. @@ -26,7 +26,7 @@ custom authentication routes. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -43,7 +43,7 @@ All auth providers must implement token verification. - AccessToken object if valid, None if invalid or expired -#### `get_routes` +#### `get_routes` ```python get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] @@ -65,7 +65,7 @@ Each provider is responsible for creating whatever routes it needs: - List of routes for this provider, including protected MCP endpoints if provided -#### `get_middleware` +#### `get_middleware` ```python get_middleware(self) -> list diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx index 4117f6afb..df2a262ba 100644 --- a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx +++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx @@ -26,7 +26,7 @@ production use with enterprise identity providers. ## Classes -### `ProxyDCRClient` +### `ProxyDCRClient` Client for DCR proxy with configurable redirect URI validation. @@ -56,7 +56,7 @@ arise from accepting arbitrary redirect URIs. **Methods:** -#### `validate_redirect_uri` +#### `validate_redirect_uri` ```python validate_redirect_uri(self, redirect_uri: AnyUrl | None) -> AnyUrl @@ -70,7 +70,7 @@ This is essential for cached token scenarios where the client may reconnect with a different port. -### `OAuthProxy` +### `OAuthProxy` OAuth provider that presents a DCR-compliant interface while proxying to non-DCR IDPs. @@ -181,7 +181,7 @@ Handles provider-specific requirements: **Methods:** -#### `get_client` +#### `get_client` ```python get_client(self, client_id: str) -> OAuthClientInformationFull | None @@ -193,7 +193,7 @@ provided to the DCR client during registration, not the upstream client ID. For unregistered clients, returns None (which will raise an error in the SDK). -#### `register_client` +#### `register_client` ```python register_client(self, client_info: OAuthClientInformationFull) -> None @@ -207,7 +207,7 @@ redirect URI will likely be localhost or unknown to the proxied IDP. The proxied IDP only knows about this server's fixed redirect URI. -#### `authorize` +#### `authorize` ```python authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str @@ -222,7 +222,7 @@ This implements the DCR-compliant proxy pattern: 4. Redirect to IdP with our fixed callback URL and proxy's PKCE -#### `load_authorization_code` +#### `load_authorization_code` ```python load_authorization_code(self, client: OAuthClientInformationFull, authorization_code: str) -> AuthorizationCode | None @@ -234,7 +234,7 @@ Look up our client code and return authorization code object with PKCE challenge for validation. -#### `exchange_authorization_code` +#### `exchange_authorization_code` ```python exchange_authorization_code(self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode) -> OAuthToken @@ -246,7 +246,7 @@ For the DCR-compliant proxy flow, we return the IdP tokens that were obtained during the IdP callback exchange. PKCE validation is handled by the MCP framework. -#### `load_refresh_token` +#### `load_refresh_token` ```python load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshToken | None @@ -255,7 +255,7 @@ load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) Load refresh token from local storage. -#### `exchange_refresh_token` +#### `exchange_refresh_token` ```python exchange_refresh_token(self, client: OAuthClientInformationFull, refresh_token: RefreshToken, scopes: list[str]) -> OAuthToken @@ -264,7 +264,7 @@ exchange_refresh_token(self, client: OAuthClientInformationFull, refresh_token: Exchange refresh token for new access token using authlib. -#### `load_access_token` +#### `load_access_token` ```python load_access_token(self, token: str) -> AccessToken | None @@ -276,7 +276,7 @@ Delegates to the JWT verifier which handles signature validation, expiration checking, and claims validation using the upstream JWKS. -#### `revoke_token` +#### `revoke_token` ```python revoke_token(self, token: AccessToken | RefreshToken) -> None @@ -288,7 +288,7 @@ Removes tokens from local storage and attempts to revoke them with the upstream server if a revocation endpoint is configured. -#### `get_routes` +#### `get_routes` ```python get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] diff --git a/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx new file mode 100644 index 000000000..f20b2dcdf --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx @@ -0,0 +1,82 @@ +--- +title: oidc_proxy +sidebarTitle: oidc_proxy +--- + +# `fastmcp.server.auth.oidc_proxy` + + +OIDC Proxy Provider for FastMCP. + +This provider acts as a transparent proxy to an upstream OIDC compliant Authorization +Server. It leverages the OAuthProxy class to handle Dynamic Client Registration and +forwarding of all OAuth flows. + +This implementation is based on: + OpenID Connect Discovery 1.0 - https://openid.net/specs/openid-connect-discovery-1_0.html + OAuth 2.0 Authorization Server Metadata - https://datatracker.ietf.org/doc/html/rfc8414 + + +## Classes + +### `OIDCConfiguration` + + +OIDC Configuration. + + +**Methods:** + +#### `get_oidc_configuration` + +```python +get_oidc_configuration(cls, config_url: AnyHttpUrl) -> Self +``` + +Get the OIDC configuration for the specified config URL. + +**Args:** +- `config_url`: The OIDC config URL +- `strict`: The strict flag for the configuration +- `timeout_seconds`: HTTP request timeout in seconds + + +### `OIDCProxy` + + +OAuth provider that wraps OAuthProxy to provide configuration via an OIDC configuration URL. + +This provider makes it easier to add OAuth protection for any upstream provider +that is OIDC compliant. + + +**Methods:** + +#### `get_oidc_configuration` + +```python +get_oidc_configuration(self, config_url: AnyHttpUrl, strict: bool | None, timeout_seconds: int | None) -> OIDCConfiguration +``` + +Gets the OIDC configuration for the specified configuration URL. + +**Args:** +- `config_url`: The OIDC configuration URL +- `strict`: The strict flag for the configuration +- `timeout_seconds`: HTTP request timeout in seconds + + +#### `get_token_verifier` + +```python +get_token_verifier(self) -> TokenVerifier +``` + +Creates the token verifier for the specified OIDC configuration and arguments. + +**Args:** +- `algorithm`: Optional token verifier algorithm +- `audience`: Optional token verifier audience +- `required_scopes`: Optional token verifier required_scopes +- `timeout_seconds`: HTTP request timeout in seconds + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx new file mode 100644 index 000000000..344f29b64 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx @@ -0,0 +1,47 @@ +--- +title: auth0 +sidebarTitle: auth0 +--- + +# `fastmcp.server.auth.providers.auth0` + + +Auth0 OAuth provider for FastMCP. + +This module provides a complete Auth0 integration that's ready to use with +just the configuration URL, client ID, client secret, audience, and base URL. + +Example: + ```python + from fastmcp import FastMCP + from fastmcp.server.auth.providers.auth0 import Auth0Provider + + # Simple Auth0 OAuth protection + auth = Auth0Provider( + config_url="https://auth0.config.url", + client_id="your-auth0-client-id", + client_secret="your-auth0-client-secret", + audience="your-auth0-api-audience", + base_url="http://localhost:8000", + ) + + mcp = FastMCP("My Protected Server", auth=auth) + ``` + + +## Classes + +### `Auth0ProviderSettings` + + +Settings for Auth0 OIDC provider. + + +### `Auth0Provider` + + +An Auth0 provider implementation for FastMCP. + +This provider is a complete Auth0 integration that's ready to use with +just the configuration URL, client ID, client secret, audience, and base URL. + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx new file mode 100644 index 000000000..290951a5a --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx @@ -0,0 +1,88 @@ +--- +title: aws +sidebarTitle: aws +--- + +# `fastmcp.server.auth.providers.aws` + + +AWS Cognito OAuth provider for FastMCP. + +This module provides a complete AWS Cognito OAuth integration that's ready to use +with a user pool ID, domain prefix, client ID and client secret. It handles all +the complexity of AWS Cognito's OAuth flow, token validation, and user management. + +Example: + ```python + from fastmcp import FastMCP + from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider + + # Simple AWS Cognito OAuth protection + auth = AWSCognitoProvider( + user_pool_id="your-user-pool-id", + aws_region="eu-central-1", + client_id="your-cognito-client-id", + client_secret="your-cognito-client-secret" + ) + + mcp = FastMCP("My Protected Server", auth=auth) + ``` + + +## Classes + +### `AWSCognitoProviderSettings` + + +Settings for AWS Cognito OAuth provider. + + +### `AWSCognitoTokenVerifier` + + +Token verifier that filters claims to Cognito-specific subset. + + +**Methods:** + +#### `verify_token` + +```python +verify_token(self, token: str) -> AccessToken | None +``` + +Verify token and filter claims to Cognito-specific subset. + + +### `AWSCognitoProvider` + + +Complete AWS Cognito OAuth provider for FastMCP. + +This provider makes it trivial to add AWS Cognito OAuth protection to any +FastMCP server using OIDC Discovery. Just provide your Cognito User Pool details, +client credentials, and a base URL, and you're ready to go. + +Features: +- Automatic OIDC Discovery from AWS Cognito User Pool +- Automatic JWT token validation via Cognito's public keys +- Cognito-specific claim filtering (sub, username, cognito:groups) +- Support for Cognito User Pools + + +**Methods:** + +#### `get_token_verifier` + +```python +get_token_verifier(self) -> TokenVerifier +``` + +Creates a Cognito-specific token verifier with claim filtering. + +**Args:** +- `algorithm`: Optional token verifier algorithm +- `audience`: Optional token verifier audience +- `required_scopes`: Optional token verifier required_scopes +- `timeout_seconds`: HTTP request timeout in seconds + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx index d1fb83d83..463e5f731 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx @@ -14,13 +14,13 @@ using the OAuth Proxy pattern for non-DCR OAuth flows. ## Classes -### `AzureProviderSettings` +### `AzureProviderSettings` Settings for Azure OAuth provider. -### `AzureTokenVerifier` +### `AzureTokenVerifier` Token verifier for Azure OAuth tokens. @@ -31,7 +31,7 @@ to get user information and validate the token. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -40,7 +40,7 @@ verify_token(self, token: str) -> AccessToken | None Verify Azure OAuth token by calling Microsoft Graph API. -### `AzureProvider` +### `AzureProvider` Azure (Microsoft Entra) OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx new file mode 100644 index 000000000..2064a25b1 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx @@ -0,0 +1,62 @@ +--- +title: descope +sidebarTitle: descope +--- + +# `fastmcp.server.auth.providers.descope` + + +Descope authentication provider for FastMCP. + +This module provides DescopeProvider - a complete authentication solution that integrates +with Descope's OAuth 2.1 and OpenID Connect services, supporting Dynamic Client Registration (DCR) +for seamless MCP client authentication. + + +## Classes + +### `DescopeProviderSettings` + +### `DescopeProvider` + + +Descope metadata provider for DCR (Dynamic Client Registration). + +This provider implements Descope integration using metadata forwarding. +This is the recommended approach for Descope DCR +as it allows Descope to handle the OAuth flow directly while FastMCP acts +as a resource server. + +IMPORTANT SETUP REQUIREMENTS: + +1. Enable Dynamic Client Registration in Descope Console: + - Go to the [Inbound Apps page](https://app.descope.com/apps/inbound) of the Descope Console + - Click **DCR Settings** + - Enable **Dynamic Client Registration (DCR)** + - Define allowed scopes + +2. Note your Project ID: + - Save your Project ID from [Project Settings](https://app.descope.com/settings/project) + - Example: P2abc...123 + +For detailed setup instructions, see: +https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr + + +**Methods:** + +#### `get_routes` + +```python +get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +``` + +Get OAuth routes including Descope authorization server metadata forwarding. + +This returns the standard protected resource routes plus an authorization server +metadata endpoint that forwards Descope's OAuth metadata to clients. + +**Args:** +- `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") +- `mcp_endpoint`: The MCP endpoint handler to protect with auth + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx index 39ad189b0..e72034495 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx @@ -29,13 +29,13 @@ Example: ## Classes -### `GitHubProviderSettings` +### `GitHubProviderSettings` Settings for GitHub OAuth provider. -### `GitHubTokenVerifier` +### `GitHubTokenVerifier` Token verifier for GitHub OAuth tokens. @@ -46,7 +46,7 @@ by calling GitHub's API to check if they're valid and get user info. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -55,7 +55,7 @@ verify_token(self, token: str) -> AccessToken | None Verify GitHub OAuth token by calling GitHub API. -### `GitHubProvider` +### `GitHubProvider` Complete GitHub OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx index 307246b15..20d3a63e9 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx @@ -29,13 +29,13 @@ Example: ## Classes -### `GoogleProviderSettings` +### `GoogleProviderSettings` Settings for Google OAuth provider. -### `GoogleTokenVerifier` +### `GoogleTokenVerifier` Token verifier for Google OAuth tokens. @@ -46,7 +46,7 @@ by calling Google's tokeninfo API to check if they're valid and get user info. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -55,7 +55,7 @@ verify_token(self, token: str) -> AccessToken | None Verify Google OAuth token by calling Google's tokeninfo API. -### `GoogleProvider` +### `GoogleProvider` Complete Google OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx new file mode 100644 index 000000000..f1b9a5df0 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx @@ -0,0 +1,64 @@ +--- +title: scalekit +sidebarTitle: scalekit +--- + +# `fastmcp.server.auth.providers.scalekit` + + +Scalekit authentication provider for FastMCP. + +This module provides ScalekitProvider - a complete authentication solution that integrates +with Scalekit's OAuth 2.1 and OpenID Connect services, supporting Resource Server +authentication for seamless MCP client authentication. + + +## Classes + +### `ScalekitProviderSettings` + +### `ScalekitProvider` + + +Scalekit resource server provider for OAuth 2.1 authentication. + +This provider implements Scalekit integration using resource server pattern. +FastMCP acts as a protected resource server that validates access tokens issued +by Scalekit's authorization server. + +IMPORTANT SETUP REQUIREMENTS: + +1. Create an MCP Server in Scalekit Dashboard: + - Go to your [Scalekit Dashboard](https://app.scalekit.com/) + - Navigate to MCP Servers section + - Register a new MCP Server with appropriate scopes + - Ensure the Resource Identifier matches exactly what you configure as MCP URL + - Note the Resource ID + +2. Environment Configuration: + - Set SCALEKIT_ENVIRONMENT_URL (e.g., https://your-env.scalekit.com) + - Set SCALEKIT_CLIENT_ID from your OAuth application + - Set SCALEKIT_RESOURCE_ID from your created resource + - Set MCP_URL to your FastMCP server's public URL + +For detailed setup instructions, see: +https://docs.scalekit.com/mcp/overview/ + + +**Methods:** + +#### `get_routes` + +```python +get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +``` + +Get OAuth routes including Scalekit authorization server metadata forwarding. + +This returns the standard protected resource routes plus an authorization server +metadata endpoint that forwards Scalekit's OAuth metadata to clients. + +**Args:** +- `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") +- `mcp_endpoint`: The MCP endpoint handler to protect with auth + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx index 3132111f1..a4ac73e02 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx @@ -18,13 +18,13 @@ Choose based on your WorkOS setup and authentication requirements. ## Classes -### `WorkOSProviderSettings` +### `WorkOSProviderSettings` Settings for WorkOS OAuth provider. -### `WorkOSTokenVerifier` +### `WorkOSTokenVerifier` Token verifier for WorkOS OAuth tokens. @@ -35,7 +35,7 @@ the /oauth2/userinfo endpoint to check validity and get user info. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -44,7 +44,7 @@ verify_token(self, token: str) -> AccessToken | None Verify WorkOS OAuth token by calling userinfo endpoint. -### `WorkOSProvider` +### `WorkOSProvider` Complete WorkOS OAuth provider for FastMCP. @@ -65,9 +65,9 @@ Setup Requirements: 4. Note your Client ID and Client Secret -### `AuthKitProviderSettings` +### `AuthKitProviderSettings` -### `AuthKitProvider` +### `AuthKitProvider` AuthKit metadata provider for DCR (Dynamic Client Registration). @@ -93,7 +93,7 @@ https://workos.com/docs/authkit/mcp/integrating/token-verification **Methods:** -#### `get_routes` +#### `get_routes` ```python get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx index bbc14d0ee..f828d513f 100644 --- a/docs/python-sdk/fastmcp-server-context.mdx +++ b/docs/python-sdk/fastmcp-server-context.mdx @@ -7,7 +7,7 @@ sidebarTitle: context ## Functions -### `set_context` +### `set_context` ```python set_context(context: Context) -> Generator[Context, None, None] @@ -15,7 +15,7 @@ set_context(context: Context) -> Generator[Context, None, None] ## Classes -### `LogData` +### `LogData` Data object for passing log arguments to client-side handlers. @@ -24,7 +24,7 @@ This provides an interface to match the Python standard library logging, for compatibility with structured logging. -### `Context` +### `Context` Context object providing access to MCP capabilities. @@ -36,18 +36,18 @@ To use context in a tool function, add a parameter with the Context type annotat ```python @server.tool -def my_tool(x: int, ctx: Context) -> str: +async def my_tool(x: int, ctx: Context) -> str: # Log messages to the client - ctx.info(f"Processing {x}") - ctx.debug("Debug info") - ctx.warning("Warning message") - ctx.error("Error message") + await ctx.info(f"Processing {x}") + await ctx.debug("Debug info") + await ctx.warning("Warning message") + await ctx.error("Error message") # Report progress - ctx.report_progress(50, 100, "Processing") + await ctx.report_progress(50, 100, "Processing") # Access resources - data = ctx.read_resource("resource://data") + data = await ctx.read_resource("resource://data") # Get request info request_id = ctx.request_id @@ -72,7 +72,7 @@ The context is optional - tools that don't need it can omit the parameter. **Methods:** -#### `fastmcp` +#### `fastmcp` ```python fastmcp(self) -> FastMCP @@ -81,7 +81,7 @@ fastmcp(self) -> FastMCP Get the FastMCP instance. -#### `request_context` +#### `request_context` ```python request_context(self) -> RequestContext[ServerSession, Any, Request] @@ -92,7 +92,7 @@ Access to the underlying request context. If called outside of a request context, this will raise a ValueError. -#### `report_progress` +#### `report_progress` ```python report_progress(self, progress: float, total: float | None = None, message: str | None = None) -> None @@ -105,7 +105,7 @@ Report progress for the current operation. - `total`: Optional total value e.g. 100 -#### `read_resource` +#### `read_resource` ```python read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents] @@ -120,7 +120,7 @@ Read a resource by URI. - The resource content as either text or bytes -#### `log` +#### `log` ```python log(self, message: str, level: LoggingLevel | None = None, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -136,7 +136,7 @@ Send a log message to the client. - `extra`: Optional mapping for additional arguments -#### `client_id` +#### `client_id` ```python client_id(self) -> str | None @@ -145,7 +145,7 @@ client_id(self) -> str | None Get the client ID if available. -#### `request_id` +#### `request_id` ```python request_id(self) -> str @@ -154,7 +154,7 @@ request_id(self) -> str Get the unique ID for this request. -#### `session_id` +#### `session_id` ```python session_id(self) -> str @@ -171,7 +171,7 @@ the same client session. - for other transports. -#### `session` +#### `session` ```python session(self) -> ServerSession @@ -180,7 +180,7 @@ session(self) -> ServerSession Access to the underlying session for advanced usage. -#### `debug` +#### `debug` ```python debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -189,7 +189,7 @@ debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, An Send a debug log message. -#### `info` +#### `info` ```python info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -198,7 +198,7 @@ info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any Send an info log message. -#### `warning` +#### `warning` ```python warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -207,7 +207,7 @@ warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Send a warning log message. -#### `error` +#### `error` ```python error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -216,7 +216,7 @@ error(self, message: str, logger_name: str | None = None, extra: Mapping[str, An Send an error log message. -#### `list_roots` +#### `list_roots` ```python list_roots(self) -> list[Root] @@ -225,7 +225,7 @@ list_roots(self) -> list[Root] List the roots available to the server, as indicated by the client. -#### `send_tool_list_changed` +#### `send_tool_list_changed` ```python send_tool_list_changed(self) -> None @@ -234,7 +234,7 @@ send_tool_list_changed(self) -> None Send a tool list changed notification to the client. -#### `send_resource_list_changed` +#### `send_resource_list_changed` ```python send_resource_list_changed(self) -> None @@ -243,7 +243,7 @@ send_resource_list_changed(self) -> None Send a resource list changed notification to the client. -#### `send_prompt_list_changed` +#### `send_prompt_list_changed` ```python send_prompt_list_changed(self) -> None @@ -252,10 +252,10 @@ send_prompt_list_changed(self) -> None Send a prompt list changed notification to the client. -#### `sample` +#### `sample` ```python -sample(self, messages: str | list[str | SamplingMessage], system_prompt: str | None = None, include_context: IncludeContext | None = None, temperature: float | None = None, max_tokens: int | None = None, model_preferences: ModelPreferences | str | list[str] | None = None) -> ContentBlock +sample(self, messages: str | Sequence[str | SamplingMessage], system_prompt: str | None = None, include_context: IncludeContext | None = None, temperature: float | None = None, max_tokens: int | None = None, model_preferences: ModelPreferences | str | list[str] | None = None) -> TextContent | ImageContent | AudioContent ``` Send a sampling request to the client and await the response. @@ -265,25 +265,25 @@ completion from the client. The client must be appropriately configured, or the request will error. -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation ``` -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation ``` -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation ``` -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: type[T] | list[str] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation @@ -312,7 +312,7 @@ type or dataclass or BaseModel. If it is a primitive type, an object schema with a single "value" field will be generated. -#### `get_http_request` +#### `get_http_request` ```python get_http_request(self) -> Request @@ -321,7 +321,7 @@ get_http_request(self) -> Request Get the active starlette request. -#### `set_state` +#### `set_state` ```python set_state(self, key: str, value: Any) -> None @@ -330,7 +330,7 @@ set_state(self, key: str, value: Any) -> None Set a value in the context state. -#### `get_state` +#### `get_state` ```python get_state(self, key: str) -> Any diff --git a/docs/python-sdk/fastmcp-server-middleware-logging.mdx b/docs/python-sdk/fastmcp-server-middleware-logging.mdx index 853725a01..fd6ee041c 100644 --- a/docs/python-sdk/fastmcp-server-middleware-logging.mdx +++ b/docs/python-sdk/fastmcp-server-middleware-logging.mdx @@ -22,18 +22,15 @@ The default serializer for Payloads in the logging middleware. ## Classes -### `LoggingMiddleware` +### `BaseLoggingMiddleware` -Middleware that provides comprehensive request and response logging. - -Logs all MCP messages with configurable detail levels. Useful for debugging, -monitoring, and understanding server usage patterns. +Base class for logging middleware. **Methods:** -#### `on_message` +#### `on_message` ```python on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any @@ -42,7 +39,16 @@ on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) Log all messages. -### `StructuredLoggingMiddleware` +### `LoggingMiddleware` + + +Middleware that provides comprehensive request and response logging. + +Logs all MCP messages with configurable detail levels. Useful for debugging, +monitoring, and understanding server usage patterns. + + +### `StructuredLoggingMiddleware` Middleware that provides structured JSON logging for better log analysis. @@ -50,14 +56,3 @@ Middleware that provides structured JSON logging for better log analysis. Outputs structured logs that are easier to parse and analyze with log aggregation tools like ELK stack, Splunk, or cloud logging services. - -**Methods:** - -#### `on_message` - -```python -on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any -``` - -Log structured message information. - diff --git a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx index 806acaecc..a530af4b1 100644 --- a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx +++ b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx @@ -7,7 +7,7 @@ sidebarTitle: middleware ## Functions -### `make_middleware_wrapper` +### `make_middleware_wrapper` ```python make_middleware_wrapper(middleware: Middleware, call_next: CallNext[T, R]) -> CallNext[T, R] @@ -21,9 +21,9 @@ passed to other functions that expect a call_next function. ## Classes -### `CallNext` +### `CallNext` -### `MiddlewareContext` +### `MiddlewareContext` Unified context for all middleware operations. @@ -31,13 +31,13 @@ Unified context for all middleware operations. **Methods:** -#### `copy` +#### `copy` ```python copy(self, **kwargs: Any) -> MiddlewareContext[T] ``` -### `Middleware` +### `Middleware` Base class for FastMCP middleware with dispatching hooks. @@ -45,61 +45,61 @@ Base class for FastMCP middleware with dispatching hooks. **Methods:** -#### `on_message` +#### `on_message` ```python on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any ``` -#### `on_request` +#### `on_request` ```python on_request(self, context: MiddlewareContext[mt.Request], call_next: CallNext[mt.Request, Any]) -> Any ``` -#### `on_notification` +#### `on_notification` ```python on_notification(self, context: MiddlewareContext[mt.Notification], call_next: CallNext[mt.Notification, Any]) -> Any ``` -#### `on_call_tool` +#### `on_call_tool` ```python on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_next: CallNext[mt.CallToolRequestParams, ToolResult]) -> ToolResult ``` -#### `on_read_resource` +#### `on_read_resource` ```python -on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, mt.ReadResourceResult]) -> mt.ReadResourceResult +on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, list[ReadResourceContents]]) -> list[ReadResourceContents] ``` -#### `on_get_prompt` +#### `on_get_prompt` ```python on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, mt.GetPromptResult]) -> mt.GetPromptResult ``` -#### `on_list_tools` +#### `on_list_tools` ```python on_list_tools(self, context: MiddlewareContext[mt.ListToolsRequest], call_next: CallNext[mt.ListToolsRequest, list[Tool]]) -> list[Tool] ``` -#### `on_list_resources` +#### `on_list_resources` ```python on_list_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], call_next: CallNext[mt.ListResourcesRequest, list[Resource]]) -> list[Resource] ``` -#### `on_list_resource_templates` +#### `on_list_resource_templates` ```python on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, list[ResourceTemplate]]) -> list[ResourceTemplate] ``` -#### `on_list_prompts` +#### `on_list_prompts` ```python on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_next: CallNext[mt.ListPromptsRequest, list[Prompt]]) -> list[Prompt] diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx index dcaf8e12f..20b58f460 100644 --- a/docs/python-sdk/fastmcp-server-server.mdx +++ b/docs/python-sdk/fastmcp-server-server.mdx @@ -10,7 +10,7 @@ FastMCP - A more ergonomic interface for MCP servers. ## Functions -### `default_lifespan` +### `default_lifespan` ```python default_lifespan(server: FastMCP[LifespanResultT]) -> AsyncIterator[Any] @@ -26,7 +26,7 @@ Default lifespan context manager that does nothing. - An empty context object -### `add_resource_prefix` +### `add_resource_prefix` ```python add_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str @@ -64,7 +64,7 @@ add_resource_prefix("resource:///absolute/path", "prefix") - `ValueError`: If the URI doesn't match the expected protocol\://path format -### `remove_resource_prefix` +### `remove_resource_prefix` ```python remove_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str @@ -103,7 +103,7 @@ remove_resource_prefix("resource://prefix//absolute/path", "prefix") - `ValueError`: If the URI doesn't match the expected protocol\://path format -### `has_resource_prefix` +### `has_resource_prefix` ```python has_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> bool @@ -143,28 +143,34 @@ False ## Classes -### `FastMCP` +### `FastMCP` **Methods:** -#### `settings` +#### `settings` ```python settings(self) -> Settings ``` -#### `name` +#### `name` ```python name(self) -> str ``` -#### `instructions` +#### `instructions` ```python instructions(self) -> str | None ``` +#### `instructions` + +```python +instructions(self, value: str | None) -> None +``` + #### `version` ```python @@ -503,8 +509,8 @@ def get_weather(city: str) -> str: return f"Weather for {city}" @server.resource("resource://{city}/weather") -def get_weather_with_context(city: str, ctx: Context) -> str: - ctx.info(f"Fetching weather for {city}") +async def get_weather_with_context(city: str, ctx: Context) -> str: + await ctx.info(f"Fetching weather for {city}") return f"Weather for {city}" @server.resource("resource://{city}/weather") @@ -583,8 +589,8 @@ Decorator to register a prompt. ] @server.prompt() - def analyze_with_context(table_name: str, ctx: Context) -> list[Message]: - ctx.info(f"Analyzing table {table_name}") + async def analyze_with_context(table_name: str, ctx: Context) -> list[Message]: + await ctx.info(f"Analyzing table {table_name}") schema = read_table_schema(table_name) return [ { @@ -595,7 +601,7 @@ Decorator to register a prompt. ] @server.prompt("custom_name") - def analyze_file(path: str) -> list[Message]: + async def analyze_file(path: str) -> list[Message]: content = await read_file(path) return [ { @@ -622,13 +628,17 @@ Decorator to register a prompt. #### `run_stdio_async` ```python -run_stdio_async(self, show_banner: bool = True) -> None +run_stdio_async(self, show_banner: bool = True, log_level: str | None = None) -> None ``` Run the server using stdio transport. +**Args:** +- `show_banner`: Whether to display the server banner +- `log_level`: Log level for the server -#### `run_http_async` + +#### `run_http_async` ```python run_http_async(self, show_banner: bool = True, transport: Literal['http', 'streamable-http', 'sse'] = 'http', host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None, middleware: list[ASGIMiddleware] | None = None, stateless_http: bool | None = None) -> None @@ -647,7 +657,7 @@ Run the server using HTTP transport. - `stateless_http`: Whether to use stateless HTTP (defaults to settings.stateless_http) -#### `run_sse_async` +#### `run_sse_async` ```python run_sse_async(self, host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None) -> None @@ -656,7 +666,7 @@ run_sse_async(self, host: str | None = None, port: int | None = None, log_level: Run the server using SSE transport. -#### `sse_app` +#### `sse_app` ```python sse_app(self, path: str | None = None, message_path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan @@ -670,7 +680,7 @@ Create a Starlette app for the SSE server. - `middleware`: A list of middleware to apply to the app -#### `streamable_http_app` +#### `streamable_http_app` ```python streamable_http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan @@ -683,7 +693,7 @@ Create a Starlette app for the StreamableHTTP server. - `middleware`: A list of middleware to apply to the app -#### `http_app` +#### `http_app` ```python http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None, json_response: bool | None = None, stateless_http: bool | None = None, transport: Literal['http', 'streamable-http', 'sse'] = 'http') -> StarletteWithLifespan @@ -700,13 +710,13 @@ Create a Starlette app using the specified HTTP transport. - A Starlette application configured with the specified transport -#### `run_streamable_http_async` +#### `run_streamable_http_async` ```python run_streamable_http_async(self, host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None) -> None ``` -#### `mount` +#### `mount` ```python mount(self, server: FastMCP[LifespanResultT], prefix: str | None = None, as_proxy: bool | None = None) -> None @@ -760,7 +770,7 @@ automatically determined based on whether the server has a custom lifespan - `prompt_separator`: Deprecated. Separator character for prompt names. -#### `import_server` +#### `import_server` ```python import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None, tool_separator: str | None = None, resource_separator: str | None = None, prompt_separator: str | None = None) -> None @@ -801,7 +811,7 @@ applied using the protocol\://prefix/path format - `prompt_separator`: Deprecated. Separator for prompt names. -#### `from_openapi` +#### `from_openapi` ```python from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route_maps: list[RouteMap] | list[RouteMapNew] | None = None, route_map_fn: OpenAPIRouteMapFn | OpenAPIRouteMapFnNew | None = None, mcp_component_fn: OpenAPIComponentFn | OpenAPIComponentFnNew | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI | FastMCPOpenAPINew @@ -810,7 +820,7 @@ from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route Create a FastMCP server from an OpenAPI specification. -#### `from_fastapi` +#### `from_fastapi` ```python from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] | list[RouteMapNew] | None = None, route_map_fn: OpenAPIRouteMapFn | OpenAPIRouteMapFnNew | None = None, mcp_component_fn: OpenAPIComponentFn | OpenAPIComponentFnNew | None = None, mcp_names: dict[str, str] | None = None, httpx_client_kwargs: dict[str, Any] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI | FastMCPOpenAPINew @@ -819,7 +829,7 @@ from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] Create a FastMCP server from a FastAPI application. -#### `as_proxy` +#### `as_proxy` ```python as_proxy(cls, backend: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy @@ -833,7 +843,7 @@ instance or any value accepted as the `transport` argument of `fastmcp.client.Client` constructor. -#### `from_client` +#### `from_client` ```python from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPProxy @@ -842,10 +852,10 @@ from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPPr Create a FastMCP proxy server from a FastMCP client. -#### `generate_name` +#### `generate_name` ```python generate_name(cls, name: str | None = None) -> str ``` -### `MountedServer` +### `MountedServer` diff --git a/docs/python-sdk/fastmcp-settings.mdx b/docs/python-sdk/fastmcp-settings.mdx index 185e05ab3..6f14415ec 100644 --- a/docs/python-sdk/fastmcp-settings.mdx +++ b/docs/python-sdk/fastmcp-settings.mdx @@ -7,7 +7,7 @@ sidebarTitle: settings ## Classes -### `ExtendedEnvSettingsSource` +### `ExtendedEnvSettingsSource` A special EnvSettingsSource that allows for multiple env var prefixes to be used. @@ -17,17 +17,17 @@ Raises a deprecation warning if the old `FASTMCP_SERVER_` prefix is used. **Methods:** -#### `get_field_value` +#### `get_field_value` ```python get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool] ``` -### `ExtendedSettingsConfigDict` +### `ExtendedSettingsConfigDict` -### `ExperimentalSettings` +### `ExperimentalSettings` -### `Settings` +### `Settings` FastMCP settings. @@ -35,7 +35,7 @@ FastMCP settings. **Methods:** -#### `get_setting` +#### `get_setting` ```python get_setting(self, attr: str) -> Any @@ -45,7 +45,7 @@ Get a setting. If the setting contains one or more `__`, it will be treated as a nested setting. -#### `set_setting` +#### `set_setting` ```python set_setting(self, attr: str, value: Any) -> None @@ -55,13 +55,13 @@ Set a setting. If the setting contains one or more `__`, it will be treated as a nested setting. -#### `settings_customise_sources` +#### `settings_customise_sources` ```python settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...] ``` -#### `settings` +#### `settings` ```python settings(self) -> Self @@ -71,8 +71,14 @@ This property is for backwards compatibility with FastMCP < 2.8.0, which accessed fastmcp.settings.settings -#### `normalize_log_level` +#### `normalize_log_level` ```python normalize_log_level(cls, v) ``` + +#### `server_auth_class` + +```python +server_auth_class(self) -> AuthProvider | None +``` diff --git a/docs/python-sdk/fastmcp-utilities-json_schema.mdx b/docs/python-sdk/fastmcp-utilities-json_schema.mdx index b782a2668..a436dda8e 100644 --- a/docs/python-sdk/fastmcp-utilities-json_schema.mdx +++ b/docs/python-sdk/fastmcp-utilities-json_schema.mdx @@ -7,7 +7,7 @@ sidebarTitle: json_schema ## Functions -### `compress_schema` +### `compress_schema` ```python compress_schema(schema: dict, prune_params: list[str] | None = None, prune_defs: bool = True, prune_additional_properties: bool = True, prune_titles: bool = False) -> dict diff --git a/docs/python-sdk/fastmcp-utilities-logging.mdx b/docs/python-sdk/fastmcp-utilities-logging.mdx index 90564927c..f139db07a 100644 --- a/docs/python-sdk/fastmcp-utilities-logging.mdx +++ b/docs/python-sdk/fastmcp-utilities-logging.mdx @@ -10,7 +10,7 @@ Logging utilities for FastMCP. ## Functions -### `get_logger` +### `get_logger` ```python get_logger(name: str) -> logging.Logger @@ -26,10 +26,10 @@ Get a logger nested under FastMCP namespace. - a configured logger instance -### `configure_logging` +### `configure_logging` ```python -configure_logging(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | int = 'INFO', logger: logging.Logger | None = None, enable_rich_tracebacks: bool = True, **rich_kwargs: Any) -> None +configure_logging(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | int = 'INFO', logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any) -> None ``` @@ -40,3 +40,19 @@ Configure logging for FastMCP. - `level`: the log level to use - `rich_kwargs`: the parameters to use for creating RichHandler + +### `temporary_log_level` + +```python +temporary_log_level(level: str | None, logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any) +``` + + +Context manager to temporarily set log level and restore it afterwards. + +**Args:** +- `level`: The temporary log level to set (e.g., "DEBUG", "INFO") +- `logger`: Optional logger to configure (defaults to FastMCP logger) +- `enable_rich_tracebacks`: Whether to enable rich tracebacks +- `**rich_kwargs`: Additional parameters for RichHandler + diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx index 51409f3d7..391759bc0 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx @@ -15,7 +15,7 @@ command-line arguments. ## Functions -### `generate_schema` +### `generate_schema` ```python generate_schema(output_path: Path | str | None = None) -> dict[str, Any] | None diff --git a/docs/python-sdk/fastmcp-utilities-storage.mdx b/docs/python-sdk/fastmcp-utilities-storage.mdx new file mode 100644 index 000000000..0d0ecd322 --- /dev/null +++ b/docs/python-sdk/fastmcp-utilities-storage.mdx @@ -0,0 +1,158 @@ +--- +title: storage +sidebarTitle: storage +--- + +# `fastmcp.utilities.storage` + + +Key-value storage utilities for persistent data management. + +## Classes + +### `KVStorage` + + +Protocol for key-value storage of JSON data. + + +**Methods:** + +#### `get` + +```python +get(self, key: str) -> dict[str, Any] | None +``` + +Get a JSON dict by key. + + +#### `set` + +```python +set(self, key: str, value: dict[str, Any]) -> None +``` + +Store a JSON dict by key. + + +#### `delete` + +```python +delete(self, key: str) -> None +``` + +Delete a value by key. + + +### `JSONFileStorage` + + +File-based key-value storage for JSON data with automatic metadata tracking. + +Each key-value pair is stored as a separate JSON file on disk. +Keys are sanitized to be filesystem-safe. + +The storage automatically wraps all data with metadata: +- timestamp: Timestamp when the entry was last written + +**Args:** +- `cache_dir`: Directory for storing JSON files + + +**Methods:** + +#### `get` + +```python +get(self, key: str) -> dict[str, Any] | None +``` + +Get a JSON dict from storage by key. + +**Args:** +- `key`: The key to retrieve + +**Returns:** +- The stored dict or None if not found + + +#### `set` + +```python +set(self, key: str, value: dict[str, Any]) -> None +``` + +Store a JSON dict with metadata. + +**Args:** +- `key`: The key to store under +- `value`: The dict to store + + +#### `delete` + +```python +delete(self, key: str) -> None +``` + +Delete a value from storage. + +**Args:** +- `key`: The key to delete + + +#### `cleanup_old_entries` + +```python +cleanup_old_entries(self, max_age_seconds: int = 30 * 24 * 60 * 60) -> int +``` + +Remove entries older than the specified age. + +Uses the timestamp field to determine age. + +**Args:** +- `max_age_seconds`: Maximum age in seconds (default 30 days) + +**Returns:** +- Number of entries removed + + +### `InMemoryStorage` + + +In-memory key-value storage for JSON data. + +Simple dict-based storage that doesn't persist across restarts. +Useful for testing or environments where file storage isn't available. + + +**Methods:** + +#### `get` + +```python +get(self, key: str) -> dict[str, Any] | None +``` + +Get a JSON dict from memory by key. + + +#### `set` + +```python +set(self, key: str, value: dict[str, Any]) -> None +``` + +Store a JSON dict in memory. + + +#### `delete` + +```python +delete(self, key: str) -> None +``` + +Delete a value from memory. + diff --git a/docs/python-sdk/fastmcp-utilities-tests.mdx b/docs/python-sdk/fastmcp-utilities-tests.mdx index ce6d3d761..669755575 100644 --- a/docs/python-sdk/fastmcp-utilities-tests.mdx +++ b/docs/python-sdk/fastmcp-utilities-tests.mdx @@ -43,7 +43,7 @@ not pickleable, so we need a function that creates and runs one. - The server URL. -### `caplog_for_fastmcp` +### `caplog_for_fastmcp` ```python caplog_for_fastmcp(caplog) @@ -55,7 +55,7 @@ Context manager to capture logs from FastMCP loggers even when propagation is di ## Classes -### `HeadlessOAuth` +### `HeadlessOAuth` OAuth provider that bypasses browser interaction for testing. @@ -66,7 +66,7 @@ instead of opening a browser and running a callback server. Useful for automated **Methods:** -#### `redirect_handler` +#### `redirect_handler` ```python redirect_handler(self, authorization_url: str) -> None @@ -75,7 +75,7 @@ redirect_handler(self, authorization_url: str) -> None Make HTTP request to authorization URL and store response for callback handler. -#### `callback_handler` +#### `callback_handler` ```python callback_handler(self) -> tuple[str, str | None] diff --git a/docs/updates.mdx b/docs/updates.mdx index a3feea050..d8862e20e 100644 --- a/docs/updates.mdx +++ b/docs/updates.mdx @@ -5,6 +5,52 @@ icon: "sparkles" tag: NEW --- + + +FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser. + +๐Ÿ” **OIDC Configuration** brings native support for OpenID Connect, enabling seamless integration with enterprise identity providers. + +๐Ÿข **Enterprise Authentication** expands with AWS Cognito and Descope providers, broadening the authentication ecosystem. + +๐Ÿ› ๏ธ **Improved Reliability** through enhanced URL handling, persistent OAuth storage, and numerous parser fixes based on community feedback. + + + + + +FastMCP 2.12.3 focuses on performance and developer experience improvements. This release includes optimized auth provider imports that reduce server startup time, enhanced OIDC authentication flows, and automatic inline snapshot creation for testing. + + + + + +Hotfix for streamable-http transport validation in fastmcp.json configuration files, resolving a parsing error when CLI arguments were merged against the configuration spec. + + + + + +FastMCP 2.12.1 strengthens OAuth proxy implementation with improved client storage reliability, PKCE forwarding, configurable token endpoint authentication methods, and expanded scope handling based on extensive community testing. + + + str: + """Echo the provided message.""" + return message + + +if __name__ == "__main__": + mcp.run(transport="http", port=8000) diff --git a/examples/auth/scalekit_oauth/README.md b/examples/auth/scalekit_oauth/README.md new file mode 100644 index 000000000..63c555244 --- /dev/null +++ b/examples/auth/scalekit_oauth/README.md @@ -0,0 +1,54 @@ +# Scalekit OAuth Example + +Demonstrates FastMCP server protection with Scalekit OAuth. + +## Setup + +### 1. Configure MCP server in Scalekit environment + +**Create a Scalekit Account**: + +- Go to [Scalekit Dashboard](https://app.scalekit.com/) +- Navigate to **Developers** โ†’ **Settings** +- Copy your Environment URL, Client ID, and Client Secret + +**Register Your MCP Server**: + +- Go to **MCP Servers** โ†’ **Create New Server** +- Fill in your MCP server details +- Note the **Resource ID** (e.g., `res_123`) + +Create a `.env` file: + +```bash +# Required Scalekit credentials +SCALEKIT_ENVIRONMENT_URL= +SCALEKIT_CLIENT_ID= # skc_7008EXAMPLE46 +SCALEKIT_RESOURCE_ID= # res_926EXAMPLE5878 +MCP_URL=http://localhost:8000/mcp +``` + +### 2. Run the Example + +Start the server: + +```bash +# From this directory +uv run python server.py +``` + +The server will start on `http://localhost:8000/mcp` with Scalekit OAuth authentication enabled. + +Test with client: + +```bash +uv run python client.py +``` + +The `client.py` will: + +1. Attempt to connect to the server +2. Detect that OAuth authentication is required +3. Open a browser for Scalekit authentication +4. Complete the OAuth flow and connect to the server +5. Demonstrate calling authenticated tools diff --git a/examples/auth/scalekit_oauth/client.py b/examples/auth/scalekit_oauth/client.py new file mode 100644 index 000000000..4146b2c49 --- /dev/null +++ b/examples/auth/scalekit_oauth/client.py @@ -0,0 +1,41 @@ +"""OAuth client example for connecting to Scalekit-protected FastMCP servers. + +This example demonstrates how to connect to a Scalekit OAuth-protected FastMCP server. + +To run: + python client.py +""" + +import asyncio + +from fastmcp.client import Client + +SERVER_URL = "http://127.0.0.1:8000/mcp" + + +async def main(): + try: + async with Client(SERVER_URL, auth="oauth") as client: + assert await client.ping() + print("โœ… Successfully authenticated with Scalekit!") + + tools = await client.list_tools() + print(f"๐Ÿ”ง Available tools ({len(tools)}):") + for tool in tools: + print(f" - {tool.name}: {tool.description}") + + # Test calling a tool + result = await client.call_tool("echo", {"message": "Hello from Scalekit!"}) + print(f"๐ŸŽฏ Echo result: {result}") + + # Test calling auth status tool + auth_status = await client.call_tool("auth_status", {}) + print(f"๐Ÿ‘ค Auth status: {auth_status}") + + except Exception as e: + print(f"โŒ Authentication failed: {e}") + raise + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/examples/auth/scalekit_oauth/server.py b/examples/auth/scalekit_oauth/server.py new file mode 100644 index 000000000..40da711e2 --- /dev/null +++ b/examples/auth/scalekit_oauth/server.py @@ -0,0 +1,48 @@ +"""Scalekit OAuth server example for FastMCP. + +This example demonstrates how to protect a FastMCP server with Scalekit OAuth. + +Required environment variables: +- SCALEKIT_ENVIRONMENT_URL: Your Scalekit environment URL (e.g., "https://your-env.scalekit.com") +- SCALEKIT_CLIENT_ID: Your Scalekit OAuth application client ID +- SCALEKIT_RESOURCE_ID: Your Scalekit resource ID + +To run: + python server.py +""" + +import os + +from fastmcp import FastMCP +from fastmcp.server.auth.providers.scalekit import ScalekitProvider + +auth = ScalekitProvider( + environment_url=os.getenv("SCALEKIT_ENVIRONMENT_URL") + or "https://your-env.scalekit.com", + client_id=os.getenv("SCALEKIT_CLIENT_ID") or "", + resource_id=os.getenv("SCALEKIT_RESOURCE_ID") or "", + mcp_url=os.getenv("MCP_URL", "http://localhost:8000/mcp"), +) + +mcp = FastMCP("Scalekit OAuth Example Server", auth=auth) + + +@mcp.tool +def echo(message: str) -> str: + """Echo the provided message.""" + return message + + +@mcp.tool +def auth_status() -> dict: + """Show Scalekit authentication status.""" + # In a real implementation, you would extract user info from the JWT token + return { + "message": "This tool requires authentication via Scalekit", + "authenticated": True, + "provider": "Scalekit", + } + + +if __name__ == "__main__": + mcp.run(transport="http", port=8000) diff --git a/examples/auth/workos_oauth/README.md b/examples/auth/workos_oauth/README.md index 359e5b904..62afa8df2 100644 --- a/examples/auth/workos_oauth/README.md +++ b/examples/auth/workos_oauth/README.md @@ -1,159 +1,27 @@ # WorkOS OAuth Example -This example demonstrates how to use the WorkOS OAuth provider with FastMCP servers. - -## Overview - -The WorkOS OAuth provider enables authentication using WorkOS User Management. It provides general OAuth2 authentication similar to GitHub or Google, with optional support for enterprise SSO connections. Unlike the AuthKit provider which uses DCR (Dynamic Client Registration), this provider works with traditional OAuth flows. +Demonstrates FastMCP server protection with WorkOS OAuth. ## Setup -### 1. WorkOS Configuration +1. Create a WorkOS application and copy your credentials: -1. **Create a WorkOS Application**: - - Go to [WorkOS Dashboard โ†’ Applications](https://dashboard.workos.com/applications) - - Create a new application or use an existing one - - Enable **User Management** for OAuth authentication - - Copy your `Client ID` and `API Key` (client secret) + ```bash + export WORKOS_CLIENT_ID="your-client-id" + export WORKOS_CLIENT_SECRET="your-client-secret" + export WORKOS_AUTHKIT_DOMAIN="https://your-app.authkit.app" + ``` -2. **Configure SSO Connection** (optional for enterprise SSO): - - Go to WorkOS Dashboard โ†’ Connections - - Set up your SSO connection (SAML, OIDC, or OAuth provider like Google/Microsoft) - - Note the `Organization ID` or `Connection ID` if using SSO +2. Run the server: -3. **Set Redirect URLs**: - - In your WorkOS application settings, add redirect URLs for your OAuth flow - - For this example: `http://localhost:8000/auth/callback` + ```bash + python server.py + ``` -### 2. Environment Variables +3. In another terminal, run the client: -Create a `.env` file in this directory: + ```bash + python client.py + ``` -```bash -# Required WorkOS credentials -WORKOS_CLIENT_ID=client_123 -WORKOS_API_KEY=sk_test_456 # Your WorkOS API key (client secret) - -# Server URL (optional, defaults to http://localhost:8000) -# WORKOS_BASE_URL=http://localhost:8000 - -# Optional: For enterprise SSO connections -# WORKOS_ORGANIZATION_ID=org_123 # Route to specific organization's SSO -# WORKOS_CONNECTION_ID=conn_456 # Route to specific SSO connection - -# Optional: Required scopes -# FASTMCP_SERVER_AUTH_WORKOS_REQUIRED_SCOPES=["profile", "email"] -``` - -### 3. Install Dependencies - -```bash -cd /Users/jlowin/Developer/fastmcp -uv sync -``` - -## Running the Example - -### Start the Server - -```bash -# From this directory -uv run python server.py -``` - -The server will start on `http://localhost:8000` with WorkOS OAuth authentication enabled. - -### Test with Client - -In another terminal: - -```bash -# From this directory -uv run python client.py -``` - -The client will: -1. Attempt to connect to the server -2. Detect that OAuth authentication is required -3. Open a browser for WorkOS authentication -4. Complete the OAuth flow and connect to the server -5. Demonstrate calling authenticated tools - -## How It Works - -### Authentication Flow - -1. **Client Request**: Client attempts to connect to FastMCP server -2. **Auth Challenge**: Server responds with `401 Unauthorized` and `WWW-Authenticate` header -3. **OAuth Discovery**: Client discovers OAuth endpoints from server metadata -4. **Authorization**: Client redirects user to WorkOS for authentication -5. **Callback**: WorkOS redirects back with authorization code -6. **Token Exchange**: Client exchanges code for access token -7. **API Calls**: Client uses access token for authenticated MCP requests - -### Server Components - -- **WorkOSProvider**: Validates tokens using WorkOS User Management API -- **Protected Resources**: MCP tools and resources require valid WorkOS tokens -- **OAuth Metadata**: Server advertises WorkOS as authorization server - -### Client Components - -- **OAuth Client**: Handles browser-based OAuth flow -- **Token Storage**: Caches tokens for future use -- **Automatic Auth**: Transparently handles authentication - -## Key Features - -- **SSO Integration**: Works with any WorkOS SSO connection -- **User Management**: Validates tokens against WorkOS User Management API -- **Token Caching**: Reuses tokens across sessions -- **Error Handling**: Graceful handling of auth failures and token expiration - -## Troubleshooting - -### Common Issues - -1. **"Invalid client" error**: Check CLIENT_ID and CLIENT_SECRET -2. **"Token validation failed"**: Check API_KEY and token scope -3. **"Redirect URI mismatch"**: Ensure redirect URL matches WorkOS settings -4. **Browser doesn't open**: Check firewall settings for localhost - -### Debug Mode - -Enable debug logging: - -```python -import logging -logging.basicConfig(level=logging.DEBUG) -``` - -### Token Inspection - -Check cached tokens: - -```bash -ls ~/.fastmcp/oauth-mcp-client-cache/ -``` - -Clear token cache: - -```python -from fastmcp.client.auth.oauth import FileTokenStorage -FileTokenStorage.clear_all() -``` - -## Security Notes - -- Never commit `.env` files with real credentials -- Use HTTPS in production -- Rotate API keys regularly -- Monitor WorkOS logs for unusual activity -- Set appropriate token expiration times - -## Next Steps - -- Explore WorkOS Directory Sync for user provisioning -- Set up multi-organization support -- Implement role-based access control -- Add custom scopes and claims validation \ No newline at end of file +The client will open your browser for WorkOS authentication. diff --git a/pyproject.toml b/pyproject.toml index 881bfe1ab..97feb117f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -142,3 +142,6 @@ extend-select = ["I", "UP"] "__init__.py" = ["F401", "I001", "RUF013"] # allow imports not at the top of the file "src/fastmcp/__init__.py" = ["E402"] + +[tool.codespell] +ignore-words-list = "asend,shttp,te" diff --git a/src/fastmcp/cli/install/gemini_cli.py b/src/fastmcp/cli/install/gemini_cli.py index c6c7c1b5d..c09016990 100644 --- a/src/fastmcp/cli/install/gemini_cli.py +++ b/src/fastmcp/cli/install/gemini_cli.py @@ -104,7 +104,6 @@ def install_gemini_cli( ) return False - # Build uv run command using Environment.build_uv_run_command() env_config = UVEnvironment( python=python_version, dependencies=(with_packages or []) + ["fastmcp"], diff --git a/src/fastmcp/contrib/mcp_mixin/README.md b/src/fastmcp/contrib/mcp_mixin/README.md index e02d57cba..0742d7b6a 100644 --- a/src/fastmcp/contrib/mcp_mixin/README.md +++ b/src/fastmcp/contrib/mcp_mixin/README.md @@ -91,12 +91,12 @@ class MyComponent(MCPMixin): # prompt @mcp_prompt(name="A prompt") def prompt_method(self, name): - return f"Whats up {name}?" + return f"What's up {name}?" # disabled prompt @mcp_prompt(name="A prompt", enabled=False) def prompt_method(self, name): - return f"Whats up {name}?" + return f"What's up {name}?" mcp_server = FastMCP() component = MyComponent() diff --git a/src/fastmcp/server/auth/providers/scalekit.py b/src/fastmcp/server/auth/providers/scalekit.py new file mode 100644 index 000000000..8c6a0a79d --- /dev/null +++ b/src/fastmcp/server/auth/providers/scalekit.py @@ -0,0 +1,181 @@ +"""Scalekit authentication provider for FastMCP. + +This module provides ScalekitProvider - a complete authentication solution that integrates +with Scalekit's OAuth 2.1 and OpenID Connect services, supporting Resource Server +authentication for seamless MCP client authentication. +""" + +from __future__ import annotations + +from typing import Any + +import httpx +from pydantic import AnyHttpUrl +from pydantic_settings import BaseSettings, SettingsConfigDict +from starlette.responses import JSONResponse +from starlette.routing import Route + +from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier +from fastmcp.server.auth.providers.jwt import JWTVerifier +from fastmcp.utilities.logging import get_logger +from fastmcp.utilities.types import NotSet, NotSetT + +logger = get_logger(__name__) + + +class ScalekitProviderSettings(BaseSettings): + model_config = SettingsConfigDict( + env_prefix="FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_", + env_file=".env", + extra="ignore", + ) + + environment_url: AnyHttpUrl + client_id: str + resource_id: str + mcp_url: AnyHttpUrl + + +class ScalekitProvider(RemoteAuthProvider): + """Scalekit resource server provider for OAuth 2.1 authentication. + + This provider implements Scalekit integration using resource server pattern. + FastMCP acts as a protected resource server that validates access tokens issued + by Scalekit's authorization server. + + IMPORTANT SETUP REQUIREMENTS: + + 1. Create an MCP Server in Scalekit Dashboard: + - Go to your [Scalekit Dashboard](https://app.scalekit.com/) + - Navigate to MCP Servers section + - Register a new MCP Server with appropriate scopes + - Ensure the Resource Identifier matches exactly what you configure as MCP URL + - Note the Resource ID + + 2. Environment Configuration: + - Set SCALEKIT_ENVIRONMENT_URL (e.g., https://your-env.scalekit.com) + - Set SCALEKIT_CLIENT_ID from your OAuth application + - Set SCALEKIT_RESOURCE_ID from your created resource + - Set MCP_URL to your FastMCP server's public URL + + For detailed setup instructions, see: + https://docs.scalekit.com/mcp/overview/ + + Example: + ```python + from fastmcp.server.auth.providers.scalekit import ScalekitProvider + + # Create Scalekit resource server provider + scalekit_auth = ScalekitProvider( + environment_url="https://your-env.scalekit.com", + client_id="sk_client_...", + resource_id="sk_resource_...", + mcp_url="https://your-fastmcp-server.com", + ) + + # Use with FastMCP + mcp = FastMCP("My App", auth=scalekit_auth) + ``` + """ + + def __init__( + self, + *, + environment_url: AnyHttpUrl | str | NotSetT = NotSet, + client_id: str | NotSetT = NotSet, + resource_id: str | NotSetT = NotSet, + mcp_url: AnyHttpUrl | str | NotSetT = NotSet, + token_verifier: TokenVerifier | None = None, + ): + """Initialize Scalekit resource server provider. + + Args: + environment_url: Your Scalekit environment URL (e.g., "https://your-env.scalekit.com") + client_id: Your Scalekit OAuth client ID + resource_id: Your Scalekit resource ID + mcp_url: Public URL of this FastMCP server (used as audience) + token_verifier: Optional token verifier. If None, creates JWT verifier for Scalekit + """ + settings = ScalekitProviderSettings.model_validate( + { + k: v + for k, v in { + "environment_url": environment_url, + "client_id": client_id, + "resource_id": resource_id, + "mcp_url": mcp_url, + }.items() + if v is not NotSet + } + ) + + self.environment_url = str(settings.environment_url).rstrip("/") + self.client_id = settings.client_id + self.resource_id = settings.resource_id + self.mcp_url = str(settings.mcp_url) + + # Create default JWT verifier if none provided + if token_verifier is None: + token_verifier = JWTVerifier( + jwks_uri=f"{self.environment_url}/keys", + issuer=self.environment_url, + algorithm="RS256", + audience=self.mcp_url, + ) + + # Initialize RemoteAuthProvider with Scalekit as the authorization server + super().__init__( + token_verifier=token_verifier, + authorization_servers=[ + AnyHttpUrl(f"{self.environment_url}/resources/{self.resource_id}") + ], + base_url=self.mcp_url, + ) + + def get_routes( + self, + mcp_path: str | None = None, + mcp_endpoint: Any | None = None, + ) -> list[Route]: + """Get OAuth routes including Scalekit authorization server metadata forwarding. + + This returns the standard protected resource routes plus an authorization server + metadata endpoint that forwards Scalekit's OAuth metadata to clients. + + Args: + mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp") + mcp_endpoint: The MCP endpoint handler to protect with auth + """ + # Get the standard protected resource routes from RemoteAuthProvider + routes = super().get_routes(mcp_path, mcp_endpoint) + + async def oauth_authorization_server_metadata(request): + """Forward Scalekit OAuth authorization server metadata with FastMCP customizations.""" + try: + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.environment_url}/.well-known/oauth-authorization-server/resources/{self.resource_id}" + ) + response.raise_for_status() + metadata = response.json() + return JSONResponse(metadata) + except Exception as e: + logger.error(f"Failed to fetch Scalekit metadata: {e}") + return JSONResponse( + { + "error": "server_error", + "error_description": f"Failed to fetch Scalekit metadata: {e}", + }, + status_code=500, + ) + + # Add Scalekit authorization server metadata forwarding + routes.append( + Route( + "/.well-known/oauth-authorization-server", + endpoint=oauth_authorization_server_metadata, + methods=["GET"], + ) + ) + + return routes diff --git a/src/fastmcp/server/openapi.py b/src/fastmcp/server/openapi.py index e090957fd..3aa752abc 100644 --- a/src/fastmcp/server/openapi.py +++ b/src/fastmcp/server/openapi.py @@ -785,6 +785,7 @@ class FastMCPOpenAPI(FastMCP): http_routes = openapi.parse_openapi_to_http_routes(openapi_spec) # Process routes + num_excluded = 0 route_maps = (route_maps or []) + DEFAULT_ROUTE_MAPPINGS for route in http_routes: # Determine route type based on mappings or default rules @@ -823,8 +824,11 @@ class FastMCPOpenAPI(FastMCP): self._create_openapi_template(route, component_name, tags=route_tags) elif route_type == MCPType.EXCLUDE: logger.info(f"Excluding route: {route.method} {route.path}") + num_excluded += 1 - logger.info(f"Created FastMCP OpenAPI server with {len(http_routes)} routes") + logger.info( + f"Created FastMCP OpenAPI server with {len(http_routes) - num_excluded} routes" + ) def _generate_default_name( self, route: openapi.HTTPRoute, mcp_names_map: dict[str, str] | None = None diff --git a/src/fastmcp/utilities/logging.py b/src/fastmcp/utilities/logging.py index 095cb3375..4d06418df 100644 --- a/src/fastmcp/utilities/logging.py +++ b/src/fastmcp/utilities/logging.py @@ -19,7 +19,7 @@ def get_logger(name: str) -> logging.Logger: Returns: a configured logger instance """ - return logging.getLogger(f"FastMCP.{name}") + return logging.getLogger(f"fastmcp.{name}") def configure_logging( @@ -45,7 +45,7 @@ def configure_logging( enable_rich_tracebacks = fastmcp.settings.enable_rich_tracebacks if logger is None: - logger = logging.getLogger("FastMCP") + logger = logging.getLogger("fastmcp") # Only configure the FastMCP logger namespace handler = RichHandler( diff --git a/src/fastmcp/utilities/tests.py b/src/fastmcp/utilities/tests.py index 4ddee9597..309a4bf9d 100644 --- a/src/fastmcp/utilities/tests.py +++ b/src/fastmcp/utilities/tests.py @@ -143,10 +143,10 @@ def run_server_in_process( def caplog_for_fastmcp(caplog): """Context manager to capture logs from FastMCP loggers even when propagation is disabled.""" caplog.clear() - logger = logging.getLogger("FastMCP") + logger = logging.getLogger("fastmcp") logger.addHandler(caplog.handler) try: - yield + yield caplog finally: logger.removeHandler(caplog.handler) diff --git a/tests/client/test_client.py b/tests/client/test_client.py index bae0ca81f..b521a8cdc 100644 --- a/tests/client/test_client.py +++ b/tests/client/test_client.py @@ -457,12 +457,12 @@ async def test_client_nested_context_manager(fastmcp_server): assert client._session_state.session is not None session = client._session_state.session - # Re-use the same session + # Reuse the same session async with client: assert client.is_connected() assert client._session_state.session is session - # Re-use the same session + # Reuse the same session async with client: assert client.is_connected() assert client._session_state.session is session diff --git a/tests/server/auth/providers/test_scalekit.py b/tests/server/auth/providers/test_scalekit.py new file mode 100644 index 000000000..d7f7a6546 --- /dev/null +++ b/tests/server/auth/providers/test_scalekit.py @@ -0,0 +1,162 @@ +"""Tests for Scalekit OAuth provider.""" + +import os +from collections.abc import Generator +from unittest.mock import patch + +import httpx +import pytest + +from fastmcp import Client, FastMCP +from fastmcp.client.transports import StreamableHttpTransport +from fastmcp.server.auth.providers.scalekit import ScalekitProvider +from fastmcp.utilities.tests import HeadlessOAuth, run_server_in_process + + +class TestScalekitProvider: + """Test Scalekit OAuth provider functionality.""" + + def test_init_with_explicit_params(self): + """Test ScalekitProvider initialization with explicit parameters.""" + provider = ScalekitProvider( + environment_url="https://my-env.scalekit.com", + client_id="sk_client_123", + resource_id="sk_resource_456", + mcp_url="https://myserver.com/", + ) + + assert provider.environment_url == "https://my-env.scalekit.com" + assert provider.client_id == "sk_client_123" + assert provider.resource_id == "sk_resource_456" + assert str(provider.mcp_url) == "https://myserver.com/" + + def test_init_with_env_vars(self): + """Test ScalekitProvider initialization from environment variables.""" + with patch.dict( + os.environ, + { + "FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_ENVIRONMENT_URL": "https://env-scalekit.com", + "FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_CLIENT_ID": "skc_123", + "FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_RESOURCE_ID": "res_456", + "FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_MCP_URL": "https://envserver.com/mcp", + }, + ): + provider = ScalekitProvider() + + assert provider.environment_url == "https://env-scalekit.com" + assert provider.client_id == "skc_123" + assert provider.resource_id == "res_456" + assert str(provider.mcp_url) == "https://envserver.com/mcp" + + def test_environment_variable_loading(self): + """Test that environment variables are loaded correctly.""" + provider = ScalekitProvider( + environment_url="https://test-env.scalekit.com", + client_id="sk_client_test_123", + resource_id="sk_resource_test_456", + mcp_url="http://test-server.com", + ) + + assert provider.environment_url == "https://test-env.scalekit.com" + assert provider.client_id == "sk_client_test_123" + assert provider.resource_id == "sk_resource_test_456" + assert str(provider.mcp_url) == "http://test-server.com/" + + def test_url_trailing_slash_handling(self): + """Test that URLs handle trailing slashes correctly.""" + provider = ScalekitProvider( + environment_url="https://my-env.scalekit.com/", + client_id="sk_client_123", + resource_id="sk_resource_456", + mcp_url="https://myserver.com/", + ) + + assert provider.environment_url == "https://my-env.scalekit.com" + assert str(provider.mcp_url) == "https://myserver.com/" + + def test_jwt_verifier_configured_correctly(self): + """Test that JWT verifier is configured correctly.""" + provider = ScalekitProvider( + environment_url="https://my-env.scalekit.com", + client_id="sk_client_123", + resource_id="sk_resource_456", + mcp_url="https://myserver.com/", + ) + + # Check that JWT verifier uses the correct endpoints + assert ( + provider.token_verifier.jwks_uri # type: ignore[attr-defined] + == "https://my-env.scalekit.com/keys" + ) + assert ( + provider.token_verifier.issuer == "https://my-env.scalekit.com" # type: ignore[attr-defined] + ) + assert provider.token_verifier.audience == "https://myserver.com/" # type: ignore[attr-defined] + + def test_authorization_servers_configuration(self): + """Test that authorization servers are configured correctly.""" + provider = ScalekitProvider( + environment_url="https://my-env.scalekit.com", + client_id="sk_client_123", + resource_id="sk_resource_456", + mcp_url="https://myserver.com/", + ) + + assert len(provider.authorization_servers) == 1 + assert ( + str(provider.authorization_servers[0]) + == "https://my-env.scalekit.com/resources/sk_resource_456" + ) + + +def run_mcp_server(host: str, port: int) -> None: + mcp = FastMCP( + auth=ScalekitProvider( + environment_url="https://test-env.scalekit.com", + client_id="sk_client_test_123", + resource_id="sk_resource_test_456", + mcp_url="http://localhost:4321", + ) + ) + + @mcp.tool + def add(a: int, b: int) -> int: + return a + b + + mcp.run(host=host, port=port, transport="http") + + +@pytest.fixture +def mcp_server_url() -> Generator[str]: + with run_server_in_process(run_mcp_server) as url: + yield f"{url}/mcp" + + +@pytest.fixture() +def client_with_headless_oauth( + mcp_server_url: str, +) -> Generator[Client, None, None]: + """Client with headless OAuth that bypasses browser interaction.""" + client = Client( + transport=StreamableHttpTransport(mcp_server_url), + auth=HeadlessOAuth(mcp_url=mcp_server_url), + ) + yield client + + +class TestScalekitProviderIntegration: + async def test_unauthorized_access(self, mcp_server_url: str): + with pytest.raises(httpx.HTTPStatusError) as exc_info: + async with Client(mcp_server_url) as client: + tools = await client.list_tools() # noqa: F841 + + assert isinstance(exc_info.value, httpx.HTTPStatusError) + assert exc_info.value.response.status_code == 401 + assert "tools" not in locals() + + # async def test_authorized_access(self, client_with_headless_oauth: Client): + # async with client_with_headless_oauth: + # tools = await client_with_headless_oauth.list_tools() + # assert tools is not None + # assert len(tools) > 0 + # assert "add" in tools diff --git a/tests/server/middleware/test_error_handling.py b/tests/server/middleware/test_error_handling.py index 0983cfb1c..6c7c3cde3 100644 --- a/tests/server/middleware/test_error_handling.py +++ b/tests/server/middleware/test_error_handling.py @@ -11,6 +11,7 @@ from fastmcp.server.middleware.error_handling import ( RetryMiddleware, ) from fastmcp.server.middleware.middleware import MiddlewareContext +from fastmcp.utilities.tests import caplog_for_fastmcp @pytest.fixture @@ -60,8 +61,9 @@ class TestErrorHandlingMiddleware: middleware = ErrorHandlingMiddleware() error = ValueError("test error") - with caplog.at_level(logging.ERROR): - middleware._log_error(error, mock_context) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + middleware._log_error(error, mock_context) assert "Error in test_method: ValueError: test error" in caplog.text assert "ValueError:test_method" in middleware.error_counts @@ -72,8 +74,9 @@ class TestErrorHandlingMiddleware: middleware = ErrorHandlingMiddleware(include_traceback=True) error = ValueError("test error") - with caplog.at_level(logging.ERROR): - middleware._log_error(error, mock_context) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + middleware._log_error(error, mock_context) assert "Error in test_method: ValueError: test error" in caplog.text # The traceback is added to the log message @@ -95,8 +98,9 @@ class TestErrorHandlingMiddleware: middleware = ErrorHandlingMiddleware(error_callback=callback) error = ValueError("test error") - with caplog.at_level(logging.ERROR): - middleware._log_error(error, mock_context) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + middleware._log_error(error, mock_context) assert "Error in error callback: callback error" in caplog.text @@ -189,9 +193,10 @@ class TestErrorHandlingMiddleware: middleware = ErrorHandlingMiddleware() mock_call_next = AsyncMock(side_effect=ValueError("test error")) - with caplog.at_level(logging.ERROR): - with pytest.raises(McpError) as exc_info: - await middleware.on_message(mock_context, mock_call_next) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + with pytest.raises(McpError) as exc_info: + await middleware.on_message(mock_context, mock_call_next) assert isinstance(exc_info.value, McpError) assert exc_info.value.error.code == -32602 @@ -293,8 +298,9 @@ class TestRetryMiddleware: ] ) - with caplog.at_level(logging.WARNING): - result = await middleware.on_request(mock_context, mock_call_next) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.WARNING): + result = await middleware.on_request(mock_context, mock_call_next) assert result == "test_result" assert mock_call_next.call_count == 3 @@ -307,9 +313,10 @@ class TestRetryMiddleware: # Fail all attempts mock_call_next = AsyncMock(side_effect=ConnectionError("connection failed")) - with caplog.at_level(logging.WARNING): - with pytest.raises(ConnectionError): - await middleware.on_request(mock_context, mock_call_next) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.WARNING): + with pytest.raises(ConnectionError): + await middleware.on_request(mock_context, mock_call_next) assert mock_call_next.call_count == 3 # initial + 2 retries assert "Retrying in" in caplog.text @@ -385,14 +392,19 @@ class TestErrorHandlingMiddlewareIntegration: error_handling_server.add_middleware(ErrorHandlingMiddleware()) - with caplog.at_level(logging.ERROR): - async with Client(error_handling_server) as client: - # Test different types of errors - with pytest.raises(Exception): - await client.call_tool("failing_operation", {"error_type": "value"}) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + async with Client(error_handling_server) as client: + # Test different types of errors + with pytest.raises(Exception): + await client.call_tool( + "failing_operation", {"error_type": "value"} + ) - with pytest.raises(Exception): - await client.call_tool("failing_operation", {"error_type": "file"}) + with pytest.raises(Exception): + await client.call_tool( + "failing_operation", {"error_type": "file"} + ) log_text = caplog.text @@ -443,17 +455,20 @@ class TestErrorHandlingMiddlewareIntegration: error_handling_server.add_middleware(ErrorHandlingMiddleware()) - with caplog.at_level(logging.ERROR): - async with Client(error_handling_server) as client: - # Successful operation (should not generate error logs) - await client.call_tool("reliable_operation", {"data": "test"}) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + async with Client(error_handling_server) as client: + # Successful operation (should not generate error logs) + await client.call_tool("reliable_operation", {"data": "test"}) - # Failed operation (should generate error log) - with pytest.raises(Exception): - await client.call_tool("failing_operation", {"error_type": "value"}) + # Failed operation (should generate error log) + with pytest.raises(Exception): + await client.call_tool( + "failing_operation", {"error_type": "value"} + ) - # Another successful operation - await client.call_tool("reliable_operation", {"data": "test2"}) + # Another successful operation + await client.call_tool("reliable_operation", {"data": "test2"}) log_text = caplog.text @@ -533,18 +548,19 @@ class TestRetryMiddlewareIntegration: ) ) - with caplog.at_level(logging.WARNING): - async with Client(error_handling_server) as client: - # This operation fails intermittently - try several times - success_count = 0 - for _ in range(5): - try: - await client.call_tool( - "intermittent_operation", {"fail_rate": 0.7} - ) - success_count += 1 - except Exception: - pass # Some failures expected even with retries + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.WARNING): + async with Client(error_handling_server) as client: + # This operation fails intermittently - try several times + success_count = 0 + for _ in range(5): + try: + await client.call_tool( + "intermittent_operation", {"fail_rate": 0.7} + ) + success_count += 1 + except Exception: + pass # Some failures expected even with retries # Should have some retry log messages # Note: Retry logs might not appear if the underlying errors are wrapped by FastMCP @@ -584,17 +600,22 @@ class TestRetryMiddlewareIntegration: ) ) - with caplog.at_level(logging.ERROR): - async with Client(error_handling_server) as client: - # Try intermittent operation - try: - await client.call_tool("intermittent_operation", {"fail_rate": 0.9}) - except Exception: - pass # May still fail even with retries + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.ERROR): + async with Client(error_handling_server) as client: + # Try intermittent operation + try: + await client.call_tool( + "intermittent_operation", {"fail_rate": 0.9} + ) + except Exception: + pass # May still fail even with retries - # Try permanent failure - with pytest.raises(Exception): - await client.call_tool("failing_operation", {"error_type": "value"}) + # Try permanent failure + with pytest.raises(Exception): + await client.call_tool( + "failing_operation", {"error_type": "value"} + ) log_text = caplog.text diff --git a/tests/server/middleware/test_logging.py b/tests/server/middleware/test_logging.py index aca1b5767..2bbeda9fa 100644 --- a/tests/server/middleware/test_logging.py +++ b/tests/server/middleware/test_logging.py @@ -1,6 +1,7 @@ """Tests for logging middleware.""" import datetime +import json import logging import re from typing import Any, Literal, TypeVar @@ -10,14 +11,17 @@ import mcp import mcp.types import pytest from inline_snapshot import snapshot +from pydantic import AnyUrl from fastmcp import FastMCP from fastmcp.client import Client +from fastmcp.resources.template import ResourceTemplate from fastmcp.server.middleware.logging import ( LoggingMiddleware, StructuredLoggingMiddleware, ) -from fastmcp.server.middleware.middleware import MiddlewareContext +from fastmcp.server.middleware.middleware import CallNext, MiddlewareContext +from fastmcp.utilities.tests import caplog_for_fastmcp FIXED_DATE = datetime.datetime(2023, 1, 1, tzinfo=datetime.timezone.utc) @@ -186,7 +190,7 @@ class TestStructuredLoggingMiddleware: middleware = StructuredLoggingMiddleware() mock_call_next = AsyncMock(return_value="test_result") - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): result = await middleware.on_message(mock_context, mock_call_next) assert result == "test_result" @@ -204,7 +208,7 @@ INFO fastmcp.structured:logging.py:LINE_NUMBER Completed message: {"event": middleware = StructuredLoggingMiddleware() mock_call_next = AsyncMock(side_effect=ValueError("test error")) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): with pytest.raises(ValueError): await middleware.on_message(mock_context, mock_call_next) @@ -247,6 +251,257 @@ class TestLoggingMiddleware: assert "payload=" in formatted assert "..." in formatted + async def test_on_message_failure( + self, mock_context: MiddlewareContext[Any], caplog: pytest.LogCaptureFixture + ): + """Test structured logging of failed messages.""" + middleware = StructuredLoggingMiddleware() + mock_call_next = AsyncMock(side_effect=ValueError("test error")) + + with caplog_for_fastmcp(caplog): + with pytest.raises(ValueError): + await middleware.on_message(mock_context, mock_call_next) + + # Check that we have structured JSON logs + log_lines = [record.message for record in caplog.records] + assert len(log_lines) == 2 # start and error entries + + # Extract JSON from "Processing message: {JSON}" + start_message = log_lines[0] + assert start_message.startswith("Processing message: ") + start_json = start_message[len("Processing message: ") :] + start_entry = json.loads(start_json) + assert start_entry["event"] == "request_start" + + # Error messages have different format - check the second log entry + assert "Failed message:" in log_lines[1] + + async def test_on_message_with_pydantic_types_in_payload( + self, + mock_call_next: CallNext[Any, Any], + caplog: pytest.LogCaptureFixture, + ): + """Ensure Pydantic AnyUrl in payload serializes correctly when include_payloads=True.""" + + mock_context = new_mock_context( + message=mcp.types.ReadResourceRequest( + method="resources/read", + params=mcp.types.ReadResourceRequestParams( + uri=AnyUrl("test://example/1"), + ), + ) + ) + + middleware = StructuredLoggingMiddleware(include_payloads=True) + + with caplog_for_fastmcp(caplog): + result = await middleware.on_message(mock_context, mock_call_next) + + assert result == "test_result" + + log_lines = [record.message for record in caplog.records] + + assert len(log_lines) == 2 + + # Extract JSON from log messages + start_message = log_lines[0] + assert start_message.startswith("Processing message: ") + start_json = start_message[len("Processing message: ") :] + assert json.loads(start_json) == snapshot( + { + "event": "request_start", + "timestamp": "2023-01-01T00:00:00+00:00", + "source": "client", + "type": "request", + "method": "test_method", + "payload": '{"method":"resources/read","params":{"_meta":null,"uri":"test://example/1"}}', + "payload_type": "ReadResourceRequest", + } + ) + + success_message = log_lines[1] + assert success_message.startswith("Completed message: ") + success_json = success_message[len("Completed message: ") :] + assert json.loads(success_json) == snapshot( + { + "event": "request_success", + "timestamp": "2023-01-01T00:00:00+00:00", + "source": "client", + "type": "request", + "method": "test_method", + } + ) + + async def test_on_message_with_resource_template_in_payload( + self, + mock_call_next: CallNext[Any, Any], + caplog: pytest.LogCaptureFixture, + ): + """Ensure ResourceTemplate in payload serializes via pydantic conversion without errors.""" + + mock_context = new_mock_context( + message=ResourceTemplate( + name="tmpl", + uri_template="tmpl://{id}", + parameters={"id": {"type": "string"}}, + ) + ) + + middleware = StructuredLoggingMiddleware(include_payloads=True) + + with caplog_for_fastmcp(caplog): + result = await middleware.on_message(mock_context, mock_call_next) + + assert result == "test_result" + + log_lines = [record.message for record in caplog.records] + assert len(log_lines) == 2 + + # Extract JSON from log message + start_message = log_lines[0] + assert start_message.startswith("Processing message: ") + start_json = start_message[len("Processing message: ") :] + assert json.loads(start_json) == snapshot( + { + "event": "request_start", + "timestamp": "2023-01-01T00:00:00+00:00", + "source": "client", + "type": "request", + "method": "test_method", + "payload": '{"name":"tmpl","title":null,"description":null,"tags":[],"meta":null,"enabled":true,"uri_template":"tmpl://{id}","mime_type":"text/plain","parameters":{"id":{"type":"string"}},"annotations":null}', + "payload_type": "ResourceTemplate", + } + ) + + async def test_on_message_with_nonserializable_payload_falls_back_to_str( + self, mock_call_next: CallNext[Any, Any], caplog: pytest.LogCaptureFixture + ): + """Ensure non-JSONable objects fall back to string serialization in payload.""" + + class NonSerializable: + def __str__(self) -> str: + return "NON_SERIALIZABLE" + + mock_context = new_mock_context( + message=mcp.types.CallToolRequest( + method="tools/call", + params=mcp.types.CallToolRequestParams( + name="test_method", + arguments={"obj": NonSerializable()}, + ), + ) + ) + + middleware = StructuredLoggingMiddleware(include_payloads=True) + + with caplog_for_fastmcp(caplog): + result = await middleware.on_message(mock_context, mock_call_next) + + assert result == "test_result" + + log_lines = [record.message for record in caplog.records] + assert len(log_lines) >= 2 + + # Extract JSON from log message + start_message = log_lines[0] + assert start_message.startswith("Processing message: ") + start_json = start_message[len("Processing message: ") :] + assert json.loads(start_json) == snapshot( + { + "event": "request_start", + "timestamp": "2023-01-01T00:00:00+00:00", + "source": "client", + "type": "request", + "method": "test_method", + "payload": '{"method":"tools/call","params":{"_meta":null,"name":"test_method","arguments":{"obj":"NON_SERIALIZABLE"}}}', + "payload_type": "CallToolRequest", + } + ) + + async def test_on_message_with_custom_serializer_applied( + self, mock_call_next: CallNext[Any, Any], caplog: pytest.LogCaptureFixture + ): + """Ensure a custom serializer is used for non-JSONable payloads.""" + + # Provide a serializer that replaces entire payload with a fixed string + def custom_serializer(_: Any) -> str: + return "CUSTOM_PAYLOAD" + + mock_context = new_mock_context( + message=mcp.types.CallToolRequest( + method="tools/call", + params=mcp.types.CallToolRequestParams( + name="test_method", + arguments={"obj": "OBJECT"}, + ), + ) + ) + + middleware = StructuredLoggingMiddleware( + include_payloads=True, payload_serializer=custom_serializer + ) + + with caplog_for_fastmcp(caplog): + result = await middleware.on_message(mock_context, mock_call_next) + + assert result == "test_result" + + log_lines = [record.message for record in caplog.records] + assert len(log_lines) >= 2 + + # Extract JSON from log message + start_message = log_lines[0] + assert start_message.startswith("Processing message: ") + start_json = start_message[len("Processing message: ") :] + assert json.loads(start_json) == snapshot( + { + "event": "request_start", + "timestamp": "2023-01-01T00:00:00+00:00", + "source": "client", + "type": "request", + "method": "test_method", + "payload": "CUSTOM_PAYLOAD", + "payload_type": "CallToolRequest", + } + ) + + +@pytest.fixture +def logging_server(): + """Create a FastMCP server specifically for logging middleware tests.""" + from fastmcp import FastMCP + + mcp = FastMCP("LoggingTestServer") + + @mcp.tool + def simple_operation(data: str) -> str: + """A simple operation for testing logging.""" + return f"Processed: {data}" + + @mcp.tool + def complex_operation(items: list[str], mode: str = "default") -> dict: + """A complex operation with structured data.""" + return {"processed_items": len(items), "mode": mode, "result": "success"} + + @mcp.tool + def operation_with_error(should_fail: bool = False) -> str: + """An operation that can be made to fail.""" + if should_fail: + raise ValueError("Operation failed intentionally") + return "Operation completed successfully" + + @mcp.resource("log://test") + def test_resource() -> str: + """A test resource for logging.""" + return "Test resource content" + + @mcp.prompt + def test_prompt() -> str: + """A test prompt for logging.""" + return "Test prompt content" + + return mcp + class TestLoggingMiddlewareIntegration: """Integration tests for logging middleware with real FastMCP server.""" @@ -296,15 +551,16 @@ class TestLoggingMiddlewareIntegration: logging_server.add_middleware(logging_middleware) - with caplog.at_level(logging.INFO): - async with Client(logging_server) as client: - await client.call_tool( - name="simple_operation", arguments={"data": "test_data"} - ) - await client.call_tool( - name="complex_operation", - arguments={"items": ["a", "b", "c"], "mode": "batch"}, - ) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.INFO): + async with Client(logging_server) as client: + await client.call_tool( + name="simple_operation", arguments={"data": "test_data"} + ) + await client.call_tool( + name="complex_operation", + arguments={"items": ["a", "b", "c"], "mode": "batch"}, + ) # Should have processing and completion logs for both operations assert remove_line_numbers(caplog.text) == snapshot("""\ @@ -324,7 +580,7 @@ INFO fastmcp.requests:logging.py:LINE_NUMBER Completed message: event=reques """Test that logging middleware captures failed operations.""" logging_server.add_middleware(LoggingMiddleware(methods=["tools/call"])) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(logging_server) as client: # This should fail and be logged with pytest.raises(Exception): @@ -351,17 +607,25 @@ INFO fastmcp.requests:logging.py:LINE_NUMBER Completed message: event=reques ) logging_server.add_middleware(middleware) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(logging_server) as client: await client.call_tool("simple_operation", {"data": "payload_test"}) log_text = caplog.text + # Remove client IDs from log text for consistent snapshots + import re + + log_text = re.sub(r"\[Client-[^\]]+\]", "[Client-XXXX]", log_text) + assert remove_line_numbers(log_text) == snapshot("""\ -INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of type CallToolRequest +DEBUG fastmcp.fastmcp.client.transports:transports.py:LINE_NUMBER Inferred transport: +DEBUG fastmcp.fastmcp.client.client:client.py:LINE_NUMBER [Client-XXXX] called call_tool: simple_operation +DEBUG fastmcp.fastmcp.server.server:server.py:LINE_NUMBER [LoggingTestServer] Handler called: list_tools +DEBUG fastmcp.fastmcp.server.server:server.py:LINE_NUMBER [LoggingTestServer] Handler called: call_tool simple_operation with {'data': 'payload_test'} INFO fastmcp.requests:logging.py:LINE_NUMBER Processing message: event=request_start timestamp=2023-01-01T00:00:00+00:00 method=tools/call type=request source=client payload={"_meta":null,"name":"simple_operation","arguments":{"data":"payload_test"}} payload_type=CallToolRequestParams INFO fastmcp.requests:logging.py:LINE_NUMBER Completed message: event=request_success timestamp=2023-01-01T00:00:00+00:00 method=tools/call type=request source=client -INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of type ListToolsRequest +DEBUG fastmcp.fastmcp.server.server:server.py:LINE_NUMBER [LoggingTestServer] Handler called: list_tools """) @@ -379,7 +643,7 @@ INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of logging_server.add_middleware(logging_middleware) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(logging_server) as client: await client.call_tool( name="simple_operation", arguments={"data": "json_test"} @@ -394,11 +658,19 @@ INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of assert len(log_lines) >= 2 # Should have start and success entries - assert remove_line_numbers(caplog.text) == snapshot("""\ -INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of type CallToolRequest + # Remove client IDs from log text for consistent snapshots + import re + + log_text = re.sub(r"\[Client-[^\]]+\]", "[Client-XXXX]", caplog.text) + + assert remove_line_numbers(log_text) == snapshot("""\ +DEBUG fastmcp.fastmcp.client.transports:transports.py:LINE_NUMBER Inferred transport: +DEBUG fastmcp.fastmcp.client.client:client.py:LINE_NUMBER [Client-XXXX] called call_tool: simple_operation +DEBUG fastmcp.fastmcp.server.server:server.py:LINE_NUMBER [LoggingTestServer] Handler called: list_tools +DEBUG fastmcp.fastmcp.server.server:server.py:LINE_NUMBER [LoggingTestServer] Handler called: call_tool simple_operation with {'data': 'json_test'} INFO fastmcp.structured:logging.py:LINE_NUMBER Processing message: {"event": "request_start", "timestamp": "2023-01-01T00:00:00+00:00", "method": "tools/call", "type": "request", "source": "client", "payload": "{\\"_meta\\":null,\\"name\\":\\"simple_operation\\",\\"arguments\\":{\\"data\\":\\"json_test\\"}}", "payload_type": "CallToolRequestParams"} INFO fastmcp.structured:logging.py:LINE_NUMBER Completed message: {"event": "request_success", "timestamp": "2023-01-01T00:00:00+00:00", "method": "tools/call", "type": "request", "source": "client"} -INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of type ListToolsRequest +DEBUG fastmcp.fastmcp.server.server:server.py:LINE_NUMBER [LoggingTestServer] Handler called: list_tools """) @@ -414,19 +686,26 @@ INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of logging_server.add_middleware(logging_middleware) - with caplog.at_level(logging.INFO): - async with Client(logging_server) as client: - with pytest.raises(Exception): - await client.call_tool( - "operation_with_error", {"should_fail": True} - ) + with caplog_for_fastmcp(caplog): + with caplog.at_level(logging.INFO): + async with Client(logging_server) as client: + with pytest.raises(Exception): + await client.call_tool( + "operation_with_error", {"should_fail": True} + ) - assert remove_line_numbers(caplog.text) == snapshot("""\ -INFO mcp.server.lowlevel.server:server.py:LINE_NUMBER Processing request of type CallToolRequest -INFO fastmcp.structured:logging.py:LINE_NUMBER Processing message: {"event": "request_start", "timestamp": "2023-01-01T00:00:00+00:00", "method": "tools/call", "type": "request", "source": "client"} -ERROR fastmcp.structured:logging.py:LINE_NUMBER Failed message: tools/call - Error calling tool 'operation_with_error': Operation failed intentionally + # Verify that the structured logging middleware properly logs errors + logs = caplog.text -""") + # The key assertion: structured logging middleware logged the error in JSON format + assert re.search( + r"fastmcp\.structured.*Failed message: tools/call.*Operation failed intentionally", + logs, + ) + + # Verify the error contains expected error type and message + assert "ValueError" in logs + assert "Operation failed intentionally" in logs async def test_logging_middleware_with_different_operations( self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture @@ -444,7 +723,7 @@ ERROR fastmcp.structured:logging.py:LINE_NUMBER Failed message: tools/call - ) ) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(logging_server) as client: # Test different operation types await client.call_tool("simple_operation", {"data": "test"}) diff --git a/tests/server/middleware/test_timing.py b/tests/server/middleware/test_timing.py index 999edf039..db726b13e 100644 --- a/tests/server/middleware/test_timing.py +++ b/tests/server/middleware/test_timing.py @@ -11,6 +11,7 @@ from fastmcp import FastMCP from fastmcp.client import Client from fastmcp.server.middleware.middleware import MiddlewareContext from fastmcp.server.middleware.timing import DetailedTimingMiddleware, TimingMiddleware +from fastmcp.utilities.tests import caplog_for_fastmcp @pytest.fixture @@ -47,7 +48,7 @@ class TestTimingMiddleware: """Test timing successful requests.""" middleware = TimingMiddleware() - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): result = await middleware.on_request(mock_context, mock_call_next) assert result == "test_result" @@ -60,7 +61,7 @@ class TestTimingMiddleware: middleware = TimingMiddleware() mock_call_next = AsyncMock(side_effect=ValueError("test error")) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): with pytest.raises(ValueError): await middleware.on_request(mock_context, mock_call_next) @@ -84,7 +85,7 @@ class TestDetailedTimingMiddleware: context.message.name = "test_tool" mock_call_next = AsyncMock(return_value="tool_result") - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): result = await middleware.on_call_tool(context, mock_call_next) assert result == "tool_result" @@ -97,7 +98,7 @@ class TestDetailedTimingMiddleware: context.message.uri = "test://resource" mock_call_next = AsyncMock(return_value="resource_result") - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): result = await middleware.on_read_resource(context, mock_call_next) assert result == "resource_result" @@ -110,7 +111,7 @@ class TestDetailedTimingMiddleware: context.message.name = "test_prompt" mock_call_next = AsyncMock(return_value="prompt_result") - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): result = await middleware.on_get_prompt(context, mock_call_next) assert result == "prompt_result" @@ -122,7 +123,7 @@ class TestDetailedTimingMiddleware: context = MagicMock() mock_call_next = AsyncMock(return_value="tools_result") - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): result = await middleware.on_list_tools(context, mock_call_next) assert result == "tools_result" @@ -135,7 +136,7 @@ class TestDetailedTimingMiddleware: context.message.name = "failing_tool" mock_call_next = AsyncMock(side_effect=RuntimeError("operation failed")) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): with pytest.raises(RuntimeError): await middleware.on_call_tool(context, mock_call_next) @@ -194,7 +195,7 @@ class TestTimingMiddlewareIntegration: """Test that timing middleware accurately measures tool execution times.""" timing_server.add_middleware(TimingMiddleware()) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(timing_server) as client: # Test instant task await client.call_tool("instant_task") @@ -225,7 +226,7 @@ class TestTimingMiddlewareIntegration: """Test that timing middleware measures time even for failed operations.""" timing_server.add_middleware(TimingMiddleware()) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(timing_server) as client: # This should fail but still be timed with pytest.raises(Exception): @@ -241,7 +242,7 @@ class TestTimingMiddlewareIntegration: """Test that detailed timing middleware provides operation-specific timing.""" timing_server.add_middleware(DetailedTimingMiddleware()) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(timing_server) as client: # Test tool call await client.call_tool("short_task") @@ -271,7 +272,7 @@ class TestTimingMiddlewareIntegration: """Test timing middleware with concurrent operations.""" timing_server.add_middleware(TimingMiddleware()) - with caplog.at_level(logging.INFO): + with caplog_for_fastmcp(caplog): async with Client(timing_server) as client: # Run multiple operations concurrently tasks = [ @@ -290,7 +291,7 @@ class TestTimingMiddlewareIntegration: len(timing_logs) >= 3 ) # At least 3 tool calls, may have additional list_tools calls - async def test_timing_middleware_custom_logger(self, timing_server): + async def test_timing_middleware_custom_logger(self, timing_server, caplog): """Test timing middleware with custom logger configuration.""" import io import logging diff --git a/tests/utilities/test_logging.py b/tests/utilities/test_logging.py index 30ea963e9..e6d8086fc 100644 --- a/tests/utilities/test_logging.py +++ b/tests/utilities/test_logging.py @@ -5,14 +5,14 @@ from fastmcp.utilities.logging import get_logger def test_logging_doesnt_affect_other_loggers(caplog): # set FastMCP loggers to CRITICAL and ensure other loggers still emit messages - original_level = logging.getLogger("FastMCP").getEffectiveLevel() + original_level = logging.getLogger("fastmcp").getEffectiveLevel() try: - logging.getLogger("FastMCP").setLevel(logging.CRITICAL) + logging.getLogger("fastmcp").setLevel(logging.CRITICAL) root_logger = logging.getLogger() app_logger = logging.getLogger("app") - fastmcp_logger = logging.getLogger("FastMCP") + fastmcp_logger = logging.getLogger("fastmcp") fastmcp_server_logger = get_logger("server") with caplog.at_level(logging.INFO): @@ -27,4 +27,4 @@ def test_logging_doesnt_affect_other_loggers(caplog): assert "--FASTMCP SERVER--" not in caplog.text finally: - logging.getLogger("FastMCP").setLevel(original_level) + logging.getLogger("fastmcp").setLevel(original_level)