Feature/mcp prompts support

README.md

@@ -68,6 +68,115 @@ mcp.mount()
 
 That's it! Your auto-generated MCP server is now available at `https://app.base.url/mcp`.
 
+## MCP Prompts Support
+
+FastAPI-MCP automatically generates helpful prompts for each of your API endpoints and supports custom prompts for enhanced AI interactions.
+
+### Auto-Generated Tool Prompts
+
+By default, every FastAPI endpoint automatically gets a corresponding prompt (named `use_{endpoint_name}`) that provides AI models with guidance on how to use that specific tool:
+
+```python
+from fastapi import FastAPI
+from fastapi_mcp import FastApiMCP
+
+app = FastAPI()
+
+@app.post("/create_item")
+async def create_item(name: str, price: float):
+    """Create a new item in the inventory."""
+    return {"name": name, "price": price}
+
+# Auto-generation is enabled by default
+mcp = FastApiMCP(app, auto_generate_prompts=True)  # This is the default
+mcp.mount()
+
+# Automatically creates a prompt named "use_create_item" with guidance
+# on how to use the create_item tool effectively
+```
+
+#### Controlling Auto-Generation
+
+You have full control over prompt auto-generation:
+
+```python
+# Option 1: Auto-generated prompts only (default)
+mcp = FastApiMCP(app, auto_generate_prompts=True)
+
+# Option 2: Disable auto-generation, use only custom prompts  
+mcp = FastApiMCP(app, auto_generate_prompts=False)
+
+# Option 3: Mixed approach - auto-generated + custom overrides
+mcp = FastApiMCP(app, auto_generate_prompts=True)
+# Then add custom prompts or override auto-generated ones
+```
+
+### Custom Prompt Overrides
+
+You can override auto-generated prompts or create entirely custom ones:
+
+```python
+# Override the auto-generated prompt for better guidance
+@mcp.prompt("use_create_item", title="Item Creation Guide")
+def create_item_guide():
+    return PromptMessage(
+        role="user",
+        content=TextContent(
+            text="""Use the create_item tool to add items to inventory.
+
+Best Practices:
+- Use descriptive names (e.g., "Wireless Bluetooth Mouse")
+- Set realistic prices in decimal format (e.g., 29.99)
+- Include detailed descriptions for better categorization
+
+This tool will validate inputs and return the created item details."""
+        )
+    )
+```
+
+### API Documentation Prompts
+
+Create dynamic prompts that help with API understanding:
+
+```python
+@mcp.prompt("api_documentation")
+def api_docs_prompt(endpoint_path: Optional[str] = None):
+    if endpoint_path:
+        return PromptMessage(
+            role="user",
+            content=TextContent(
+                text=f"Please provide comprehensive documentation for {endpoint_path}, including parameters, examples, and use cases."
+            )
+        )
+    else:
+        # Generate overview of all endpoints
+        return PromptMessage(
+            role="user", 
+            content=TextContent(text="Please explain this API's purpose and how to use its endpoints effectively.")
+        )
+```
+
+### Welcome and Troubleshooting Prompts
+
+```python
+@mcp.prompt("welcome")
+def welcome_prompt():
+    return PromptMessage(
+        role="user",
+        content=TextContent(text="Please provide a friendly welcome message for API users.")
+    )
+
+@mcp.prompt("troubleshoot")  
+async def troubleshoot_prompt(error_message: str, endpoint: Optional[str] = None):
+    return PromptMessage(
+        role="user",
+        content=TextContent(
+            text=f"Help troubleshoot this API issue: {error_message}" + 
+                 (f" on endpoint {endpoint}" if endpoint else "")
+        )
+    )
+```
+
 ## Documentation, Examples and Advanced Usage
 
 FastAPI-MCP provides [comprehensive documentation](https://fastapi-mcp.tadata.com/). Additionaly, check out the [examples directory](examples) for code samples demonstrating these features in action.

examples/01_basic_usage_example.py

@@ -1,4 +1,4 @@
-from examples.shared.apps.items import app # The FastAPI app
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 from fastapi_mcp import FastApiMCP
@@ -15,4 +15,4 @@
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="0.0.0.0", port=8000)
+    uvicorn.run(app, host="0.0.0.0", port=8000)

examples/02_full_schema_description_example.py

@@ -1,8 +1,8 @@
-
 """
 This example shows how to describe the full response schema instead of just a response example.
 """
-from examples.shared.apps.items import app # The FastAPI app
+
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 from fastapi_mcp import FastApiMCP
@@ -22,5 +22,5 @@
 
 if __name__ == "__main__":
     import uvicorn
-    
+
     uvicorn.run(app, host="0.0.0.0", port=8000)

examples/03_custom_exposed_endpoints_example.py

@@ -6,7 +6,8 @@
 - You can combine operation filtering with tag filtering (e.g., use `include_operations` with `include_tags`)
 - When combining filters, a greedy approach will be taken. Endpoints matching either criteria will be included
 """
-from examples.shared.apps.items import app # The FastAPI app
+
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 from fastapi_mcp import FastApiMCP
@@ -24,7 +25,7 @@
 
 # Filter by excluding specific operation IDs
 exclude_operations_mcp = FastApiMCP(
-    app,    
+    app,
     name="Item API MCP - Excluded Operations",
     exclude_operations=["create_item", "update_item", "delete_item"],
 )

examples/04_separate_server_example.py

@@ -2,6 +2,7 @@
 This example shows how to run the MCP server and the FastAPI app separately.
 You can create an MCP server from one FastAPI app, and mount it to a different app.
 """
+
 from fastapi import FastAPI
 
 from examples.shared.apps.items import app
@@ -30,4 +31,4 @@
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(mcp_app, host="0.0.0.0", port=8000)
+    uvicorn.run(mcp_app, host="0.0.0.0", port=8000)

examples/05_reregister_tools_example.py

@@ -1,15 +1,16 @@
 """
 This example shows how to re-register tools if you add endpoints after the MCP server was created.
 """
-from examples.shared.apps.items import app # The FastAPI app
+
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 from fastapi_mcp import FastApiMCP
 
 setup_logging()
 
-mcp = FastApiMCP(app) # Add MCP server to the FastAPI app
-mcp.mount() # MCP server
+mcp = FastApiMCP(app)  # Add MCP server to the FastAPI app
+mcp.mount()  # MCP server
 
 
 # This endpoint will not be registered as a tool, since it was added after the MCP instance was created
@@ -24,5 +25,5 @@ async def new_endpoint():
 
 if __name__ == "__main__":
     import uvicorn
-    
+
     uvicorn.run(app, host="0.0.0.0", port=8000)

examples/06_custom_mcp_router_example.py

@@ -1,15 +1,16 @@
 """
 This example shows how to mount the MCP server to a specific APIRouter, giving a custom mount path.
 """
-from examples.shared.apps.items import app # The FastAPI app
+
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 from fastapi import APIRouter
 from fastapi_mcp import FastApiMCP
 
 setup_logging()
 
-other_router = APIRouter(prefix="/other/route")    
+other_router = APIRouter(prefix="/other/route")
 app.include_router(other_router)
 
 mcp = FastApiMCP(app)
@@ -21,5 +22,5 @@
 
 if __name__ == "__main__":
     import uvicorn
-    
+
     uvicorn.run(app, host="0.0.0.0", port=8000)

examples/07_configure_http_timeout_example.py

@@ -2,7 +2,8 @@
 This example shows how to configure the HTTP client timeout for the MCP server.
 In case you have API endpoints that take longer than 5 seconds to respond, you can increase the timeout.
 """
-from examples.shared.apps.items import app # The FastAPI app
+
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 import httpx
@@ -12,14 +13,11 @@
 setup_logging()
 
 
-mcp = FastApiMCP(
-    app,
-    http_client=httpx.AsyncClient(timeout=20)
-)
+mcp = FastApiMCP(app, http_client=httpx.AsyncClient(timeout=20))
 mcp.mount()
 
 
 if __name__ == "__main__":
     import uvicorn
-    
+
     uvicorn.run(app, host="0.0.0.0", port=8000)

examples/08_auth_example_token_passthrough.py

@@ -21,7 +21,8 @@
 }
 ```
 """
-from examples.shared.apps.items import app # The FastAPI app
+
+from examples.shared.apps.items import app  # The FastAPI app
 from examples.shared.setup import setup_logging
 
 from fastapi import Depends
@@ -34,11 +35,13 @@
 # Scheme for the Authorization header
 token_auth_scheme = HTTPBearer()
 
+
 # Create a private endpoint
 @app.get("/private")
-async def private(token = Depends(token_auth_scheme)):
+async def private(token=Depends(token_auth_scheme)):
     return token.credentials
 
+
 # Create the MCP server with the token auth scheme
 mcp = FastApiMCP(
     app,
@@ -54,5 +57,5 @@ async def private(token = Depends(token_auth_scheme)):
 
 if __name__ == "__main__":
     import uvicorn
-    
-    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)