π The fast, Pythonic way to build MCP servers and clients.
Infer MIME types from OpenAPI response definitions (#3101)
Jeremiah Lowin85eff33b8124
diff --git a/src/fastmcp/server/providers/openapi/components.py b/src/fastmcp/server/providers/openapi/components.pyindex 43c58b956..4e6d18f1e 100644--- a/src/fastmcp/server/providers/openapi/components.py+++ b/src/fastmcp/server/providers/openapi/components.py@@ -33,10 +33,64 @@ __all__ = ["OpenAPIResource","OpenAPIResourceTemplate","OpenAPITool",+ "_extract_mime_type_from_route",]logger = get_logger(__name__)+# Default MIME type when no response content type can be inferred+_DEFAULT_MIME_TYPE = "application/json"+++def _extract_mime_type_from_route(route: HTTPRoute) -> str:+ """Extract the primary MIME type from an HTTPRoute's response definitions.++ Looks for the first successful response (2xx) and returns its content type.+ Prefers JSON-compatible types when multiple are available.+ Falls back to "application/json" when no response content type is declared.+ """+ if not route.responses:+ return _DEFAULT_MIME_TYPE++ # Priority order for success status codes+ success_codes = ["200", "201", "202", "204"]++ response_info = None+ for status_code in success_codes:+ if status_code in route.responses:+ response_info = route.responses[status_code]+ break++ # If no explicit success codes, try any 2xx response+ if response_info is None:+ for status_code, resp_info in route.responses.items():+ if status_code.startswith("2"):+ response_info = resp_info+ break++ if response_info is None or not response_info.content_schema:+ return _DEFAULT_MIME_TYPE++ # If there's only one content type, use it directly+ content_types = list(response_info.content_schema.keys())+ if len(content_types) == 1:+ return content_types[0]++ # When multiple types exist, prefer JSON-compatible types+ json_compatible_types = [+ "application/json",+ "application/vnd.api+json",+ "application/hal+json",+ "application/ld+json",+ "text/json",+ ]+ for ct in json_compatible_types:+ if ct in response_info.content_schema:+ return ct++ # Fall back to the first available content type+ return content_types[0]+def _slugify(text: str) -> str:"""Convert text to a URL-friendly slug format.@@ -294,6 +348,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):description: str,parameters: dict[str, Any],tags: set[str] | None = None,+ mime_type: str = _DEFAULT_MIME_TYPE,):super().__init__(uri_template=uri_template,@@ -301,6 +356,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):description=description,parameters=parameters,tags=tags or set(),+ mime_type=mime_type,)self._client = clientself._route = route@@ -325,6 +381,6 @@ class OpenAPIResourceTemplate(ResourceTemplate):uri=uri,name=f"{self.name}-{'-'.join(uri_parts)}",description=self.description or f"Resource for {self._route.path}",- mime_type="application/json",+ mime_type=self.mime_type,tags=set(self._route.tags or []),)diff --git a/src/fastmcp/server/providers/openapi/provider.py b/src/fastmcp/server/providers/openapi/provider.pyindex a93be1a41..ac79af400 100644--- a/src/fastmcp/server/providers/openapi/provider.py+++ b/src/fastmcp/server/providers/openapi/provider.py@@ -17,6 +17,7 @@ from fastmcp.server.providers.openapi.components import (OpenAPIResource,OpenAPIResourceTemplate,OpenAPITool,+ _extract_mime_type_from_route,_slugify,)from fastmcp.server.providers.openapi.routing import (@@ -288,6 +289,7 @@ class OpenAPIProvider(Provider):uri=resource_uri,name=resource_name,description=enhanced_description,+ mime_type=_extract_mime_type_from_route(route),tags=set(route.tags or []) | tags,)@@ -356,6 +358,7 @@ class OpenAPIProvider(Provider):description=enhanced_description,parameters=template_params_schema,tags=set(route.tags or []) | tags,+ mime_type=_extract_mime_type_from_route(route),)if self._mcp_component_fn is not None:diff --git a/src/fastmcp/utilities/openapi/parser.py b/src/fastmcp/utilities/openapi/parser.pyindex e284295fa..40adf8d27 100644--- a/src/fastmcp/utilities/openapi/parser.py+++ b/src/fastmcp/utilities/openapi/parser.py@@ -506,6 +506,10 @@ class OpenAPIParser(f"Failed to extract schema for media type '{media_type_str}' "f"in response {status_code}: {e}")+ else:+ # Record the media type even without a schema so MIME+ # type inference can still use the declared content type.+ resp_info.content_schema.setdefault(media_type_str, {})extracted_responses[str(status_code)] = resp_infoexcept ValueError as e:diff --git a/tests/server/providers/openapi/test_openapi_features.py b/tests/server/providers/openapi/test_openapi_features.pyindex b466268fe..f55a1e038 100644--- a/tests/server/providers/openapi/test_openapi_features.py+++ b/tests/server/providers/openapi/test_openapi_features.py@@ -6,6 +6,9 @@ import pytestfrom fastmcp import FastMCPfrom fastmcp.client import Clientfrom fastmcp.server.providers.openapi import OpenAPIProvider+from fastmcp.server.providers.openapi.components import _extract_mime_type_from_route+from fastmcp.server.providers.openapi.routing import MCPType, RouteMap+from fastmcp.utilities.openapi.models import HTTPRoute, ResponseInfodef create_openapi_server(@@ -412,3 +415,357 @@ class TestResponseSchemas:# Let's just check the tool exists and has basic propertiesassert get_user_tool.description is not Noneassert get_user_tool.name == "get_user"+++class TestMimeTypeExtraction:+ """Test MIME type extraction from route responses."""++ def test_json_response(self):+ """JSON content type is correctly extracted."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ responses={+ "200": ResponseInfo(+ content_schema={"application/json": {"type": "object"}}+ )+ },+ )+ assert _extract_mime_type_from_route(route) == "application/json"++ def test_text_plain_response(self):+ """Plain text content type is correctly extracted."""+ route = HTTPRoute(+ path="/health",+ method="GET",+ responses={+ "200": ResponseInfo(content_schema={"text/plain": {"type": "string"}})+ },+ )+ assert _extract_mime_type_from_route(route) == "text/plain"++ def test_text_html_response(self):+ """HTML content type is correctly extracted."""+ route = HTTPRoute(+ path="/page",+ method="GET",+ responses={+ "200": ResponseInfo(content_schema={"text/html": {"type": "string"}})+ },+ )+ assert _extract_mime_type_from_route(route) == "text/html"++ def test_image_response(self):+ """Image content type is correctly extracted."""+ route = HTTPRoute(+ path="/avatar",+ method="GET",+ responses={+ "200": ResponseInfo(+ content_schema={"image/png": {"type": "string", "format": "binary"}}+ )+ },+ )+ assert _extract_mime_type_from_route(route) == "image/png"++ def test_no_responses_defaults_to_json(self):+ """Empty responses default to application/json."""+ route = HTTPRoute(path="/items", method="GET", responses={})+ assert _extract_mime_type_from_route(route) == "application/json"++ def test_no_content_schema_defaults_to_json(self):+ """Response without content_schema defaults to application/json."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ responses={"204": ResponseInfo(description="No content")},+ )+ assert _extract_mime_type_from_route(route) == "application/json"++ def test_prefers_json_when_multiple_types(self):+ """When both JSON and other types exist, JSON is preferred."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ responses={+ "200": ResponseInfo(+ content_schema={+ "text/html": {"type": "string"},+ "application/json": {"type": "object"},+ }+ )+ },+ )+ assert _extract_mime_type_from_route(route) == "application/json"++ def test_non_standard_2xx_code(self):+ """Falls back to any 2xx status code when standard ones are missing."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ responses={+ "206": ResponseInfo(+ content_schema={+ "application/octet-stream": {+ "type": "string",+ "format": "binary",+ }+ }+ )+ },+ )+ assert _extract_mime_type_from_route(route) == "application/octet-stream"++ def test_ignores_error_responses(self):+ """Only error responses (no 2xx) results in default."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ responses={+ "404": ResponseInfo(+ content_schema={"application/json": {"type": "object"}}+ )+ },+ )+ assert _extract_mime_type_from_route(route) == "application/json"++ def test_201_response(self):+ """201 Created response content type is extracted."""+ route = HTTPRoute(+ path="/items",+ method="POST",+ responses={+ "201": ResponseInfo(content_schema={"text/plain": {"type": "string"}})+ },+ )+ assert _extract_mime_type_from_route(route) == "text/plain"++ def test_media_type_without_schema(self):+ """Media type declared without a schema still infers MIME type."""+ route = HTTPRoute(+ path="/health",+ method="GET",+ responses={"200": ResponseInfo(content_schema={"text/plain": {}})},+ )+ assert _extract_mime_type_from_route(route) == "text/plain"+++class TestResourceTemplateMimeType:+ """Test that OpenAPIResourceTemplate uses inferred MIME types."""++ @pytest.fixture+ def text_plain_spec(self):+ """OpenAPI spec with a text/plain resource template endpoint."""+ return {+ "openapi": "3.0.0",+ "info": {"title": "Text API", "version": "1.0.0"},+ "servers": [{"url": "https://api.example.com"}],+ "paths": {+ "/documents/{id}": {+ "get": {+ "operationId": "get_document",+ "summary": "Get document content",+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "required": True,+ "schema": {"type": "string"},+ }+ ],+ "responses": {+ "200": {+ "description": "Document content",+ "content": {+ "text/plain": {"schema": {"type": "string"}}+ },+ }+ },+ }+ }+ },+ }++ @pytest.fixture+ def html_spec(self):+ """OpenAPI spec with a text/html resource endpoint."""+ return {+ "openapi": "3.0.0",+ "info": {"title": "HTML API", "version": "1.0.0"},+ "servers": [{"url": "https://api.example.com"}],+ "paths": {+ "/pages/{slug}": {+ "get": {+ "operationId": "get_page",+ "summary": "Get HTML page",+ "parameters": [+ {+ "name": "slug",+ "in": "path",+ "required": True,+ "schema": {"type": "string"},+ }+ ],+ "responses": {+ "200": {+ "description": "HTML page",+ "content": {+ "text/html": {"schema": {"type": "string"}}+ },+ }+ },+ }+ }+ },+ }++ async def test_resource_template_text_plain_mime_type(self, text_plain_spec):+ """Resource template should reflect text/plain from OpenAPI spec."""+ route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]+ async with httpx.AsyncClient(base_url="https://api.example.com") as client:+ provider = OpenAPIProvider(+ openapi_spec=text_plain_spec, client=client, route_maps=route_maps+ )+ mcp = FastMCP("Test")+ mcp.add_provider(provider)+ async with Client(mcp) as mcp_client:+ templates = await mcp_client.list_resource_templates()+ assert len(templates) == 1+ assert templates[0].mimeType == "text/plain"++ async def test_resource_template_html_mime_type(self, html_spec):+ """Resource template should reflect text/html from OpenAPI spec."""+ route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]+ async with httpx.AsyncClient(base_url="https://api.example.com") as client:+ provider = OpenAPIProvider(+ openapi_spec=html_spec, client=client, route_maps=route_maps+ )+ mcp = FastMCP("Test")+ mcp.add_provider(provider)+ async with Client(mcp) as mcp_client:+ templates = await mcp_client.list_resource_templates()+ assert len(templates) == 1+ assert templates[0].mimeType == "text/html"++ async def test_resource_template_defaults_json_mime_type(self):+ """Resource template defaults to application/json for JSON responses."""+ spec = {+ "openapi": "3.0.0",+ "info": {"title": "JSON API", "version": "1.0.0"},+ "servers": [{"url": "https://api.example.com"}],+ "paths": {+ "/users/{id}": {+ "get": {+ "operationId": "get_user",+ "summary": "Get user",+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "required": True,+ "schema": {"type": "integer"},+ }+ ],+ "responses": {+ "200": {+ "description": "User data",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {"type": "integer"},+ "name": {"type": "string"},+ },+ }+ }+ },+ }+ },+ }+ }+ },+ }+ route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]+ async with httpx.AsyncClient(base_url="https://api.example.com") as client:+ provider = OpenAPIProvider(+ openapi_spec=spec, client=client, route_maps=route_maps+ )+ mcp = FastMCP("Test")+ mcp.add_provider(provider)+ async with Client(mcp) as mcp_client:+ templates = await mcp_client.list_resource_templates()+ assert len(templates) == 1+ assert templates[0].mimeType == "application/json"+++class TestResourceMimeType:+ """Test that OpenAPIResource uses inferred MIME types."""++ async def test_resource_text_plain_mime_type(self):+ """Static resource should reflect text/plain from OpenAPI spec."""+ spec = {+ "openapi": "3.0.0",+ "info": {"title": "Health API", "version": "1.0.0"},+ "servers": [{"url": "https://api.example.com"}],+ "paths": {+ "/health": {+ "get": {+ "operationId": "healthcheck",+ "summary": "Health check",+ "responses": {+ "200": {+ "description": "Health status",+ "content": {+ "text/plain": {"schema": {"type": "string"}}+ },+ }+ },+ }+ }+ },+ }+ route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE)]+ async with httpx.AsyncClient(base_url="https://api.example.com") as client:+ provider = OpenAPIProvider(+ openapi_spec=spec, client=client, route_maps=route_maps+ )+ mcp = FastMCP("Test")+ mcp.add_provider(provider)+ async with Client(mcp) as mcp_client:+ resources = await mcp_client.list_resources()+ assert len(resources) == 1+ assert resources[0].mimeType == "text/plain"++ async def test_resource_mime_type_without_schema(self):+ """Resource with media type but no schema still infers MIME type."""+ spec = {+ "openapi": "3.0.0",+ "info": {"title": "Health API", "version": "1.0.0"},+ "servers": [{"url": "https://api.example.com"}],+ "paths": {+ "/health": {+ "get": {+ "operationId": "healthcheck",+ "summary": "Health check",+ "responses": {+ "200": {+ "description": "Health status",+ "content": {"text/plain": {}},+ }+ },+ }+ }+ },+ }+ route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE)]+ async with httpx.AsyncClient(base_url="https://api.example.com") as client:+ provider = OpenAPIProvider(+ openapi_spec=spec, client=client, route_maps=route_maps+ )+ mcp = FastMCP("Test")+ mcp.add_provider(provider)+ async with Client(mcp) as mcp_client:+ resources = await mcp_client.list_resources()+ assert len(resources) == 1+ assert resources[0].mimeType == "text/plain"