Merge pull request #1281 from jlowin/meta-tag

docs/clients/prompts.mdx

@@ -25,8 +25,33 @@ async with client:
         print(f"Description: {prompt.description}")
         if prompt.arguments:
             print(f"Arguments: {[arg.name for arg in prompt.arguments]}")
+        # Access tags and other metadata
+        if hasattr(prompt, '_meta') and prompt._meta:
+            print(f"Tags: {prompt._meta.get('tags', [])}")
 ```
 
+### Filtering by Tags
+
+You can use the `meta` field to filter prompts based on their tags:
+
+```python
+async with client:
+    prompts = await client.list_prompts()
+    
+    # Filter prompts by tag
+    analysis_prompts = [
+        prompt for prompt in prompts 
+        if hasattr(prompt, '_meta') and prompt._meta and 
+           'analysis' in prompt._meta.get('tags', [])
+    ]
+    
+    print(f"Found {len(analysis_prompts)} analysis prompts")
+```
+
+<Note>
+The `_meta` field is part of the standard MCP specification, but the inclusion of tags within it is specific to FastMCP servers. Other MCP server implementations may not provide tags in their metadata.
+</Note>
+
 ## Using Prompts
 
 ### Basic Usage

docs/clients/resources.mdx

@@ -34,6 +34,9 @@ async with client:
         print(f"Name: {resource.name}")
         print(f"Description: {resource.description}")
         print(f"MIME Type: {resource.mimeType}")
+        # Access tags and other metadata
+        if hasattr(resource, '_meta') and resource._meta:
+            print(f"Tags: {resource._meta.get('tags', [])}")
 ```
 
 ### Resource Templates
@@ -49,8 +52,33 @@ async with client:
         print(f"Template URI: {template.uriTemplate}")
         print(f"Name: {template.name}")
         print(f"Description: {template.description}")
+        # Access tags and other metadata
+        if hasattr(template, '_meta') and template._meta:
+            print(f"Tags: {template._meta.get('tags', [])}")
 ```
 
+### Filtering by Tags
+
+You can use the `meta` field to filter resources based on their tags:
+
+```python
+async with client:
+    resources = await client.list_resources()
+    
+    # Filter resources by tag
+    config_resources = [
+        resource for resource in resources 
+        if hasattr(resource, '_meta') and resource._meta and 
+           'config' in resource._meta.get('tags', [])
+    ]
+    
+    print(f"Found {len(config_resources)} config resources")
+```
+
+<Note>
+The `_meta` field is part of the standard MCP specification, but the inclusion of tags within it is specific to FastMCP servers. Other MCP server implementations may not provide tags in their metadata.
+</Note>
+
 ## Reading Resources
 
 ### Static Resources

docs/clients/tools.mdx

@@ -25,8 +25,33 @@ async with client:
         print(f"Description: {tool.description}")
         if tool.inputSchema:
             print(f"Parameters: {tool.inputSchema}")
+        # Access tags and other metadata
+        if hasattr(tool, '_meta') and tool._meta:
+            print(f"Tags: {tool._meta.get('tags', [])}")
 ```
 
+### Filtering by Tags
+
+You can use the `meta` field to filter tools based on their tags:
+
+```python
+async with client:
+    tools = await client.list_tools()
+    
+    # Filter tools by tag
+    analysis_tools = [
+        tool for tool in tools 
+        if hasattr(tool, '_meta') and tool._meta and 
+           'analysis' in tool._meta.get('tags', [])
+    ]
+    
+    print(f"Found {len(analysis_tools)} analysis tools")
+```
+
+<Note>
+The `_meta` field is part of the standard MCP specification, but the inclusion of tags within it is specific to FastMCP servers. Other MCP server implementations may not provide tags in their metadata.
+</Note>
+
 ## Executing Tools
 
 ### Basic Execution

docs/integrations/openapi.mdx

@@ -332,6 +332,38 @@ mcp = FastMCP.from_openapi(
 )
 ```
 
+#### OpenAPI Tags in Client Meta
+
+FastMCP automatically includes OpenAPI tags from your specification in the component's metadata. These tags are available to MCP clients through the `_meta` field, allowing clients to filter and organize components based on the original OpenAPI tagging:
+
+<CodeGroup>
+```json {5} OpenAPI spec with tags
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "tags": ["users", "public"],
+        "operationId": "list_users",
+        "summary": "List all users"
+      }
+    }
+  }
+}
+```
+```python {6-8} Access OpenAPI tags in MCP client
+async with client:
+    tools = await client.list_tools()
+    for tool in tools:
+        if hasattr(tool, '_meta') and tool._meta:
+            # OpenAPI tags are now available!
+            openapi_tags = tool._meta.get('tags', [])
+            if 'users' in openapi_tags:
+                print(f"Found user-related tool: {tool.name}")
+```
+</CodeGroup>
+
+This makes it easy for clients to understand and organize API endpoints based on their original OpenAPI categorization.
+
 ### Advanced Customization
 
 <VersionBadge version="2.5.0" />

docs/servers/middleware.mdx

@@ -111,9 +111,9 @@ FastMCP middleware handles two types of operations differently:
 
 **Listing Operations** (`on_list_tools`, `on_list_resources`, `on_list_prompts`, etc.):
 - Middleware receives **FastMCP component objects** with full metadata
-- These objects include FastMCP-specific properties like `tags` that aren't part of the MCP specification
-- The result contains complete component information before it's converted to MCP format
-- Tags and other metadata are stripped when finally returned to the MCP client
+- These objects include FastMCP-specific properties like `tags` that can be accessed directly from the component
+- The result contains complete component information before it's converted to MCP format  
+- Tags are included in the component's `meta` field in the listing response returned to MCP clients
 
 **Execution Operations** (`on_call_tool`, `on_read_resource`, `on_get_prompt`):
 - Middleware runs **before** the component is executed
@@ -200,7 +200,7 @@ class ListingFilterMiddleware(Middleware):
         return filtered_tools
 ```
 
-This filtering happens before the components are converted to MCP format and returned to the client, so the tags (which are FastMCP-specific) are naturally stripped in the final response.
+This filtering happens before the components are converted to MCP format and returned to the client. Tags are accessible both during filtering and are included in the component's `meta` field in the final listing response.
 
 <Tip>
 When filtering components in listing operations, ensure you also prevent execution of filtered components in the corresponding execution hooks (`on_call_tool`, `on_read_resource`, `on_get_prompt`) to maintain consistency.

docs/servers/prompts.mdx

@@ -85,7 +85,7 @@ def data_analysis_prompt(
 </ParamField>
 
 <ParamField body="tags" type="set[str] | None">
-  A set of strings used to categorize the prompt. Clients might use tags to filter or group available prompts
+  A set of strings used to categorize the prompt. Clients might use tags to filter or group available prompts. Tags are available to clients in the prompt's `meta` field when the prompt is listed (via `list_prompts`)
 </ParamField>
 
 <ParamField body="enabled" type="bool" default="True">

docs/servers/resources.mdx

@@ -98,7 +98,7 @@ def get_application_status() -> dict:
 </ParamField>
 
 <ParamField body="tags" type="set[str] | None">
-  A set of strings for categorization, potentially used by clients for filtering
+  A set of strings for categorization, potentially used by clients for filtering. Tags are available to clients in the resource's `meta` field when the resource is listed (via `list_resources` or `list_resource_templates`)
 </ParamField>
 
 <ParamField body="enabled" type="bool" default="True">

docs/servers/tools.mdx

@@ -76,7 +76,7 @@ def search_products_implementation(query: str, category: str | None = None) -> l
 </ParamField>
 
 <ParamField body="tags" type="set[str] | None">
-  A set of strings to categorize the tool. Clients might use tags to filter or group available tools
+  A set of strings to categorize the tool. Clients might use tags to filter or group available tools. Tags are available to clients in the tool's `meta` field when the tool is listed (via `list_tools`)
 </ParamField>
 
 <ParamField body="enabled" type="bool" default="True">

justfile

@@ -12,7 +12,7 @@ typecheck:
 
 # Serve documentation locally
 docs:
-    cd docs && npx mint@latest dev
+    cd docs && npx --yes mint@latest dev
 
 # Generate API reference documentation for all modules
 api-ref-all:

src/fastmcp/prompts/prompt.py

@@ -100,6 +100,7 @@ class Prompt(FastMCPComponent, ABC):
             "description": self.description,
             "arguments": arguments,
             "title": self.title,
+            "_meta": self.get_meta(),
         }
         return MCPPrompt(**kwargs | overrides)
 

src/fastmcp/resources/resource.py

@@ -122,6 +122,7 @@ class Resource(FastMCPComponent, abc.ABC):
             "mimeType": self.mime_type,
             "title": self.title,
             "annotations": self.annotations,
+            "_meta": self.get_meta(),
         }
         return MCPResource(**kwargs | overrides)
 

src/fastmcp/resources/template.py

@@ -154,6 +154,7 @@ class ResourceTemplate(FastMCPComponent):
             "mimeType": self.mime_type,
             "title": self.title,
             "annotations": self.annotations,
+            "_meta": self.get_meta(),
         }
         return MCPResourceTemplate(**kwargs | overrides)
 

src/fastmcp/tools/tool.py

@@ -145,6 +145,7 @@ class Tool(FastMCPComponent):
             "outputSchema": self.output_schema,
             "annotations": self.annotations,
             "title": title,
+            "_meta": self.get_meta(),
         }
         return MCPTool(**kwargs | overrides)
 

src/fastmcp/utilities/components.py

@@ -36,7 +36,9 @@ class FastMCPComponent(FastMCPBaseModel):
         default_factory=set,
         description="Tags for the component.",
     )
-
+    meta: dict[str, Any] = Field(
+        default_factory=dict, description="Meta information about the prompt"
+    )
     enabled: bool = Field(
         default=True,
         description="Whether the component is enabled.",
@@ -58,6 +60,13 @@ class FastMCPComponent(FastMCPBaseModel):
         """
         return self._key or self.name
 
+    def get_meta(self) -> dict[str, Any]:
+        """Get the meta information about the component."""
+        if self.tags:
+            return {"tags": sorted(self.tags)} | self.meta
+        else:
+            return self.meta
+
     def with_key(self, key: str) -> Self:
         return self.model_copy(update={"_key": key})
 

tests/server/openapi/test_basic_functionality.py

@@ -97,7 +97,7 @@ class TestTools:
 
         assert tools[0].model_dump() == dict(
             name="create_user_users_post",
-            meta=None,
+            meta=dict(tags=["create", "users"]),
             title=None,
             annotations=None,
             description=IsStr(regex=r"^Create a new user\..*$", regex_flags=re.DOTALL),
@@ -122,7 +122,7 @@ class TestTools:
         )
         assert tools[1].model_dump() == dict(
             name="update_user_name_users",
-            meta=None,
+            meta=dict(tags=["update", "users"]),
             title=None,
             annotations=None,
             description=IsStr(

tests/server/test_server_interactions.py

@@ -268,6 +268,21 @@ class TestToolTags:
             result_2 = await client.call_tool("tool_2", {})
             assert result_2.data == 2
 
+    async def test_tags_in_meta(self):
+        mcp = FastMCP()
+
+        @mcp.tool(tags={"tool-example", "test-tool-tag"})
+        def sample_tool(x: int) -> int:
+            """A sample tool."""
+            return x * 2
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            tool = tools[0]
+            assert tool.meta is not None
+            assert set(tool.meta["tags"]) == {"tool-example", "test-tool-tag"}
+
 
 class TestToolReturnTypes:
     async def test_string(self):
@@ -1544,6 +1559,26 @@ class TestResourceTags:
             with pytest.raises(McpError, match="Unknown resource"):
                 await client.read_resource(AnyUrl("resource://1"))
 
+    async def test_tags_in_meta(self):
+        mcp = FastMCP()
+
+        @mcp.resource(
+            uri="test://resource", tags={"resource-example", "test-resource-tag"}
+        )
+        def sample_resource() -> str:
+            """A sample resource."""
+            return "resource content"
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            resource = resources[0]
+            assert resource.meta is not None
+            assert set(resource.meta["tags"]) == {
+                "resource-example",
+                "test-resource-tag",
+            }
+
 
 class TestResourceContext:
     async def test_resource_with_context_annotation_gets_context(self):
@@ -1972,6 +2007,26 @@ class TestResourceTemplatesTags:
             result = await client.read_resource("resource://2/x")
             assert result[0].text == "Template resource 2: x"  # type: ignore[attr-defined]
 
+    async def test_tags_in_meta(self):
+        mcp = FastMCP()
+
+        @mcp.resource(
+            "test://template/{id}", tags={"template-example", "test-template-tag"}
+        )
+        def sample_template(id: str) -> str:
+            """A sample resource template."""
+            return f"template content for {id}"
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+            assert len(templates) == 1
+            template = templates[0]
+            assert template.meta is not None
+            assert set(template.meta["tags"]) == {
+                "template-example",
+                "test-template-tag",
+            }
+
 
 class TestResourceTemplateContext:
     async def test_resource_template_context(self):
@@ -2339,6 +2394,20 @@ class TestPrompts:
         prompt = prompts_dict["sample_prompt"]
         assert prompt.tags == {"example", "test-tag"}
 
+    async def test_tags_in_meta(self):
+        mcp = FastMCP()
+
+        @mcp.prompt(tags={"example", "test-tag"})
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+            assert len(prompts) == 1
+            prompt = prompts[0]
+            assert prompt.meta is not None
+            assert set(prompt.meta["tags"]) == {"example", "test-tag"}
+
 
 class TestPromptEnabled:
     async def test_toggle_enabled(self):