add describe_all_responses and describe_full_response_schema params

Author: shahar4499

examples/sample_app.py

@@ -147,6 +147,8 @@ async def search_items(
     name="Item API MCP",
     description="MCP server for the Item API",
     base_url="http://localhost:8000",
+    describe_all_responses=False,  # Only describe the success response in tool descriptions
+    describe_full_response_schema=False,  # Only show LLM-friendly example response in tool descriptions, not the full json schema
 )
 
 

examples/simple_integration.py

@@ -4,16 +4,14 @@
 This module provides functionality for creating MCP tools from FastAPI endpoints.
 """
 
-import inspect
 import json
 import logging
-from typing import Any, Callable, Dict, List, Optional, Type, get_type_hints
+from typing import Any, Dict, List, Optional
 
 import httpx
-from fastapi import FastAPI, params
+from fastapi import FastAPI
 from fastapi.openapi.utils import get_openapi
 from mcp.server.fastmcp import FastMCP
-from pydantic import BaseModel
 
 logger = logging.getLogger("fastapi_mcp")
 
@@ -101,14 +99,22 @@ def clean_schema_for_display(schema: Dict[str, Any]) -> Dict[str, Any]:
     return schema
 
 
-def create_mcp_tools_from_openapi(app: FastAPI, mcp_server: FastMCP, base_url: str = None) -> None:
+def create_mcp_tools_from_openapi(
+    app: FastAPI,
+    mcp_server: FastMCP,
+    base_url: Optional[str] = None,
+    describe_all_responses: bool = False,
+    describe_full_response_schema: bool = False,
+) -> None:
     """
     Create MCP tools from a FastAPI app's OpenAPI schema.
 
     Args:
         app: The FastAPI application
         mcp_server: The MCP server to add tools to
         base_url: Base URL for API requests (defaults to http://localhost:$PORT)
+        describe_all_responses: Whether to include all possible response schemas in tool descriptions
+        describe_full_response_schema: Whether to include full response schema in tool descriptions
     """
     # Get OpenAPI schema from FastAPI app
     openapi_schema = get_openapi(
@@ -161,6 +167,8 @@ def create_mcp_tools_from_openapi(app: FastAPI, mcp_server: FastMCP, base_url: s
                 request_body=operation.get("requestBody", {}),
                 responses=operation.get("responses", {}),
                 openapi_schema=openapi_schema,
+                describe_all_responses=describe_all_responses,
+                describe_full_response_schema=describe_full_response_schema,
             )
 
 
@@ -176,6 +184,8 @@ def create_http_tool(
     request_body: Dict[str, Any],
     responses: Dict[str, Any],
     openapi_schema: Dict[str, Any],
+    describe_all_responses: bool,
+    describe_full_response_schema: bool,
 ) -> None:
     """
     Create an MCP tool that makes an HTTP request to a FastAPI endpoint.
@@ -192,6 +202,8 @@ def create_http_tool(
         request_body: OpenAPI request body
         responses: OpenAPI responses
         openapi_schema: The full OpenAPI schema
+        describe_all_responses: Whether to include all possible response schemas in tool descriptions
+        describe_full_response_schema: Whether to include full response schema in tool descriptions
     """
     # Build tool description
     tool_description = f"{summary}" if summary else f"{method.upper()} {path}"
@@ -210,8 +222,16 @@ def create_http_tool(
                 success_response = responses[str(status_code)]
                 break
 
-        # Process all responses
-        for status_code, response_data in responses.items():
+        # Get the list of responses to include
+        responses_to_include = responses
+        if not describe_all_responses and success_response:
+            # If we're not describing all responses, only include the success response
+            success_code = next((code for code in success_codes if str(code) in responses), None)
+            if success_code:
+                responses_to_include = {str(success_code): success_response}
+
+        # Process all selected responses
+        for status_code, response_data in responses_to_include.items():
             response_desc = response_data.get("description", "")
             response_info += f"\n**{status_code}**: {response_desc}"
 
@@ -310,30 +330,25 @@ def create_http_tool(
                                 response_info += json.dumps(generated_example, indent=2)
                                 response_info += "\n```"
 
-                        # Format schema information based on its type
-                        if display_schema.get("type") == "array" and "items" in display_schema:
-                            items_schema = display_schema["items"]
-                            # Check if items reference a model
-                            items_model_name = None
-                            if "$ref" in schema.get("items", {}):
-                                items_ref_path = schema["items"]["$ref"]
-                                if items_ref_path.startswith("#/components/schemas/"):
-                                    items_model_name = items_ref_path.split("/")[-1]
-                                    response_info += f"\nArray of: {items_model_name}"
-
-                            response_info += (
-                                "\n\n**Output Schema:** Array of items with the following structure:\n```json\n"
-                            )
-                            response_info += json.dumps(items_schema, indent=2)
-                            response_info += "\n```"
-                        elif "properties" in display_schema:
-                            response_info += "\n\n**Output Schema:**\n```json\n"
-                            response_info += json.dumps(display_schema, indent=2)
-                            response_info += "\n```"
-                        else:
-                            response_info += "\n\n**Output Schema:**\n```json\n"
-                            response_info += json.dumps(display_schema, indent=2)
-                            response_info += "\n```"
+                        # Only include full schema information if requested
+                        if describe_full_response_schema:
+                            # Format schema information based on its type
+                            if display_schema.get("type") == "array" and "items" in display_schema:
+                                items_schema = display_schema["items"]
+
+                                response_info += (
+                                    "\n\n**Output Schema:** Array of items with the following structure:\n```json\n"
+                                )
+                                response_info += json.dumps(items_schema, indent=2)
+                                response_info += "\n```"
+                            elif "properties" in display_schema:
+                                response_info += "\n\n**Output Schema:**\n```json\n"
+                                response_info += json.dumps(display_schema, indent=2)
+                                response_info += "\n```"
+                            else:
+                                response_info += "\n\n**Output Schema:**\n```json\n"
+                                response_info += json.dumps(display_schema, indent=2)
+                                response_info += "\n```"
 
         tool_description += response_info
 

fastapi_mcp/http_tools.py

@@ -4,7 +4,7 @@
 This module provides functionality for creating and mounting MCP servers to FastAPI applications.
 """
 
-from typing import Dict, Optional, Union, Any
+from typing import Dict, Optional, Any
 
 from fastapi import FastAPI
 from mcp.server.fastmcp import FastMCP
@@ -53,6 +53,8 @@ def mount_mcp_server(
     mount_path: str = "/mcp",
     serve_tools: bool = True,
     base_url: Optional[str] = None,
+    describe_all_responses: bool = False,
+    describe_full_response_schema: bool = False,
 ) -> None:
     """
     Mount an MCP server to a FastAPI app.
@@ -63,6 +65,8 @@ def mount_mcp_server(
         mount_path: Path where the MCP server will be mounted
         serve_tools: Whether to serve tools from the FastAPI app
         base_url: Base URL for API requests
+        describe_all_responses: Whether to include all possible response schemas in tool descriptions. Recommended to keep False, as the LLM will probably derive if there is an error.
+        describe_full_response_schema: Whether to include full json schema for responses in tool descriptions. Recommended to keep False, as examples are more LLM friendly, and save tokens.
     """
     # Normalize mount path
     if not mount_path.startswith("/"):
@@ -88,7 +92,13 @@ async def handle_mcp_connection(request: Request):
 
     # Serve tools from the FastAPI app if requested
     if serve_tools:
-        create_mcp_tools_from_openapi(app, mcp_server, base_url)
+        create_mcp_tools_from_openapi(
+            app,
+            mcp_server,
+            base_url,
+            describe_all_responses=describe_all_responses,
+            describe_full_response_schema=describe_full_response_schema,
+        )
 
 
 def add_mcp_server(
@@ -99,6 +109,8 @@ def add_mcp_server(
     capabilities: Optional[Dict[str, Any]] = None,
     serve_tools: bool = True,
     base_url: Optional[str] = None,
+    describe_all_responses: bool = False,
+    describe_full_response_schema: bool = False,
 ) -> FastMCP:
     """
     Add an MCP server to a FastAPI app.
@@ -111,6 +123,8 @@ def add_mcp_server(
         capabilities: Optional capabilities for the MCP server
         serve_tools: Whether to serve tools from the FastAPI app
         base_url: Base URL for API requests (defaults to http://localhost:$PORT)
+        describe_all_responses: Whether to include all possible response schemas in tool descriptions. Recommended to keep False, as the LLM will probably derive if there is an error.
+        describe_full_response_schema: Whether to include full json schema for responses in tool descriptions. Recommended to keep False, as examples are more LLM friendly, and save tokens.
 
     Returns:
         The FastMCP instance that was created and mounted
@@ -119,6 +133,14 @@ def add_mcp_server(
     mcp_server = create_mcp_server(app, name, description, capabilities)
 
     # Mount MCP server to FastAPI app
-    mount_mcp_server(app, mcp_server, mount_path, serve_tools, base_url)
+    mount_mcp_server(
+        app,
+        mcp_server,
+        mount_path,
+        serve_tools,
+        base_url,
+        describe_all_responses=describe_all_responses,
+        describe_full_response_schema=describe_full_response_schema,
+    )
 
     return mcp_server