diff --git a/docs/servers/openapi.mdx b/docs/servers/openapi.mdx index ff7d6460c..1359ff51b 100644 --- a/docs/servers/openapi.mdx +++ b/docs/servers/openapi.mdx @@ -51,6 +51,7 @@ Each `RouteMap` specifies a combination of methods, patterns, and tags, as well - **Pattern**: Regex pattern to match the route path (e.g. `r"^/users/.*"` or `r".*"` for all) - **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags. - **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`) +- **MCP tags** A set of custom tags to add to components created from matching routes Here is FastMCP's default rule: @@ -206,9 +207,76 @@ mcp = FastMCP.from_openapi( ## Customizing MCP Components +### Tags + + + +FastMCP provides several ways to add tags to your MCP components, allowing you to categorize and organize them for better discoverability and filtering. Tags are combined from multiple sources to create the final set of tags on each component. + +#### RouteMap Tags + +You can add custom tags to components created from specific routes using the `mcp_tags` parameter in `RouteMap`. These tags will be applied to all components created from routes that match that particular route map. + +```python {12, 20, 28} +from fastmcp import FastMCP +from fastmcp.server.openapi import RouteMap, MCPType + +mcp = FastMCP.from_openapi( + ..., + route_maps=[ + # Add custom tags to all POST endpoints + RouteMap( + methods=["POST"], + pattern=r".*", + mcp_type=MCPType.TOOL, + mcp_tags={"write-operation", "api-mutation"} + ), + + # Add different tags to detail view endpoints + RouteMap( + methods=["GET"], + pattern=r".*\{.*\}.*", + mcp_type=MCPType.RESOURCE_TEMPLATE, + mcp_tags={"detail-view", "parameterized"} + ), + + # Add tags to list endpoints + RouteMap( + methods=["GET"], + pattern=r".*", + mcp_type=MCPType.RESOURCE, + mcp_tags={"list-data", "collection"} + ), + ], +) +``` + +#### Global Tags + +You can add tags to **all** components by providing a `tags` parameter when creating your FastMCP server with `from_openapi` or `from_fastapi`. These global tags will be applied to every component created from your OpenAPI specification. + + +```python {6} from_openapi() +from fastmcp import FastMCP + +mcp = FastMCP.from_openapi( + openapi_spec=spec, + client=client, + tags={"api-v2", "production", "external"} +) +``` +```python {5} from_fastapi() +from fastmcp import FastMCP + +mcp = FastMCP.from_fastapi( + app=app, + tags={"internal-api", "microservice"} +) +``` + -### Component Names +### Names @@ -421,10 +489,16 @@ mcp = FastMCP.from_fastapi( app=app, name="My Custom Server", timeout=5.0, + tags={"api-v1", "fastapi"}, # Global tags for all components mcp_names={"operationId": "friendly_name"}, # Custom component names route_maps=[ - # Admin endpoints become tools - RouteMap(methods="*", pattern=r"^/admin/.*", mcp_type=MCPType.TOOL), + # Admin endpoints become tools with custom tags + RouteMap( + methods="*", + pattern=r"^/admin/.*", + mcp_type=MCPType.TOOL, + mcp_tags={"admin", "privileged"} + ), # Internal endpoints are excluded RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"internal"}), ], diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.py index 7e245b4ec..7522942a7 100644 --- a/src/fastmcp/server/server.py +++ b/src/fastmcp/server/server.py @@ -121,7 +121,6 @@ class FastMCP(Generic[LifespanResultT]): ] | None ) = None, - tags: set[str] | None = None, tool_serializer: Callable[[Any], str] | None = None, cache_expiration_seconds: float | None = None, on_duplicate_tools: DuplicateBehavior | None = None, @@ -152,8 +151,6 @@ class FastMCP(Generic[LifespanResultT]): resource_prefix_format or fastmcp.settings.resource_prefix_format ) - self.tags: set[str] = tags or set() - self._cache = TimedCache( expiration=datetime.timedelta(seconds=cache_expiration_seconds or 0) ) @@ -1561,6 +1558,7 @@ class FastMCP(Generic[LifespanResultT]): route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, + tags: set[str] | None = None, **settings: Any, ) -> FastMCPOpenAPI: """ @@ -1575,6 +1573,7 @@ class FastMCP(Generic[LifespanResultT]): route_map_fn=route_map_fn, mcp_component_fn=mcp_component_fn, mcp_names=mcp_names, + tags=tags, **settings, ) @@ -1588,6 +1587,7 @@ class FastMCP(Generic[LifespanResultT]): mcp_component_fn: OpenAPIComponentFn | 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: """ @@ -1615,6 +1615,7 @@ class FastMCP(Generic[LifespanResultT]): route_map_fn=route_map_fn, mcp_component_fn=mcp_component_fn, mcp_names=mcp_names, + tags=tags, **settings, ) diff --git a/tests/deprecated/test_settings.py b/tests/deprecated/test_settings.py index c58ce183e..490b88c1a 100644 --- a/tests/deprecated/test_settings.py +++ b/tests/deprecated/test_settings.py @@ -175,7 +175,6 @@ class TestDeprecatedServerInitKwargs: server = FastMCP( name="TestServer", instructions="Test instructions", - tags={"test", "server"}, cache_expiration_seconds=60.0, on_duplicate_tools="warn", on_duplicate_resources="error", @@ -193,7 +192,6 @@ class TestDeprecatedServerInitKwargs: # Verify server was created successfully assert server.name == "TestServer" assert server.instructions == "Test instructions" - assert server.tags == {"test", "server"} def test_none_values_no_warnings(self): """Test that None values for deprecated kwargs don't raise warnings.""" diff --git a/tests/server/openapi/test_openapi.py b/tests/server/openapi/test_openapi.py index d0c66a593..366416975 100644 --- a/tests/server/openapi/test_openapi.py +++ b/tests/server/openapi/test_openapi.py @@ -2709,25 +2709,22 @@ class TestGlobalTagsParameter: ) # Check tool has both original and global tags - tools = server._tool_manager.list_tools() - create_item_tool = next((t for t in tools if "create_item" in t.name), None) - assert create_item_tool is not None + tools = await server.get_tools() + create_item_tool = tools["create_item_items_post"] assert "items" in create_item_tool.tags # Original OpenAPI tag assert "global" in create_item_tool.tags # Global tag assert "api-v1" in create_item_tool.tags # Global tag # Check resource has both original and global tags - resources = list(server._resource_manager.get_resources().values()) - get_items_resource = next((r for r in resources if "get_items" in r.name), None) - assert get_items_resource is not None + resources = await server.get_resources() + get_items_resource = resources["resource://get_items_items_get"] assert "items" in get_items_resource.tags # Original OpenAPI tag assert "global" in get_items_resource.tags # Global tag assert "api-v1" in get_items_resource.tags # Global tag # Check resource template has both original and global tags - templates = list(server._resource_manager.get_templates().values()) - get_item_template = next((t for t in templates if "get_item" in t.name), None) - assert get_item_template is not None + templates = await server.get_resource_templates() + get_item_template = templates["resource://get_item_items/{item_id}"] assert "items" in get_item_template.tags # Original OpenAPI tag assert "global" in get_item_template.tags # Global tag assert "api-v1" in get_item_template.tags # Global tag @@ -2754,25 +2751,22 @@ class TestGlobalTagsParameter: ) # Check tool has both original and global tags - tools = server._tool_manager.list_tools() - create_item_tool = next((t for t in tools if "create_item" in t.name), None) - assert create_item_tool is not None + tools = await server.get_tools() + create_item_tool = tools["create_item_items_post"] assert "items" in create_item_tool.tags # Original OpenAPI tag assert "openapi-global" in create_item_tool.tags # Global tag assert "service" in create_item_tool.tags # Global tag # Check resource has both original and global tags - resources = list(server._resource_manager.get_resources().values()) - get_items_resource = next((r for r in resources if "get_items" in r.name), None) - assert get_items_resource is not None + resources = await server.get_resources() + get_items_resource = resources["resource://get_items_items_get"] assert "items" in get_items_resource.tags # Original OpenAPI tag assert "openapi-global" in get_items_resource.tags # Global tag assert "service" in get_items_resource.tags # Global tag # Check resource template has both original and global tags - templates = list(server._resource_manager.get_templates().values()) - get_item_template = next((t for t in templates if "get_item" in t.name), None) - assert get_item_template is not None + templates = await server.get_resource_templates() + get_item_template = templates["resource://get_item_items/{item_id}"] assert "items" in get_item_template.tags # Original OpenAPI tag assert "openapi-global" in get_item_template.tags # Global tag assert "service" in get_item_template.tags # Global tag @@ -2800,17 +2794,15 @@ class TestGlobalTagsParameter: ) # Check that all three types of tags are present on the tool - tools = server._tool_manager.list_tools() - create_item_tool = next((t for t in tools if "create_item" in t.name), None) - assert create_item_tool is not None + tools = await server.get_tools() + create_item_tool = tools["create_item_items_post"] assert "items" in create_item_tool.tags # Original OpenAPI tag assert "global" in create_item_tool.tags # Global tag assert "route-specific" in create_item_tool.tags # RouteMap mcp_tag # Check that resource only has OpenAPI and global tags (no route-specific since different RouteMap) - resources = list(server._resource_manager.get_resources().values()) - get_items_resource = next((r for r in resources if "get_items" in r.name), None) - assert get_items_resource is not None + resources = await server.get_resources() + get_items_resource = resources["resource://get_items_items_get"] assert "items" in get_items_resource.tags # Original OpenAPI tag assert "global" in get_items_resource.tags # Global tag assert "route-specific" not in get_items_resource.tags # Not from this RouteMap