add support for resource metadata

Author: mat-octave

src/mcp/server/fastmcp/resources/base.py

@@ -1,7 +1,7 @@
 """Base classes and interfaces for FastMCP resources."""
 
 import abc
-from typing import Annotated
+from typing import Annotated, Any
 
 from pydantic import (
     AnyUrl,
@@ -32,6 +32,7 @@ class Resource(BaseModel, abc.ABC):
     )
     icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this resource")
     annotations: Annotations | None = Field(default=None, description="Optional annotations for the resource")
+    meta: dict[str, Any] | None = Field(default=None, description="Optional metadata for the resource")
 
     @field_validator("name", mode="before")
     @classmethod

src/mcp/server/fastmcp/resources/resource_manager.py

@@ -64,6 +64,7 @@ def add_template(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> ResourceTemplate:
         """Add a template from a function."""
         template = ResourceTemplate.from_function(
@@ -75,6 +76,7 @@ def add_template(
             mime_type=mime_type,
             icons=icons,
             annotations=annotations,
+            meta=meta,
         )
         self._templates[template.uri_template] = template
         return template

src/mcp/server/fastmcp/resources/templates.py

@@ -33,6 +33,7 @@ class ResourceTemplate(BaseModel):
     fn: Callable[..., Any] = Field(exclude=True)
     parameters: dict[str, Any] = Field(description="JSON schema for function parameters")
     context_kwarg: str | None = Field(None, description="Name of the kwarg that should receive context")
+    meta: dict[str, Any] | None = Field(default=None, description="Optional metadata for the resource template")
 
     @classmethod
     def from_function(
@@ -46,6 +47,7 @@ def from_function(
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
         context_kwarg: str | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> ResourceTemplate:
         """Create a template from a function."""
         func_name = name or fn.__name__
@@ -77,6 +79,7 @@ def from_function(
             fn=fn,
             parameters=parameters,
             context_kwarg=context_kwarg,
+            meta=meta,
         )
 
     def matches(self, uri: str) -> dict[str, Any] | None:
@@ -113,6 +116,7 @@ async def create_resource(
                 icons=self.icons,
                 annotations=self.annotations,
                 fn=lambda: result,  # Capture result in closure
+                meta=self.meta,
             )
         except Exception as e:
             raise ValueError(f"Error creating resource from template: {e}")

src/mcp/server/fastmcp/resources/types.py

@@ -83,6 +83,7 @@ def from_function(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> "FunctionResource":
         """Create a FunctionResource from a function."""
         func_name = name or fn.__name__
@@ -101,6 +102,7 @@ def from_function(
             fn=fn,
             icons=icons,
             annotations=annotations,
+            meta=meta,
         )
 
 

src/mcp/server/fastmcp/server.py

@@ -358,6 +358,7 @@ async def list_resources(self) -> list[MCPResource]:
                 mimeType=resource.mime_type,
                 icons=resource.icons,
                 annotations=resource.annotations,
+                _meta=resource.meta,
             )
             for resource in resources
         ]
@@ -373,6 +374,7 @@ async def list_resource_templates(self) -> list[MCPResourceTemplate]:
                 mimeType=template.mime_type,
                 icons=template.icons,
                 annotations=template.annotations,
+                _meta=template.meta,
             )
             for template in templates
         ]
@@ -539,6 +541,7 @@ def resource(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a function as a resource.
 
@@ -615,6 +618,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     mime_type=mime_type,
                     icons=icons,
                     annotations=annotations,
+                    meta=meta,
                 )
             else:
                 # Register as regular resource
@@ -627,6 +631,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     mime_type=mime_type,
                     icons=icons,
                     annotations=annotations,
+                    meta=meta,
                 )
                 self.add_resource(resource)
             return fn

tests/server/fastmcp/resources/test_function_resources.py

@@ -155,3 +155,23 @@ async def get_data() -> str:  # pragma: no cover
         assert resource.mime_type == "text/plain"
         assert resource.name == "test"
         assert resource.uri == AnyUrl("function://test")
+
+    @pytest.mark.anyio
+    def test_from_function_with_meta(self):
+        """Test creating a FunctionResource with metadata."""
+
+        async def get_data() -> str:  # pragma: no cover
+            return "Hello, world!"
+
+        meta = {"ui": {"type": "card"}, "version": "1.0"}
+
+        resource = FunctionResource.from_function(
+            fn=get_data,
+            uri="function://test",
+            name="test",
+            meta=meta,
+        )
+
+        assert resource.meta is not None
+        assert resource.meta == meta
+        assert resource.meta["ui"]["type"] == "card"

tests/server/fastmcp/resources/test_resource_template.py

@@ -258,3 +258,63 @@ def get_item(item_id: str) -> str:  # pragma: no cover
         # Verify the resource works correctly
         content = await resource.read()
         assert content == "Item 123"
+
+
+class TestResourceTemplateMeta:
+    """Test metadata on resource templates."""
+
+    def test_template_with_meta(self):
+        """Test creating a template with metadata."""
+
+        def get_user_data(user_id: str) -> str:  # pragma: no cover
+            return f"User {user_id}"
+
+        meta = {"ui": {"type": "card"}, "version": "1.0"}
+
+        template = ResourceTemplate.from_function(
+            fn=get_user_data, uri_template="resource://users/{user_id}", meta=meta
+        )
+
+        assert template.meta is not None
+        assert template.meta == meta
+
+    def test_template_without_meta(self):
+        """Test that metadata is optional for templates."""
+
+        def get_user_data(user_id: str) -> str:  # pragma: no cover
+            return f"User {user_id}"
+
+        template = ResourceTemplate.from_function(fn=get_user_data, uri_template="resource://users/{user_id}")
+
+        assert template.meta is None
+
+    @pytest.mark.anyio
+    async def test_template_meta_in_fastmcp(self):
+        """Test template metadata via FastMCP decorator."""
+
+        mcp = FastMCP()
+
+        @mcp.resource("resource://dynamic/{id}", meta={"category": "dynamic"})
+        def get_dynamic(id: str) -> str:  # pragma: no cover
+            return f"Data for {id}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].meta is not None
+        assert templates[0].meta == {"category": "dynamic"}
+
+    @pytest.mark.anyio
+    async def test_template_created_resources_inherit_meta(self):
+        """Test that resources created from templates inherit metadata."""
+
+        def get_item(item_id: str) -> str:  # pragma: no cover
+            return f"Item {item_id}"
+
+        meta = {"category": "items"}
+
+        template = ResourceTemplate.from_function(fn=get_item, uri_template="resource://items/{item_id}", meta=meta)
+
+        resource = await template.create_resource("resource://items/123", {"item_id": "123"})
+
+        assert resource.meta is not None
+        assert resource.meta == meta

tests/server/fastmcp/resources/test_resources.py

@@ -193,3 +193,64 @@ def test_audience_validation(self):
         # Invalid roles should raise validation error
         with pytest.raises(Exception):  # Pydantic validation error
             Annotations(audience=["invalid_role"])  # type: ignore
+
+
+class TestResourceMeta:
+    """Test metadata on resources."""
+
+    def test_resource_with_meta(self):
+        """Test creating a resource with metadata."""
+
+        def get_data() -> str:  # pragma: no cover
+            return "data"
+
+        meta = {"ui": {"type": "card"}, "category": "data"}
+
+        resource = FunctionResource.from_function(fn=get_data, uri="resource://test", meta=meta)
+
+        assert resource.meta is not None
+        assert resource.meta == meta
+
+    def test_resource_without_meta(self):
+        """Test that metadata is optional."""
+
+        def get_data() -> str:  # pragma: no cover
+            return "data"
+
+        resource = FunctionResource.from_function(fn=get_data, uri="resource://test")
+
+        assert resource.meta is None
+
+    @pytest.mark.anyio
+    async def test_resource_meta_in_fastmcp(self):
+        """Test resource metadata via FastMCP decorator."""
+
+        mcp = FastMCP()
+
+        @mcp.resource("resource://with-meta", meta={"category": "test", "version": "1.0"})
+        def get_with_meta() -> str:  # pragma: no cover
+            return "data with meta"
+
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+        assert resources[0].meta is not None
+        assert resources[0].meta == {"category": "test", "version": "1.0"}
+
+    @pytest.mark.anyio
+    async def test_resource_meta_with_annotations(self):
+        """Test that metadata and annotations can coexist."""
+
+        mcp = FastMCP()
+
+        meta = {"custom": "value"}
+        annotations = Annotations(audience=["user"], priority=0.8)
+
+        @mcp.resource("resource://combined", meta=meta, annotations=annotations)
+        def combined_resource() -> str:  # pragma: no cover
+            return "combined"
+
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+        assert resources[0].meta == meta
+        assert resources[0].annotations is not None
+        assert resources[0].annotations.audience == ["user"]