Relevant source files

The following files were used as context for generating this wiki page: - [`src/mcp/server/fastmcp/resources/base.py`](https://github.com/Derek7552/python-sdk/blob/main/src/mcp/server/fastmcp/resources/base.py) - [`src/mcp/server/fastmcp/resources/resource_manager.py`](https://github.com/Derek7552/python-sdk/blob/main/src/mcp/server/fastmcp/resources/resource_manager.py) - [`examples/servers/simple-resource/mcp_simple_resource/server.py`](https://github.com/Derek7552/python-sdk/blob/main/examples/servers/simple-resource/mcp_simple_resource/server.py) - [`examples/snippets/servers/images.py`](https://github.com/Derek7552/python-sdk/blob/main/examples/snippets/servers/images.py) - [`tests/server/fastmcp/test_server.py`](https://github.com/Derek7552/python-sdk/blob/main/tests/server/fastmcp/test_server.py) - [`tests/server/fastmcp/servers/test_file_server.py`](https://github.com/Derek7552/python-sdk/blob/main/tests/server/fastmcp/servers/test_file_server.py) - [`tests/server/fastmcp/resources/test_function_resources.py`](https://github.com/Derek7552/python-sdk/blob/main/tests/server/fastmcp/resources/test_function_resources.py) - [`tests/server/fastmcp/resources/test_resource_manager.py`](https://github.com/Derek7552/python-sdk/blob/main/tests/server/fastmcp/resources/test_resource_manager.py) - [`tests/server/fastmcp/test_integration.py`](https://github.com/Derek7552/python-sdk/blob/main/tests/server/fastmcp/test_integration.py)

# FastMCP: Serving Resources The FastMCP framework provides a powerful system for exposing data and functionality to clients as "resources." These resources are identified by a URI and can be discovered, listed, and read by clients. This system is designed to be flexible, supporting everything from static files to dynamically generated content from Python functions. The core of the resource system revolves around the `ResourceManager`, which manages a collection of `Resource` objects. Developers can define resources using decorators on functions or by instantiating resource classes directly. The framework also supports resource templates, allowing for the creation of dynamic resources based on parameters in the URI. ## Core Components The resource system is comprised of several key classes that work together to register, manage, and serve resources. ### ResourceManager The `ResourceManager` is the central hub for all resources within a `FastMCP` server. It is responsible for registering, retrieving, and listing both static resources and resource templates. This diagram shows the main interactions with the `ResourceManager`. ```mermaid graph TD subgraph FastMCP Server RM[ResourceManager] end subgraph Client C[MCP Client] end subgraph Developer Code D[Developer] end D -- "mcp.add_resource(resource)"
"@mcp.resource(...)" --> RM C -- "list_resources()" --> RM RM -- "List[Resource]" --> C C -- "read_resource(uri)" --> RM RM -- "Finds or generates resource" --> R[Resource] R -- "read()" --> Content[Content] Content -- "ResourceContents" --> C ``` **Key Responsibilities:** * **Registration**: Adds `Resource` objects and `ResourceTemplate` objects to the server's registry. * **Listing**: Provides lists of available resources and resource templates to clients. * **Retrieval**: Fetches a specific resource by its URI. If the URI matches a template, it instantiates a concrete `Resource` object on the fly. * **Duplicate Handling**: By default, it logs a warning when a resource with an existing URI is added again. This can be disabled. Sources: [`src/mcp/server/fastmcp/resources/resource_manager.py`](), [`tests/server/fastmcp/resources/test_resource_manager.py:27-35, 80-87`]() ### Resource Types FastMCP provides several concrete `Resource` implementations. The two primary types are `FunctionResource` and `FileResource`. | Resource Type | Description | Primary Use Case | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `FunctionResource` | A resource whose content is generated by executing a Python function. The return value of the function becomes the resource's content. | Serving dynamic or computed data. | | `FileResource` | A resource that represents a file on the local filesystem. Reading the resource returns the contents of the file. | Serving static files like text, configs, or logs. | Sources: [`tests/server/fastmcp/resources/test_function_resources.py:10-23`](), [`tests/server/fastmcp/servers/test_file_server.py:38-52`]() This class diagram illustrates the basic structure of the resource classes. ```mermaid classDiagram class Resource { <> +uri: AnyUrl +name: str +description: str +title: str +mime_type: str +read() object } class FunctionResource { +fn: Callable +read() str | bytes } class FileResource { +path: Path +read() str | bytes } Resource <|-- FunctionResource Resource <|-- FileResource ``` Sources: [`src/mcp/server/fastmcp/resources/base.py`](), [`tests/server/fastmcp/resources/test_function_resources.py`](), [`tests/server/fastmcp/servers/test_file_server.py`]() ## Defining and Registering Resources The most common way to define a resource is by using the `@mcp.resource` decorator on a function. This automatically creates and registers a `FunctionResource`. ### Using the `@mcp.resource` Decorator The `@mcp.resource` decorator transforms a Python function into a discoverable resource. The URI for the resource is a required argument to the decorator. ```python # From tests/server/fastmcp/test_server.py:166-172 mcp = FastMCP() @mcp.resource("r://{x}") def get_data(x: str) -> str: return f"Data: {x}" ``` This registers a resource template. When a client requests `r://some_value`, the `get_data` function will be called with `x="some_value"`. It is crucial to use the decorator with parentheses, even if only the URI is provided. Incorrect usage will result in a `TypeError`. ```python # From tests/server/fastmcp/test_server.py:177-183 mcp = FastMCP() with pytest.raises(TypeError, match="The @resource decorator was used incorrectly"): @mcp.resource # Missing parentheses #type: ignore def get_data(x: str) -> str: return f"Data: {x}" ``` Sources: [`tests/server/fastmcp/test_server.py:164-183`]() ### FunctionResource In-Depth A `FunctionResource` is highly versatile in how it handles return types from the decorated function. * **`str`**: Returned as `text/plain` content. * **`bytes`**: Returned as binary content, typically `application/octet-stream` unless a `mime_type` is specified. * **`pydantic.BaseModel` or `dict`**: Automatically serialized to a JSON string and returned as `application/json`. * **Other types**: Converted to a string representation. The `FunctionResource` can wrap both synchronous and asynchronous functions. Sources: [`tests/server/fastmcp/resources/test_function_resources.py:26-66, 99-110`]() ### FileResource `FileResource` is used to expose a file from the server's filesystem. It can be instantiated and added to the `ResourceManager` manually. ```python # From tests/server/fastmcp/test_server.py:700-707 mcp = FastMCP() # Create a text file text_file = tmp_path / "test.txt" text_file.write_text("Hello from file!") resource = FileResource(uri=AnyUrl("file://test.txt"), name="test.txt", path=text_file) mcp.add_resource(resource) ``` The resource's content type is inferred from the file extension, but can be overridden by setting the `mime_type` parameter. Sources: [`tests/server/fastmcp/test_server.py:700-724`](), [`tests/server/fastmcp/servers/test_file_server.py:38-52`]() ## Resource Templates Resource templates allow for the creation of dynamic resources based on patterns in a URI. A template is defined by a URI containing placeholders, such as `resource://{org}/{repo}/data`. When a client requests a URI that matches a template, FastMCP: 1. Parses the parameters from the request URI (e.g., `org="cursor"` and `repo="fastmcp"`). 2. Finds the corresponding `ResourceTemplate`. 3. Instantiates a temporary `FunctionResource` by passing the parsed parameters to the template's function. 4. Calls the `read()` method on the new resource to generate the content. ### Defining a Template A resource template is created automatically when the `@mcp.resource` decorator is used with a URI containing placeholders. The names of the placeholders in the URI **must** match the names of the arguments in the decorated function. ```python # From tests/server/fastmcp/test_server.py:796-800 mcp = FastMCP() @mcp.resource("resource://{org}/{repo}/data") def get_data(org: str, repo: str) -> str: return f"Data for {org}/{repo}" ``` A `ValueError` will be raised if the URI parameters and function arguments do not match. Sources: [`tests/server/fastmcp/test_server.py:760-768, 794-800`]() ### Template Resolution Flow This diagram illustrates the process of a client reading a resource that matches a template. ```mermaid sequenceDiagram participant Client participant FastMCP as FastMCP Server participant ResourceManager participant FunctionResource as Temp Resource Client->>FastMCP: read_resource("resource://cursor/fastmcp/data") FastMCP->>ResourceManager: get_resource("resource://cursor/fastmcp/data") ResourceManager-->>FastMCP: Finds matching template "resource://{org}/{repo}/data" Note over ResourceManager: Instantiates FunctionResource with
fn=get_data, org="cursor", repo="fastmcp" FastMCP->>FunctionResource: read() FunctionResource-->>FastMCP: "Data for cursor/fastmcp" FastMCP-->>Client: ReadResourceResult(content="...") ``` Sources: [`tests/server/fastmcp/test_server.py:794-806`](), [`tests/server/fastmcp/resources/test_resource_manager.py:89-103`]() ## Client Interaction From a client's perspective, interacting with resources involves a few simple API calls. 1. **`initialize()`**: The client connects to the server and learns about its capabilities, including whether it supports resources. 2. **`list_resources()`**: The client requests a list of all available static resources. 3. **`list_resource_templates()`**: The client requests a list of all available resource templates. 4. **`read_resource(uri)`**: The client requests the content of a specific resource by its URI. This flow is demonstrated in integration tests, where a client connects to a server and reads various resources. ```python # Based on tests/server/fastmcp/test_integration.py:228-251 async with ClientSession(read, write) as session: # Test initialization result = await session.initialize() assert result.capabilities.resources is not None # Test document resource doc_content = await session.read_resource(AnyUrl("file://documents/readme")) assert isinstance(doc_content, ReadResourceResult) assert "Content of readme" in doc_content.contents[0].text # Test settings resource (from a function) settings_content = await session.read_resource(AnyUrl("config://settings")) settings_json = json.loads(settings_content.contents[0].text) assert settings_json["theme"] == "dark" ``` Sources: [`tests/server/fastmcp/test_integration.py:228-251`](), [`examples/servers/simple-resource/README.md`]() ## Summary The resource system in FastMCP is a cornerstone feature for exposing server-side data to clients. It provides a unified interface for accessing both static content (via `FileResource`) and dynamic content (via `FunctionResource`). The use of the `@mcp.resource` decorator simplifies the process of creating resources from Python functions, while resource templates offer a powerful mechanism for generating a wide range of dynamic content from a single function definition. This flexible and extensible system allows developers to easily integrate data sources into their MCP servers.