π The fast, Pythonic way to build MCP servers and clients.
Ensure that openapi tags are transferred to MCP objects
Jeremiah Lowin79190e40e932
diff --git a/src/fastmcp/server/openapi.py b/src/fastmcp/server/openapi.pyindex 19cac311d..d25dc314d 100644--- a/src/fastmcp/server/openapi.py+++ b/src/fastmcp/server/openapi.py@@ -115,6 +115,7 @@ class OpenAPITool(Tool):parameters: dict[str, Any],fn_metadata: Any,is_async: bool = True,+ tags: set[str] = set(),):super().__init__(name=name,@@ -124,6 +125,7 @@ class OpenAPITool(Tool):fn_metadata=fn_metadata,is_async=is_async,context_kwarg="context", # Default context keyword argument+ tags=tags,)self._client = clientself._route = route@@ -242,12 +244,14 @@ class OpenAPIResource(Resource):name: str,description: str,mime_type: str = "application/json",+ tags: set[str] = set(),):super().__init__(uri=AnyUrl(uri), # Convert string to AnyUrlname=name,description=description,mime_type=mime_type,+ tags=tags,)self._client = clientself._route = route@@ -332,6 +336,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):name: str,description: str,parameters: dict[str, Any],+ tags: set[str] = set(),):super().__init__(uri_template=uri_template,@@ -339,6 +344,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):description=description,fn=self._create_resource_fn,parameters=parameters,+ tags=tags,)self._client = clientself._route = route@@ -405,6 +411,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):description=self.descriptionor f"Resource for {self._route.path}", # Provide default if Nonemime_type="application/json", # Default, will be updated when read+ tags=set(self._route.tags or []),)@@ -525,10 +532,13 @@ class FastMCPOpenAPI(FastMCP):parameters=combined_schema,fn_metadata=func_metadata(_openapi_passthrough),is_async=True,+ tags=set(route.tags or []),)# Register the tool by directly assigning to the tools dictionaryself._tool_manager._tools[tool_name] = tool- logger.debug(f"Registered TOOL: {tool_name} ({route.method} {route.path})")+ logger.debug(+ f"Registered TOOL: {tool_name} ({route.method} {route.path}) with tags: {route.tags}"+ )def _create_openapi_resource(self, route: openapi.HTTPRoute, operation_id: str):"""Creates and registers an OpenAPIResource with enhanced description."""@@ -550,11 +560,12 @@ class FastMCPOpenAPI(FastMCP):uri=resource_uri,name=resource_name,description=enhanced_description,+ tags=set(route.tags or []),)# Register the resource by directly assigning to the resources dictionaryself._resource_manager._resources[str(resource.uri)] = resourcelogger.debug(- f"Registered RESOURCE: {resource_uri} ({route.method} {route.path})"+ f"Registered RESOURCE: {resource_uri} ({route.method} {route.path}) with tags: {route.tags}")def _create_openapi_template(self, route: openapi.HTTPRoute, operation_id: str):@@ -594,11 +605,12 @@ class FastMCPOpenAPI(FastMCP):name=template_name,description=enhanced_description,parameters=template_params_schema,+ tags=set(route.tags or []),)# Register the template by directly assigning to the templates dictionaryself._resource_manager._templates[uri_template_str] = templatelogger.debug(- f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path})"+ f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path}) with tags: {route.tags}")async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.pyindex fd50f2450..99e20f7bb 100644--- a/src/fastmcp/server/server.py+++ b/src/fastmcp/server/server.py@@ -78,8 +78,10 @@ class FastMCP(Generic[LifespanResultT]):lifespan: (Callable[["FastMCP"], AbstractAsyncContextManager[LifespanResultT]] | None) = None,+ tags: set[str] | None = None,**settings: Any,):+ self.tags: set[str] = tags or set()self.settings = fastmcp.settings.ServerSettings(**settings)self._mcp_server = MCPServer[LifespanResultT](diff --git a/tests/server/test_openapi.py b/tests/server/test_openapi.pyindex 35e9e9ab3..a7fe9a685 100644--- a/tests/server/test_openapi.py+++ b/tests/server/test_openapi.py@@ -36,17 +36,17 @@ def users_db() -> dict[int, User]:def fastapi_app(users_db: dict[int, User]) -> FastAPI:app = FastAPI(title="FastAPI App")- @app.get("/users")+ @app.get("/users", tags=["users", "list"])async def get_users() -> list[User]:"""Get all users."""return sorted(users_db.values(), key=lambda x: x.id)- @app.get("/users/{user_id}")+ @app.get("/users/{user_id}", tags=["users", "detail"])async def get_user(user_id: int) -> User | None:"""Get a user by ID."""return users_db.get(user_id)- @app.post("/users")+ @app.post("/users", tags=["users", "create"])async def create_user(user: UserCreate) -> User:"""Create a new user."""user_id = max(users_db.keys()) + 1@@ -54,7 +54,7 @@ def fastapi_app(users_db: dict[int, User]) -> FastAPI:users_db[user_id] = new_userreturn new_user- @app.patch("/users/{user_id}/name")+ @app.patch("/users/{user_id}/name", tags=["users", "update"])async def update_user_name(user_id: int, name: str) -> User:"""Update a user's name."""user = users_db.get(user_id)@@ -258,3 +258,98 @@ class TestPrompts:"""prompts = await fastmcp_server.list_prompts()assert len(prompts) == 0+++class TestTagTransfer:+ """Tests for transferring tags from OpenAPI to MCP objects."""++ async def test_tags_transferred_to_tools(self, fastmcp_server: FastMCPOpenAPI):+ """Test that tags from OpenAPI routes are correctly transferred to Tools."""+ # Get internal tools directly (not the public API which returns MCP.Content)+ tools = fastmcp_server._tool_manager.list_tools()++ # Find the create_user and update_user_name tools+ create_user_tool = next(+ (t for t in tools if t.name == "create_user_users_post"), None+ )+ update_user_tool = next(+ (+ t+ for t in tools+ if t.name == "update_user_name_users__user_id__name_patch"+ ),+ None,+ )++ assert create_user_tool is not None+ assert update_user_tool is not None++ # Check that tags from OpenAPI routes were transferred to the Tool objects+ assert "users" in create_user_tool.tags+ assert "create" in create_user_tool.tags+ assert len(create_user_tool.tags) == 2++ assert "users" in update_user_tool.tags+ assert "update" in update_user_tool.tags+ assert len(update_user_tool.tags) == 2++ async def test_tags_transferred_to_resources(self, fastmcp_server: FastMCPOpenAPI):+ """Test that tags from OpenAPI routes are correctly transferred to Resources."""+ # Get internal resources directly+ resources = fastmcp_server._resource_manager.list_resources()++ # Find the get_users resource+ get_users_resource = next(+ (r for r in resources if r.name == "get_users_users_get"), None+ )++ assert get_users_resource is not None++ # Check that tags from OpenAPI routes were transferred to the Resource object+ assert "users" in get_users_resource.tags+ assert "list" in get_users_resource.tags+ assert len(get_users_resource.tags) == 2++ async def test_tags_transferred_to_resource_templates(+ self, fastmcp_server: FastMCPOpenAPI+ ):+ """Test that tags from OpenAPI routes are correctly transferred to ResourceTemplates."""+ # Get internal resource templates directly+ templates = fastmcp_server._resource_manager.list_templates()++ # Find the get_user template+ get_user_template = next(+ (t for t in templates if t.name == "get_user_users__user_id__get"), None+ )++ assert get_user_template is not None++ # Check that tags from OpenAPI routes were transferred to the ResourceTemplate object+ assert "users" in get_user_template.tags+ assert "detail" in get_user_template.tags+ assert len(get_user_template.tags) == 2++ async def test_tags_preserved_in_resources_created_from_templates(+ self, fastmcp_server: FastMCPOpenAPI+ ):+ """Test that tags are preserved when creating resources from templates."""+ # Get internal resource templates directly+ templates = fastmcp_server._resource_manager.list_templates()++ # Find the get_user template+ get_user_template = next(+ (t for t in templates if t.name == "get_user_users__user_id__get"), None+ )++ assert get_user_template is not None++ # Manually create a resource from template+ params = {"user_id": 1}+ resource = await get_user_template.create_resource(+ "resource://openapi/get_user_users__user_id__get/1", params+ )++ # Verify tags are preserved from template to resource+ assert "users" in resource.tags+ assert "detail" in resource.tags+ assert len(resource.tags) == 2diff --git a/tests/utilities/openapi/test_openapi.py b/tests/utilities/openapi/test_openapi.pyindex 410fef210..83cec52b3 100644--- a/tests/utilities/openapi/test_openapi.py+++ b/tests/utilities/openapi/test_openapi.py@@ -460,6 +460,63 @@ def test_petstore_required_fields_resolution(parsed_petstore_routes):assert json_schema.get("required") == ["id", "name"]+def test_tags_parsing_in_petstore_routes(parsed_petstore_routes):+ """Test that tags are correctly parsed from the OpenAPI schema."""+ # All petstore routes should have the "pets" tag+ for route in parsed_petstore_routes:+ assert "pets" in route.tags, (+ f"Route {route.method} {route.path} is missing 'pets' tag"+ )+++def test_tag_list_structure(parsed_petstore_routes):+ """Test that tags are stored as a list of strings."""+ for route in parsed_petstore_routes:+ assert isinstance(route.tags, list), "Tags should be stored as a list"+ for tag in route.tags:+ assert isinstance(tag, str), "Each tag should be a string"+++def test_empty_tags_handling(bookstore_schema):+ """Test that routes with no tags are handled correctly with empty lists."""+ # Modify a route to remove tags+ if "tags" in bookstore_schema["paths"]["/books"]["get"]:+ del bookstore_schema["paths"]["/books"]["get"]["tags"]++ # Parse the modified schema+ routes = parse_openapi_to_http_routes(bookstore_schema)++ # Find the GET /books route+ get_books = next(+ (r for r in routes if r.method == "GET" and r.path == "/books"), None+ )+ assert get_books is not None++ # Should have an empty list, not None+ assert get_books.tags == [], "Routes without tags should have empty tag lists"+++def test_multiple_tags_preserved(bookstore_schema):+ """Test that multiple tags are preserved during parsing."""+ # Add multiple tags to a route+ bookstore_schema["paths"]["/books"]["get"]["tags"] = ["books", "catalog", "api"]++ # Parse the modified schema+ routes = parse_openapi_to_http_routes(bookstore_schema)++ # Find the GET /books route+ get_books = next(+ (r for r in routes if r.method == "GET" and r.path == "/books"), None+ )+ assert get_books is not None++ # Should have all tags+ assert "books" in get_books.tags+ assert "catalog" in get_books.tags+ assert "api" in get_books.tags+ assert len(get_books.tags) == 3++# --- Tests for BookStore schema --- #diff --git a/tests/utilities/openapi/test_openapi_fastapi.py b/tests/utilities/openapi/test_openapi_fastapi.pyindex b7da748cc..94d0afe6e 100644--- a/tests/utilities/openapi/test_openapi_fastapi.py+++ b/tests/utilities/openapi/test_openapi_fastapi.py@@ -432,3 +432,91 @@ def test_token_dependency_handling(route_map):token_headers = [p for p in header_params if p.name == "x-token"]assert len(token_headers) == 1, f"Expected x-token header in {op_id}"assert token_headers[0].required is True+++# --- Additional Tag-related Tests --- #+++def test_all_routes_have_tags(parsed_routes):+ """Test that all routes have a non-empty tags list."""+ for route in parsed_routes:+ assert hasattr(route, "tags"), f"Route {route.path} should have tags attribute"+ assert route.tags is not None, f"Route {route.path} tags should not be None"+ # FastAPI adds tags to all routes in our test fixture+ assert len(route.tags) > 0, f"Route {route.path} should have at least one tag"+++def test_tag_consistency_across_related_endpoints(route_map):+ """Test that related endpoints have consistent tags."""+ # All item endpoints should have the "items" tag+ item_endpoints = [+ "list_items",+ "create_item",+ "get_item",+ "update_item",+ "delete_item",+ ]+ for endpoint in item_endpoints:+ assert "items" in route_map[endpoint].tags, (+ f"Endpoint {endpoint} should have 'items' tag"+ )++ # Tag-related endpoints should have both "items" and "tags" tags+ tag_endpoints = ["update_item_tags", "get_item_tag"]+ for endpoint in tag_endpoints:+ assert "items" in route_map[endpoint].tags, (+ f"Endpoint {endpoint} should have 'items' tag"+ )+ assert "tags" in route_map[endpoint].tags, (+ f"Endpoint {endpoint} should have 'tags' tag"+ )+++def test_tag_order_preservation(fastapi_server):+ """Test that tag order is preserved in the parsed routes."""++ # Add a new endpoint with specifically ordered tags+ @fastapi_server.get(+ "/test-tag-order",+ tags=["first", "second", "third"],+ operation_id="test_tag_order",+ )+ async def test_tag_order():+ return {"result": "testing tag order"}++ # Get the updated schema and parse routes+ routes = parse_openapi_to_http_routes(fastapi_server.openapi())++ # Find our test route+ test_route = next((r for r in routes if r.path == "/test-tag-order"), None)+ assert test_route is not None++ # Check tag order is preserved+ assert test_route.tags == ["first", "second", "third"], (+ "Tag order should be preserved"+ )+++def test_duplicate_tags_handling(fastapi_server):+ """Test handling of duplicate tags in the OpenAPI schema."""++ # Add an endpoint with duplicate tags+ @fastapi_server.get(+ "/test-duplicate-tags",+ tags=["duplicate", "items", "duplicate"],+ operation_id="test_duplicate_tags",+ )+ async def test_duplicate_tags():+ return {"result": "testing duplicate tags"}++ # Get the updated schema and parse routes+ routes = parse_openapi_to_http_routes(fastapi_server.openapi())++ # Find our test route+ test_route = next((r for r in routes if r.path == "/test-duplicate-tags"), None)+ assert test_route is not None++ # Check that duplicate tags are preserved (FastAPI might deduplicate)+ # We'll test both possibilities to be safe+ assert "duplicate" in test_route.tags, "Tag 'duplicate' should be present"+ assert "items" in test_route.tags, "Tag 'items' should be present"