diff --git a/src/fastmcp/server/openapi.py b/src/fastmcp/server/openapi.py index 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 = client self._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 AnyUrl name=name, description=description, mime_type=mime_type, + tags=tags, ) self._client = client self._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 = client self._route = route @@ -405,6 +411,7 @@ class OpenAPIResourceTemplate(ResourceTemplate): description=self.description or f"Resource for {self._route.path}", # Provide default if None mime_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 dictionary self._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 dictionary self._resource_manager._resources[str(resource.uri)] = resource logger.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 dictionary self._resource_manager._templates[uri_template_str] = template logger.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.py index 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.py index 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_user return 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) == 2 diff --git a/tests/utilities/openapi/test_openapi.py b/tests/utilities/openapi/test_openapi.py index 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.py index 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"