π The fast, Pythonic way to build MCP servers and clients.
Add template support
Jeremiah Lowin55d7cd14886b
diff --git a/README.md b/README.mdindex 0c4b2b0a4..fa9f48e22 100644--- a/README.md+++ b/README.md@@ -4,13 +4,26 @@A fast, pythonic way to build Model Context Protocol (MCP) servers.-Anthropic's new [Model Context Protocol](https://modelcontextprotocol.io) is powerful way to give broadcast new functionality and context to LLMs. However, developing MCP servers can be cumbersome. FastMCP provides a simple, intuitive interface for creating MCP servers in Python.+Anthropic's new [Model Context Protocol](https://modelcontextprotocol.io) is a powerful way to give broadcast new functionality and context to LLMs. However, developing MCP servers can be cumbersome. FastMCP provides a simple, intuitive interface for creating MCP servers in Python.++## Table of Contents++- [FastMCP](#fastmcp)+ - [Table of Contents](#table-of-contents)+ - [Installation](#installation)+ - [Quick Start](#quick-start)+ - [Core Concepts](#core-concepts)+ - [Resources](#resources)+ - [Tools](#tools)+ - [Development](#development)+ - [Running the Dev Inspector](#running-the-dev-inspector)+ - [Installing in Claude](#installing-in-claude)+ - [License](#license)## InstallationMCP servers require you to use [uv](https://github.com/astral-sh/uv) as your dependency manager.-Install uv with brew:```bashbrew install uv@@ -22,8 +35,6 @@ Install FastMCP:uv pip install fastmcp```--## Quick StartHere's a simple example that exposes your desktop directory as a resource and provides a basic addition tool:@@ -50,35 +61,92 @@ if __name__ == "__main__":mcp.run()```-## Features+## Core Concepts++FastMCP makes it easy to expose two types of functionality to LLMs: Resources and Tools.### Resources-Resources are data sources that can be accessed by the LLM. They can be files, directories, or any other data source. Resources are defined using the `@resource` decorator:+Resources are data sources that can be accessed by the LLM. They're perfect for providing context like files, API responses, or database queries.++FastMCP provides a simple `@resource` decorator that handles both static and dynamic resources. While the MCP spec distinguishes between resources and templates, FastMCP automatically handles this distinction based on your function signature:```python[email protected]("file://config.json")+# Static resource[email protected]("resource://static")+def get_static() -> str:+ """Return static content"""+ return "Static content"++# Dynamic resource[email protected]("resource://{city}/weather")+def get_weather(city: str) -> str:+ """Get weather for a city"""+ return f"Weather for {city}"++# Multiple parameters are supported[email protected]("db://users/{user_id}/posts/{post_id}")+def get_user_post(user_id: int, post_id: int) -> dict:+ """Get a specific post by a user"""+ return {+ "user_id": user_id,+ "post_id": post_id,+ "content": "Post content..."+ }++# File resources[email protected]("file://config.json")def get_config() -> str:"""Read the config file"""return Path("config.json").read_text()```+Resources can return:+- Strings for text content+- Bytes for binary content+- Other types will be converted to JSON++When your resource URI includes parameters in curly braces (like `{city}`) and your function accepts matching arguments, FastMCP automatically sets up a template resource behind the scenes. This means you don't need to worry about the distinction between resources and templates in the MCP spec - just write your function, and FastMCP handles the rest.++> **Note**: If you're familiar with the MCP spec, you might notice that dynamic resources are implemented as templates under the hood. FastMCP simplifies this by providing a unified interface through the `@resource` decorator. This is similar to how web frameworks often unify GET and POST handlers under a single route decorator.++### Tools-Tools are functions that can be called by the LLM. They are defined using the `@tool` decorator:+Tools are functions that can be called by the LLM to perform actions. They're great for calculations, API calls, or any interactive functionality. Tools are defined using the `@tool` decorator:```python@mcp.tool()-def calculate(x: int, y: int) -> int:- """Perform a calculation"""- return x + y+def search_docs(query: str, max_results: int = 5) -> list[dict]:+ """Search documentation for relevant entries"""+ results = perform_search(query, limit=max_results)+ return [{"title": r.title, "excerpt": r.excerpt} for r in results]++def analyze_image(image_path: str) -> dict:+ """Analyze an image and return metadata"""+ from PIL import Image+ img = Image.open(image_path)+ return {+ "size": img.size,+ "mode": img.mode,+ "format": img.format+ }```+Tools support:+- Type hints for parameters+- Default values+- Async functions+- Return value conversion to JSON+## Development+FastMCP includes developer tools to make testing and debugging easier.+### Running the Dev Inspector-FastMCP includes a development server with the MCP Inspector for testing your server:+The MCP Inspector helps you test your server during development:```bash# Basic usage@@ -114,4 +182,6 @@ fastmcp install your_server.py --with pandas --with numpyfastmcp install your_server.py --with-editable . --with pandas --with numpy```+## License+Apache 2.0\ No newline at end of filediff --git a/src/fastmcp/resources.py b/src/fastmcp/resources.pyindex 5fd7454ab..b1649c9b5 100644--- a/src/fastmcp/resources.py+++ b/src/fastmcp/resources.py@@ -1,3 +1,4 @@+import inspectimport pydantic.jsonimport abcimport asyncio@@ -19,20 +20,30 @@ class Resource(BaseModel, abc.ABC):"""Base class for all resources."""uri: _BaseUrl = Field(description="URI of the resource")- name: str = Field(description="Name of the resource")- description: Optional[str] = Field(description="Description of the resource")- mime_type: Optional[str] = Field(description="MIME type of the resource content")+ name: str = Field(description="Name of the resource", default=None)+ description: Optional[str] = Field(+ description="Description of the resource", default=None+ )+ mime_type: str = Field(+ default="text/plain",+ description="MIME type of the resource content",+ pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",+ )@field_validator("name", mode="before")@classmethoddef set_default_name(cls, name: str | None, info) -> str:"""Set default name from URI if not provided."""- if name is not None:+ if name:return name# Extract everything after the protocol (e.g., "desktop" from "resource://desktop")uri = info.data.get("uri")if uri:- return str(uri).split("://", 1)[1]+ uri_str = str(uri)+ if "://" in uri_str:+ name = uri_str.split("://", 1)[1]+ if name:+ return nameraise ValueError("Either name or uri must be provided")@abc.abstractmethod@@ -40,14 +51,15 @@ class Resource(BaseModel, abc.ABC):"""Read the resource content."""pass+ model_config = {+ "validate_default": True,+ }+class TextResource(Resource):- """A resource containing text content."""+ """A resource that reads from a string."""text: str = Field(description="Text content of the resource")- mime_type: Optional[str] = Field(- default="text/plain", description="MIME type of the resource content"- )async def read(self) -> str:"""Read the text content."""@@ -55,25 +67,62 @@ class TextResource(Resource):class BinaryResource(Resource):- """A resource containing binary content."""+ """A resource that reads from bytes."""data: bytes = Field(description="Binary content of the resource")- mime_type: Optional[str] = Field(- default="application/octet-stream",- description="MIME type of the resource content",- )async def read(self) -> bytes:"""Read the binary content."""return self.data+class FunctionResource(Resource):+ """A resource that defers data loading by wrapping a function.++ The function is only called when the resource is read, allowing for lazy loading+ of potentially expensive data. This is particularly useful when listing resources,+ as the function won't be called until the resource is actually accessed.++ The function can return:+ - str for text content (default)+ - bytes for binary content+ - other types will be converted to JSON+ """++ func: Callable[[], Any] = Field(exclude=True)++ async def read(self) -> Union[str, bytes]:+ """Read the resource by calling the wrapped function."""+ try:+ result = self.func()+ if isinstance(result, Resource):+ return await result.read()+ if isinstance(result, bytes):+ return result+ if isinstance(result, str):+ return result+ try:+ return json.dumps(result, default=pydantic.json.pydantic_encoder)+ except TypeError:+ # If JSON serialization fails, try str()+ return str(result)+ except Exception as e:+ raise ValueError(f"Error reading resource {self.uri}: {e}")++class FileResource(Resource):- """A resource that reads from a file."""+ """A resource that reads from a file.++ Set is_binary=True to read file as binary data instead of text.+ """path: Path = Field(description="Path to the file")- mime_type: Optional[str] = Field(- default="application/octet-stream",+ is_binary: bool = Field(+ default=False,+ description="Whether to read the file as binary data",+ )+ mime_type: str = Field(+ default="text/plain",description="MIME type of the resource content",)@@ -87,17 +136,12 @@ class FileResource(Resource):async def read(self) -> Union[str, bytes]:"""Read the file content."""- if self.mime_type and self.mime_type.startswith("text/"):- return await self._read_text()- return await self._read_binary()-- async def _read_text(self) -> str:- """Read file as text."""- return await asyncio.to_thread(self.path.read_text)-- async def _read_binary(self) -> bytes:- """Read file as binary."""- return await asyncio.to_thread(self.path.read_bytes)+ try:+ if self.is_binary:+ return await asyncio.to_thread(self.path.read_bytes)+ return await asyncio.to_thread(self.path.read_text)+ except Exception as e:+ raise ValueError(f"Error reading file {self.path}: {e}")class HttpResource(Resource):@@ -180,7 +224,7 @@ class ResourceTemplate(BaseModel):description: Optional[str] = Field(description="Description of what the resource does")- mime_type: Optional[str] = Field(+ mime_type: str = Field(default="text/plain", description="MIME type of the resource content")func: Callable = Field(exclude=True)@@ -210,7 +254,6 @@ class ResourceTemplate(BaseModel):uri_template=uri_template,name=func_name,description=description or func.__doc__ or "",- mime_type=mime_type or "text/plain",func=func,parameters=parameters,)@@ -226,30 +269,20 @@ class ResourceTemplate(BaseModel):async def create_resource(self, uri: str, params: Dict[str, Any]) -> Resource:"""Create a resource from the template with the given parameters."""- result = await self.func(**params)-- if isinstance(result, bytes):- return BinaryResource(- uri=uri,- name=self.name,- description=self.description,- mime_type=self.mime_type,- data=result,- )+ try:+ # Call function and check if result is a coroutine+ result = self.func(**params)+ if inspect.iscoroutine(result):+ result = await result- else:- if not isinstance(result, str):- try:- result = json.dumps(result, default=pydantic.json.pydantic_encoder)- except Exception as e:- raise ValueError(f"Error converting result to JSON: {e}")- return TextResource(+ return FunctionResource(uri=uri,name=self.name,description=self.description,- mime_type=self.mime_type,- text=result,+ func=lambda: result, # Capture result in closure)+ except Exception as e:+ raise ValueError(f"Error creating resource from template: {e}")class ResourceManager:diff --git a/src/fastmcp/server.py b/src/fastmcp/server.pyindex 7f74b77f2..edd2d25c7 100644--- a/src/fastmcp/server.py+++ b/src/fastmcp/server.py@@ -4,6 +4,8 @@ import asyncioimport functoolsimport jsonfrom typing import Any, Callable, Optional, Sequence, Union, Literal+import inspect+import reimport pydantic.jsonfrom mcp.server import Server as MCPServer@@ -19,7 +21,11 @@ from pydantic_settings import BaseSettingsfrom pydantic.networks import _BaseUrlfrom .exceptions import ResourceError-from .resources import Resource, FunctionResource, ResourceManager+from .resources import (+ Resource,+ FunctionResource,+ ResourceManager,+)from .tools import ToolManager, Imagefrom .utilities.logging import get_logger, configure_logging@@ -138,7 +144,7 @@ class FastMCP:async def read_resource(self, uri: _BaseUrl) -> Union[str, bytes]:"""Read a resource by URI."""- resource = self._resource_manager.get_resource(uri)+ resource = await self._resource_manager.get_resource(uri)if not resource:raise ResourceError(f"Unknown resource: {uri}")@@ -193,9 +199,17 @@ class FastMCP:"""Decorator to register a function as a resource.The function will be called when the resource is read to generate its content.+ The function can return:+ - str for text content+ - bytes for binary content+ - other types will be converted to JSON++ If the URI contains parameters (e.g. "resource://{param}") or the function+ has parameters, it will be registered as a template resource.Args:- uri: URI for the resource (e.g. "resource://my-resource")+ uri: URI for the resource (e.g. "resource://my-resource" or "resource://{param}")+ name: Optional name for the resourcedescription: Optional description of the resourcemime_type: Optional MIME type for the resource@@ -203,6 +217,10 @@ class FastMCP:@server.resource("resource://my-resource")def get_data() -> str:return "Hello, world!"++ @server.resource("resource://{city}/weather")+ def get_weather(city: str) -> str:+ return f"Weather for {city}""""# Check if user passed function directly instead of calling decoratorif callable(uri):@@ -213,61 +231,42 @@ class FastMCP:def decorator(func: Callable) -> Callable:@functools.wraps(func)- def wrapper() -> Any:- return func()-- resource = FunctionResource(- uri=uri,- name=name,- description=description,- mime_type=mime_type or "text/plain",- func=wrapper,- )- self.add_resource(resource)- return wrapper+ def wrapper(*args: Any, **kwargs: Any) -> Any:+ return func(*args, **kwargs)- return decorator+ # Check if this should be a template+ has_uri_params = "{" in uri and "}" in uri+ has_func_params = bool(inspect.signature(func).parameters)- def template(- self,- uri_template: str,- *,- name: Optional[str] = None,- description: Optional[str] = None,- mime_type: Optional[str] = None,- ) -> Callable:- """Decorator to register a function as a resource template.+ if has_uri_params or has_func_params:+ # Validate that URI params match function params+ uri_params = set(re.findall(r"{(\w+)}", uri))+ func_params = set(inspect.signature(func).parameters.keys())- Args:- uri_template: URI template with parameters (e.g. "weather://{city}/current")- name: Optional name for the resource- description: Optional description of the resource- mime_type: Optional MIME type for the resource-- Example:- @server.template("weather://{city}/current")- def get_weather(city: str) -> str:- return f"Weather for {city}"- """- # Check if user passed function directly instead of calling decorator- if callable(uri_template):- raise TypeError(- "The @template decorator was used incorrectly. "- "Did you forget to call it? Use @template('uri_template') instead of @template"- )-- def decorator(func: Callable) -> Callable:- @functools.wraps(func)- def wrapper(*args: Any, **kwargs: Any) -> Any:- return func(*args, **kwargs)+ if uri_params != func_params:+ raise ValueError(+ f"Mismatch between URI parameters {uri_params} "+ f"and function parameters {func_params}"+ )- self._resource_manager.add_template(- wrapper,- uri_template=uri_template,- name=name,- description=description,- mime_type=mime_type or "text/plain",- )+ # Register as template+ self._resource_manager.add_template(+ wrapper,+ uri_template=uri,+ name=name,+ description=description,+ mime_type=mime_type or "text/plain",+ )+ else:+ # Register as regular resource+ resource = FunctionResource(+ uri=uri,+ name=name,+ description=description,+ mime_type=mime_type or "text/plain",+ func=wrapper,+ )+ self.add_resource(resource)return wrapperreturn decoratordiff --git a/tests/resources/test_file_resources.py b/tests/resources/test_file_resources.pyindex b9691929d..5b26abe82 100644--- a/tests/resources/test_file_resources.py+++ b/tests/resources/test_file_resources.py@@ -1,6 +1,6 @@import pytestfrom pathlib import Path-from tempfile import NamedTemporaryFile, TemporaryDirectory+from tempfile import NamedTemporaryFilefrom fastmcp.resources import FileResource@@ -22,20 +22,6 @@ def temp_file():pass # File was already deleted by the test-def temp_dir_with_files():- """Create a temporary directory with test files."""- with TemporaryDirectory() as d:- path = Path(d).resolve()- # Create some test files- (path / "file1.txt").write_text("content1")- (path / "file2.txt").write_text("content2")- (path / "subdir").mkdir()- (path / "subdir/file3.txt").write_text("content3")- (path / "test.json").write_text('{"key": "value"}')- yield path--class TestFileResource:"""Test FileResource functionality."""@@ -45,23 +31,14 @@ class TestFileResource:uri=f"file://{temp_file}",name="test",description="test file",- mime_type="text/plain",path=temp_file,)assert str(resource.uri) == f"file://{temp_file}"assert resource.name == "test"assert resource.description == "test file"- assert resource.mime_type == "text/plain"+ assert resource.mime_type == "text/plain" # defaultassert resource.path == temp_file-- def test_file_resource_relative_path_error(self):- """Test FileResource rejects relative paths."""- with pytest.raises(ValueError, match="Path must be absolute"):- FileResource(- uri="file://test.txt",- name="test",- path=Path("test.txt"),- )+ assert resource.is_binary is False # defaultdef test_file_resource_str_path_conversion(self, temp_file: Path):"""Test FileResource handles string paths."""@@ -73,8 +50,8 @@ class TestFileResource:assert isinstance(resource.path, Path)assert resource.path.is_absolute()- async def test_file_resource_read(self, temp_file: Path):- """Test reading a FileResource."""+ async def test_read_text_file(self, temp_file: Path):+ """Test reading a text file."""resource = FileResource(uri=f"file://{temp_file}",name="test",@@ -82,19 +59,42 @@ class TestFileResource:)content = await resource.read()assert content == "test content"+ assert resource.mime_type == "text/plain"- async def test_file_resource_read_missing_file(self, temp_file: Path):- """Test reading a non-existent file."""- temp_file.unlink()+ async def test_read_binary_file(self, temp_file: Path):+ """Test reading a file as binary."""resource = FileResource(uri=f"file://{temp_file}",name="test",path=temp_file,+ is_binary=True,+ )+ content = await resource.read()+ assert isinstance(content, bytes)+ assert content == b"test content"++ def test_relative_path_error(self):+ """Test error on relative path."""+ with pytest.raises(ValueError, match="Path must be absolute"):+ FileResource(+ uri="file:///test.txt",+ name="test",+ path=Path("test.txt"),+ )++ async def test_missing_file_error(self, temp_file: Path):+ """Test error when file doesn't exist."""+ # Create path to non-existent file+ missing = temp_file.parent / "missing.txt"+ resource = FileResource(+ uri="file:///missing.txt",+ name="test",+ path=missing,)- with pytest.raises(FileNotFoundError):+ with pytest.raises(ValueError, match="Error reading file"):await resource.read()- async def test_file_resource_read_permission_error(self, temp_file: Path):+ async def test_permission_error(self, temp_file: Path):"""Test reading a file without permissions."""temp_file.chmod(0o000) # Remove all permissionstry:@@ -103,7 +103,7 @@ class TestFileResource:name="test",path=temp_file,)- with pytest.raises(PermissionError):+ with pytest.raises(ValueError, match="Error reading file"):await resource.read()finally:temp_file.chmod(0o644) # Restore permissionsdiff --git a/tests/resources/test_function_resources.py b/tests/resources/test_function_resources.pyindex 7de95a0c6..d9333849f 100644--- a/tests/resources/test_function_resources.py+++ b/tests/resources/test_function_resources.py@@ -1,3 +1,4 @@+import pytestfrom fastmcp.resources import FunctionResource@@ -7,32 +8,92 @@ class TestFunctionResource:def test_function_resource_creation(self):"""Test creating a FunctionResource."""- def my_func(x: str = "") -> str:- return f"Content: {x}"+ def my_func() -> str:+ return "test content"resource = FunctionResource(uri="fn://test",name="test",description="test function",- mime_type="text/plain",func=my_func,)assert str(resource.uri) == "fn://test"assert resource.name == "test"assert resource.description == "test function"- assert resource.mime_type == "text/plain"+ assert resource.mime_type == "text/plain" # defaultassert resource.func == my_func- async def test_function_resource_read(self):- """Test reading a FunctionResource with no parameters."""+ async def test_read_text(self):+ """Test reading text from a FunctionResource."""- def my_func() -> str:- return "test content"+ def get_data() -> str:+ return "Hello, world!"resource = FunctionResource(- uri="fn://test",+ uri="function://test",name="test",- func=my_func,+ func=get_data,+ )+ content = await resource.read()+ assert content == "Hello, world!"+ assert resource.mime_type == "text/plain"++ async def test_read_binary(self):+ """Test reading binary data from a FunctionResource."""++ def get_data() -> bytes:+ return b"Hello, world!"++ resource = FunctionResource(+ uri="function://test",+ name="test",+ func=get_data,+ )+ content = await resource.read()+ assert content == b"Hello, world!"++ async def test_json_conversion(self):+ """Test automatic JSON conversion of non-string results."""++ def get_data() -> dict:+ return {"key": "value"}++ resource = FunctionResource(+ uri="function://test",+ name="test",+ func=get_data,+ )+ content = await resource.read()+ assert '"key": "value"' in content++ async def test_error_handling(self):+ """Test error handling in FunctionResource."""++ def failing_func() -> str:+ raise ValueError("Test error")++ resource = FunctionResource(+ uri="function://test",+ name="test",+ func=failing_func,+ )+ with pytest.raises(ValueError, match="Error reading resource function://test"):+ await resource.read()++ async def test_custom_type_conversion(self):+ """Test handling of custom types."""++ class CustomData:+ def __str__(self) -> str:+ return "custom data"++ def get_data() -> CustomData:+ return CustomData()++ resource = FunctionResource(+ uri="function://test",+ name="test",+ func=get_data,)content = await resource.read()- assert content == "test content"+ assert isinstance(content, str)diff --git a/tests/resources/test_resource_manager.py b/tests/resources/test_resource_manager.pyindex 4bcc8de0c..c63b85935 100644--- a/tests/resources/test_resource_manager.py+++ b/tests/resources/test_resource_manager.py@@ -1,14 +1,11 @@-import loggingimport pytestfrom pathlib import Path-from tempfile import NamedTemporaryFile, TemporaryDirectory+from tempfile import NamedTemporaryFilefrom fastmcp.resources import (FileResource,FunctionResource,ResourceManager,- TextResource,- BinaryResource,ResourceTemplate,)@@ -30,396 +27,69 @@ def temp_file():pass # File was already deleted by the test-def temp_file_no_cleanup():- """Create a temporary file for testing.-- File is NOT automatically cleaned up - tests must handle cleanup.- """- content = "test content"- with NamedTemporaryFile(mode="w", delete=False) as f:- f.write(content)- path = Path(f.name).resolve()- return path---def temp_dir():- """Create a temporary directory for testing."""- with TemporaryDirectory() as d:- yield Path(d).resolve()+class TestResourceManager:+ """Test ResourceManager functionality."""--class TestResourceValidation:- def test_resource_uri_validation(self):- def dummy_func() -> str:- return "data"-- # Valid URI- resource = FunctionResource(- uri="http://example.com/data",- name="test",- func=dummy_func,- )- assert str(resource.uri) == "http://example.com/data"-- # Missing protocol- with pytest.raises(ValueError, match="Input should be a valid URL"):- FunctionResource(- uri="invalid",- name="test",- func=dummy_func,- )-- # Missing host- with pytest.raises(ValueError, match="Input should be a valid URL"):- FunctionResource(- uri="http://",- name="test",- func=dummy_func,- )---class TestResourceManagerAdd:- """Test ResourceManager add functionality."""-- def test_add_file_resource(self, temp_file: Path):- """Test adding a file resource."""+ def test_add_resource(self, temp_file: Path):+ """Test adding a resource."""manager = ResourceManager()resource = FileResource(uri=f"file://{temp_file}",name="test",- description="test file",- mime_type="text/plain",path=temp_file,)added = manager.add_resource(resource)- assert isinstance(added, FileResource)- assert str(added.uri) == f"file://{temp_file}"- assert added.name == "test"- assert added.description == "test file"- assert added.mime_type == "text/plain"- assert added.path == temp_file-- def test_add_file_resource_relative_path_error(self):- """Test ResourceManager rejects relative paths."""- with pytest.raises(ValueError, match="Path must be absolute"):- FileResource(- uri="file:///test.txt",- name="test",- path=Path("test.txt"),- )-- def test_warn_on_duplicate_resources(self, caplog):- """Test warning on duplicate resources."""- caplog.set_level(logging.WARNING, logger="mcp")- manager = ResourceManager()- resource = FileResource(- uri="file:///test.txt",- name="test",- path=Path("/test.txt"),- )- manager.add_resource(resource)- manager.add_resource(resource)- assert "Resource already exists: file:///test.txt" in caplog.text-- def test_disable_warn_on_duplicate_resources(self, caplog):- """Test disabling warning on duplicate resources."""- caplog.set_level(logging.WARNING, logger="mcp")- manager = ResourceManager()- resource = FileResource(- uri="file:///test.txt",- name="test",- path=Path("/test.txt"),- )- manager.add_resource(resource)- manager.warn_on_duplicate_resources = False- manager.add_resource(resource)- assert "Resource already exists: file:///test.txt" not in caplog.text---class TestResourceManagerRead:- """Test ResourceManager read functionality."""+ assert added == resource+ assert manager.list_resources() == [resource]- def test_get_resource_unknown_uri(self):- """Test getting a non-existent resource."""- manager = ResourceManager()- with pytest.raises(ValueError, match="Unknown resource"):- manager.get_resource("file://unknown")-- def test_get_resource(self, temp_file: Path):- """Test getting a resource by URI."""+ def test_add_duplicate_resource(self, temp_file: Path):+ """Test adding the same resource twice."""manager = ResourceManager()resource = FileResource(uri=f"file://{temp_file}",name="test",path=temp_file,)- added = manager.add_resource(resource)- retrieved = manager.get_resource(added.uri)- assert retrieved == added+ first = manager.add_resource(resource)+ second = manager.add_resource(resource)+ assert first == second+ assert manager.list_resources() == [resource]- async def test_resource_read_through_manager(self, temp_file: Path):- """Test reading a resource through the manager."""+ def test_warn_on_duplicate_resources(self, temp_file: Path, caplog):+ """Test warning on duplicate resources."""manager = ResourceManager()resource = FileResource(uri=f"file://{temp_file}",name="test",path=temp_file,)- added = manager.add_resource(resource)- retrieved = manager.get_resource(added.uri)- assert retrieved is not None- content = await retrieved.read()- assert content == "test content"-- async def test_resource_read_error_through_manager(- self, temp_file_no_cleanup: Path- ):- """Test error handling when reading through manager."""- manager = ResourceManager()- # Create resource while file exists- resource = FileResource(- uri=f"file://{temp_file_no_cleanup}",- name="test",- path=temp_file_no_cleanup,- )- added = manager.add_resource(resource)- retrieved = manager.get_resource(added.uri)- assert retrieved is not None-- # Delete file and verify read fails- temp_file_no_cleanup.unlink()- with pytest.raises(FileNotFoundError):- await retrieved.read()---class TestResourceManagerList:- """Test ResourceManager list functionality."""+ manager.add_resource(resource)+ manager.add_resource(resource)+ assert "Resource already exists" in caplog.text- def test_list_resources(self, temp_file: Path):- """Test listing all resources."""- manager = ResourceManager()+ def test_disable_warn_on_duplicate_resources(self, temp_file: Path, caplog):+ """Test disabling warning on duplicate resources."""+ manager = ResourceManager(warn_on_duplicate_resources=False)resource = FileResource(uri=f"file://{temp_file}",name="test",path=temp_file,)- added = manager.add_resource(resource)- resources = manager.list_resources()- assert len(resources) == 1- assert resources[0] == added+ manager.add_resource(resource)+ manager.add_resource(resource)+ assert "Resource already exists" not in caplog.text- def test_list_resources_duplicate(self, temp_file: Path):- """Test that adding the same resource twice only stores it once."""+ async def test_get_resource(self, temp_file: Path):+ """Test getting a resource by URI."""manager = ResourceManager()resource = FileResource(uri=f"file://{temp_file}",name="test",path=temp_file,)- resource1 = manager.add_resource(resource)- resource2 = manager.add_resource(resource)-- resources = manager.list_resources()- assert len(resources) == 1- assert resources[0] == resource1- assert resource1 == resource2-- def test_list_multiple_resources(self, temp_file: Path, temp_file_no_cleanup: Path):- """Test listing multiple different resources."""- manager = ResourceManager()- resource1 = FileResource(- uri=f"file://{temp_file}",- name="test1",- path=temp_file,- )- resource2 = FileResource(- uri=f"file://{temp_file_no_cleanup}",- name="test2",- path=temp_file_no_cleanup,- )- added1 = manager.add_resource(resource1)- added2 = manager.add_resource(resource2)-- resources = manager.list_resources()- assert len(resources) == 2- assert resources[0] == added1- assert resources[1] == added2- assert added1 != added2---class TestTextResource:- """Test TextResource functionality."""-- async def test_text_resource_read(self):- """Test reading from a TextResource."""- resource = TextResource(- uri="text://test",- name="test",- text="Hello, world!",- )- content = await resource.read()- assert content == "Hello, world!"- assert resource.mime_type == "text/plain"-- def test_text_resource_custom_mime(self):- """Test TextResource with custom mime type."""- resource = TextResource(- uri="text://test",- name="test",- text="<html></html>",- mime_type="text/html",- )- assert resource.mime_type == "text/html"---class TestBinaryResource:- """Test BinaryResource functionality."""-- async def test_binary_resource_read(self):- """Test reading from a BinaryResource."""- data = b"Hello, world!"- resource = BinaryResource(- uri="binary://test",- name="test",- data=data,- )- content = await resource.read()- assert content == data- assert resource.mime_type == "application/octet-stream"-- def test_binary_resource_custom_mime(self):- """Test BinaryResource with custom mime type."""- resource = BinaryResource(- uri="binary://test",- name="test",- data=b"test",- mime_type="image/png",- )- assert resource.mime_type == "image/png"---class TestResourceTemplate:- """Test ResourceTemplate functionality."""-- def test_template_from_function(self):- """Test creating a template from a function."""-- def weather(city: str, units: str = "metric") -> str:- return f"Weather in {city} ({units})"-- template = ResourceTemplate.from_function(- func=weather,- uri_template="weather://{city}/current",- name="weather",- description="Get current weather",- mime_type="text/plain",- )-- assert template.name == "weather"- assert template.uri_template == "weather://{city}/current"- assert template.mime_type == "text/plain"- assert "city" in template.parameters["properties"]-- def test_template_from_lambda_error(self):- """Test error when creating template from lambda without name."""- with pytest.raises(- ValueError, match="You must provide a name for lambda functions"- ):- ResourceTemplate.from_function(- func=lambda x: x,- uri_template="test://{x}",- )-- def test_template_matches(self):- """Test URI matching against template."""-- def dummy(x: str) -> str:- return x-- template = ResourceTemplate.from_function(- func=dummy,- uri_template="test://{x}/value",- name="test",- )-- # Test matching URI- params = template.matches("test://hello/value")- assert params == {"x": "hello"}-- # Test non-matching URI- params = template.matches("test://hello/wrong")- assert params is None-- async def test_template_create_text_resource(self):- """Test creating a TextResource from template."""-- def greet(name: str) -> str:- return f"Hello, {name}!"-- template = ResourceTemplate.from_function(- func=greet,- uri_template="greet://{name}",- name="greeter",- )-- resource = await template.create_resource(- "greet://world",- {"name": "world"},- )-- assert isinstance(resource, TextResource)- content = await resource.read()- assert content == "Hello, world!"-- async def test_template_create_binary_resource(self):- """Test creating a BinaryResource from template."""-- def get_bytes(value: str) -> bytes:- return value.encode()-- template = ResourceTemplate.from_function(- func=get_bytes,- uri_template="bytes://{value}",- name="bytes",- mime_type="application/octet-stream",- )-- resource = await template.create_resource(- "bytes://test",- {"value": "test"},- )-- assert isinstance(resource, BinaryResource)- content = await resource.read()- assert content == b"test"-- async def test_template_json_conversion(self):- """Test automatic JSON conversion of non-string/bytes results."""-- def get_data(key: str) -> dict:- return {"key": key, "value": 123}-- template = ResourceTemplate.from_function(- func=get_data,- uri_template="data://{key}",- name="data",- )-- resource = await template.create_resource(- "data://test",- {"key": "test"},- )-- assert isinstance(resource, TextResource)- content = await resource.read()- assert '"key": "test"' in content- assert '"value": 123' in content---class TestResourceManagerWithTemplates:- """Test ResourceManager template functionality."""+ manager.add_resource(resource)+ retrieved = await manager.get_resource(resource.uri)+ assert retrieved == resourceasync def test_get_resource_from_template(self):"""Test getting a resource through a template."""@@ -436,23 +106,31 @@ class TestResourceManagerWithTemplates:manager._templates[template.uri_template] = templateresource = await manager.get_resource("greet://world")- assert isinstance(resource, TextResource)+ assert isinstance(resource, FunctionResource)content = await resource.read()assert content == "Hello, world!"- async def test_template_error_handling(self):- """Test error handling in template resource creation."""+ async def test_get_unknown_resource(self):+ """Test getting a non-existent resource."""manager = ResourceManager()+ with pytest.raises(ValueError, match="Unknown resource"):+ await manager.get_resource("unknown://test")- def failing_func(x: str) -> str:- raise ValueError("Test error")-- template = ResourceTemplate.from_function(- func=failing_func,- uri_template="fail://{x}",- name="fail",+ def test_list_resources(self, temp_file: Path):+ """Test listing all resources."""+ manager = ResourceManager()+ resource1 = FileResource(+ uri=f"file://{temp_file}",+ name="test1",+ path=temp_file,)- manager._templates[template.uri_template] = template-- with pytest.raises(ValueError, match="Error creating resource from template"):- await manager.get_resource("fail://test")+ resource2 = FileResource(+ uri=f"file://{temp_file}2",+ name="test2",+ path=temp_file,+ )+ manager.add_resource(resource1)+ manager.add_resource(resource2)+ resources = manager.list_resources()+ assert len(resources) == 2+ assert resources == [resource1, resource2]diff --git a/tests/resources/test_resource_template.py b/tests/resources/test_resource_template.pynew file mode 100644index 000000000..0f72e9a85--- /dev/null+++ b/tests/resources/test_resource_template.py@@ -0,0 +1,238 @@+import pytest+from fastmcp.resources import ResourceTemplate, FunctionResource+++class TestResourceTemplate:+ """Test ResourceTemplate functionality."""++ def test_template_from_function(self):+ """Test creating a template from a function."""++ def weather(city: str, units: str = "metric") -> str:+ return f"Weather in {city} ({units})"++ template = ResourceTemplate.from_function(+ func=weather,+ uri_template="weather://{city}/current",+ name="weather",+ description="Get current weather",+ )++ assert template.name == "weather"+ assert template.uri_template == "weather://{city}/current"+ assert template.mime_type == "text/plain"+ assert "city" in template.parameters["properties"]++ def test_template_from_lambda_error(self):+ """Test error when creating template from lambda without name."""+ with pytest.raises(+ ValueError, match="You must provide a name for lambda functions"+ ):+ ResourceTemplate.from_function(+ func=lambda x: x,+ uri_template="test://{x}",+ )++ def test_template_matches(self):+ """Test URI matching against template."""++ def dummy(x: str) -> str:+ return x++ template = ResourceTemplate.from_function(+ func=dummy,+ uri_template="test://{x}/value",+ name="test",+ )++ # Test matching URI+ params = template.matches("test://hello/value")+ assert params == {"x": "hello"}++ # Test non-matching URI+ params = template.matches("test://hello/wrong")+ assert params is None++ async def test_create_text_resource(self):+ """Test creating a text resource from template."""++ def greet(name: str) -> str:+ return f"Hello, {name}!"++ template = ResourceTemplate.from_function(+ func=greet,+ uri_template="greet://{name}",+ name="greeter",+ )++ resource = await template.create_resource(+ "greet://world",+ {"name": "world"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert content == "Hello, world!"++ async def test_create_binary_resource(self):+ """Test creating a binary resource from template."""++ def get_bytes(value: str) -> bytes:+ return value.encode()++ template = ResourceTemplate.from_function(+ func=get_bytes,+ uri_template="bytes://{value}",+ name="bytes",+ )++ resource = await template.create_resource(+ "bytes://test",+ {"value": "test"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert content == b"test"++ async def test_json_conversion(self):+ """Test automatic JSON conversion of non-string/bytes results."""++ def get_data(key: str) -> dict:+ return {"key": key, "value": 123}++ template = ResourceTemplate.from_function(+ func=get_data,+ uri_template="data://{key}",+ name="data",+ )++ resource = await template.create_resource(+ "data://test",+ {"key": "test"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert '"key": "test"' in content+ assert '"value": 123' in content++ async def test_template_error(self):+ """Test error handling in template resource creation."""++ def failing_func(x: str) -> str:+ raise ValueError("Test error")++ template = ResourceTemplate.from_function(+ func=failing_func,+ uri_template="fail://{x}",+ name="fail",+ )++ with pytest.raises(ValueError, match="Error creating resource from template"):+ await template.create_resource("fail://test", {"x": "test"})++ async def test_async_text_resource(self):+ """Test creating a text resource from async function."""++ async def greet(name: str) -> str:+ return f"Hello, {name}!"++ template = ResourceTemplate.from_function(+ func=greet,+ uri_template="greet://{name}",+ name="greeter",+ )++ resource = await template.create_resource(+ "greet://world",+ {"name": "world"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert content == "Hello, world!"++ async def test_async_binary_resource(self):+ """Test creating a binary resource from async function."""++ async def get_bytes(value: str) -> bytes:+ return value.encode()++ template = ResourceTemplate.from_function(+ func=get_bytes,+ uri_template="bytes://{value}",+ name="bytes",+ )++ resource = await template.create_resource(+ "bytes://test",+ {"value": "test"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert content == b"test"++ async def test_async_json_conversion(self):+ """Test automatic JSON conversion of async results."""++ async def get_data(key: str) -> dict:+ return {"key": key, "value": 123}++ template = ResourceTemplate.from_function(+ func=get_data,+ uri_template="data://{key}",+ name="data",+ )++ resource = await template.create_resource(+ "data://test",+ {"key": "test"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert '"key": "test"' in content+ assert '"value": 123' in content++ async def test_async_error(self):+ """Test error handling in async template."""++ async def failing_func(x: str) -> str:+ raise ValueError("Test error")++ template = ResourceTemplate.from_function(+ func=failing_func,+ uri_template="fail://{x}",+ name="fail",+ )++ with pytest.raises(+ ValueError, match="Error creating resource from template: Test error"+ ):+ await template.create_resource("fail://test", {"x": "test"})++ async def test_sync_returning_coroutine(self):+ """Test sync function that returns a coroutine."""++ async def async_helper(name: str) -> str:+ return f"Hello, {name}!"++ def get_greeting(name: str) -> str:+ return async_helper(name) # Returns coroutine++ template = ResourceTemplate.from_function(+ func=get_greeting,+ uri_template="greet://{name}",+ name="greeter",+ )++ resource = await template.create_resource(+ "greet://world",+ {"name": "world"},+ )++ assert isinstance(resource, FunctionResource)+ content = await resource.read()+ assert content == "Hello, world!"diff --git a/tests/resources/test_resources.py b/tests/resources/test_resources.pynew file mode 100644index 000000000..ffb92e099--- /dev/null+++ b/tests/resources/test_resources.py@@ -0,0 +1,98 @@+import pytest+from fastmcp.resources import Resource, FunctionResource+++class TestResourceValidation:+ """Test base Resource validation."""++ def test_resource_uri_validation(self):+ """Test URI validation."""++ def dummy_func() -> str:+ return "data"++ # Valid URI+ resource = FunctionResource(+ uri="http://example.com/data",+ name="test",+ func=dummy_func,+ )+ assert str(resource.uri) == "http://example.com/data"++ # Missing protocol+ with pytest.raises(ValueError, match="Input should be a valid URL"):+ FunctionResource(+ uri="invalid",+ name="test",+ func=dummy_func,+ )++ # Missing host+ with pytest.raises(ValueError, match="Input should be a valid URL"):+ FunctionResource(+ uri="http://",+ name="test",+ func=dummy_func,+ )++ def test_resource_name_from_uri(self):+ """Test name is extracted from URI if not provided."""++ def dummy_func() -> str:+ return "data"++ resource = FunctionResource(+ uri="resource://my-resource",+ func=dummy_func,+ )+ assert resource.name == "my-resource"++ def test_resource_name_validation(self):+ """Test name validation."""++ def dummy_func() -> str:+ return "data"++ # Must provide either name or URI+ with pytest.raises(ValueError, match="Either name or uri must be provided"):+ FunctionResource(+ func=dummy_func,+ )++ # Explicit name takes precedence over URI+ resource = FunctionResource(+ uri="resource://uri-name",+ name="explicit-name",+ func=dummy_func,+ )+ assert resource.name == "explicit-name"++ def test_resource_mime_type(self):+ """Test mime type handling."""++ def dummy_func() -> str:+ return "data"++ # Default mime type+ resource = FunctionResource(+ uri="resource://test",+ func=dummy_func,+ )+ assert resource.mime_type == "text/plain"++ # Custom mime type+ resource = FunctionResource(+ uri="resource://test",+ func=dummy_func,+ mime_type="application/json",+ )+ assert resource.mime_type == "application/json"++ async def test_resource_read_abstract(self):+ """Test that Resource.read() is abstract."""++ class ConcreteResource(Resource):+ pass++ with pytest.raises(TypeError, match="abstract method"):+ ConcreteResource(uri="test://test", name="test")diff --git a/tests/test_server.py b/tests/test_server.pyindex 0a491a2ee..a97405ce6 100644--- a/tests/test_server.py+++ b/tests/test_server.py@@ -38,11 +38,11 @@ class TestServer:async def test_add_resource_decorator(self):mcp = FastMCP()- @mcp.resource("r://data")+ @mcp.resource("r://{x}")def get_data(x: str) -> str:return f"Data: {x}"- assert len(mcp._resource_manager.list_resources()) == 1+ assert len(mcp._resource_manager._templates) == 1async def test_add_resource_decorator_incorrect_usage(self):mcp = FastMCP()@@ -264,3 +264,87 @@ class TestServerResources:result.contents[0].blob== base64.b64encode(b"Binary file data").decode())++ async def test_resource_with_params(self):+ """Test that a resource with function parameters is automatically a template"""+ mcp = FastMCP()++ with pytest.raises(ValueError, match="Mismatch between URI parameters"):++ @mcp.resource("resource://data")+ def get_data(param: str) -> str:+ return f"Data: {param}"++ async def test_resource_with_uri_params(self):+ """Test that a resource with URI parameters is automatically a template"""+ mcp = FastMCP()++ with pytest.raises(ValueError, match="Mismatch between URI parameters"):++ @mcp.resource("resource://{param}")+ def get_data() -> str:+ return "Data"++ async def test_resource_matching_params(self):+ """Test that a resource with matching URI and function parameters works"""+ mcp = FastMCP()++ @mcp.resource("resource://{name}/data")+ def get_data(name: str) -> str:+ return f"Data for {name}"++ async with client_session(mcp._mcp_server) as client:+ result = await client.read_resource("resource://test/data")+ assert result.contents[0].text == "Data for test"++ async def test_resource_mismatched_params(self):+ """Test that mismatched parameters raise an error"""+ mcp = FastMCP()++ with pytest.raises(ValueError, match="Mismatch between URI parameters"):++ @mcp.resource("resource://{name}/data")+ def get_data(user: str) -> str:+ return f"Data for {user}"++ async def test_resource_multiple_params(self):+ """Test that multiple parameters work correctly"""+ mcp = FastMCP()++ @mcp.resource("resource://{org}/{repo}/data")+ def get_data(org: str, repo: str) -> str:+ return f"Data for {org}/{repo}"++ async with client_session(mcp._mcp_server) as client:+ result = await client.read_resource("resource://cursor/fastmcp/data")+ assert result.contents[0].text == "Data for cursor/fastmcp"++ async def test_resource_no_params(self):+ """Test that a resource with no parameters works as a regular resource"""+ mcp = FastMCP()++ @mcp.resource("resource://static")+ def get_data() -> str:+ return "Static data"++ async with client_session(mcp._mcp_server) as client:+ result = await client.read_resource("resource://static")+ assert result.contents[0].text == "Static data"++ async def test_template_to_resource_conversion(self):+ """Test that templates are properly converted to resources when accessed"""+ mcp = FastMCP()++ @mcp.resource("resource://{name}/data")+ def get_data(name: str) -> str:+ return f"Data for {name}"++ # Should be registered as a template+ assert len(mcp._resource_manager._templates) == 1+ assert len(mcp._resource_manager.list_resources()) == 0++ # When accessed, should create a concrete resource+ resource = await mcp._resource_manager.get_resource("resource://test/data")+ assert isinstance(resource, FunctionResource)+ result = await resource.read()+ assert result == "Data for test"