edit examples

shiraayal-tadata · shiraayal-tadata · commit 0c5845132ad2 · 2025-04-20T11:58:28.000+03:00
diff --git a/README.md b/README.md
@@ -60,6 +60,7 @@ That's it! Your auto-generated MCP server is now available at `https://app.base.
 ## Documentation, Examples and Advanced Usage
 
 FastAPI-MCP provides comprehensive documentation in the `docs` folder:
+- [Best Practices](docs/00_BEST_PRACTICES.md) - Essential guidelines for converting APIs to MCP tools safely and effectively
 - [FAQ](docs/00_FAQ.md) - Frequently asked questions about usage, development and support
 - [Tool Naming](docs/01_tool_naming.md) - Best practices for naming your MCP tools using operation IDs
 - [Connecting to MCP Server](docs/02_connecting_to_the_mcp_server.md) - How to connect various MCP clients like Cursor and Claude Desktop
diff --git a/examples/01_basic_usage_example.py b/examples/01_basic_usage_example.py
@@ -2,24 +2,19 @@
 """
 This example shows a simple MCP server created from a FastAPI app.
 """
-from examples.shared.apps.items import app # The FastAPI app
-from examples.shared.setup import setup_logging
-
+from examples.shared.items_app import app # The FastAPI app
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
-
 # Add MCP server to the FastAPI app
 mcp = FastApiMCP(
     app,
     name="Item API MCP",
     description="MCP server for the Item API",
-    base_url="http://localhost:8000",
 )
 
+# Mount the MCP server to the FastAPI app
 mcp.mount()
 
 if __name__ == "__main__":
     import uvicorn
-
     uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/examples/02_full_schema_description_example.py b/examples/02_full_schema_description_example.py
@@ -2,14 +2,9 @@
 """
 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.setup import setup_logging
-
+from examples.shared.items_app import app # The FastAPI app
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
-
-# Add MCP server to the FastAPI app
 mcp = FastApiMCP(
     app,
     describe_full_response_schema=True,  # Include all possible response schemas in tool descriptions
diff --git a/examples/03_custom_exposed_endpoints_example.py b/examples/03_custom_exposed_endpoints_example.py
@@ -6,40 +6,42 @@
 - 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
-from examples.shared.setup import setup_logging
-
+from examples.shared.items_app import app # The FastAPI app
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
 
 # Filter by including specific operation IDs
 include_operations_mcp = FastApiMCP(
     app,
+    name="Item API MCP - Included Operations",
     include_operations=["get_item", "list_items"],
 )
 
 # Filter by excluding specific operation IDs
 exclude_operations_mcp = FastApiMCP(
     app,    
+    name="Item API MCP - Excluded Operations",
     exclude_operations=["create_item", "update_item", "delete_item"],
 )
 
 # Filter by including specific tags
 include_tags_mcp = FastApiMCP(
     app,
+    name="Item API MCP - Included Tags",
     include_tags=["items"],
 )
 
 # Filter by excluding specific tags
 exclude_tags_mcp = FastApiMCP(
     app,
+    name="Item API MCP - Excluded Tags",
     exclude_tags=["search"],
 )
 
 # Combine operation IDs and tags (include mode)
 combined_include_mcp = FastApiMCP(
     app,
+    name="Item API MCP - Combined Include",
     include_operations=["delete_item"],
     include_tags=["search"],
 )
diff --git a/examples/04_separate_server_example.py b/examples/04_separate_server_example.py
@@ -3,46 +3,28 @@
 You can create an MCP server from one FastAPI app, and mount it to a different app.
 """
 from fastapi import FastAPI
-import asyncio
-import uvicorn
 
-from examples.shared.apps.items import app
-from examples.shared.setup import setup_logging
+from examples.shared.items_app import app
 
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
-
-
 MCP_SERVER_HOST = "localhost"
 MCP_SERVER_PORT = 8000
 ITEMS_API_HOST = "localhost"
 ITEMS_API_PORT = 8001
 
 
 # Take the FastAPI app only as a source for MCP server generation
-mcp = FastApiMCP(
-    app,
-    base_url=f"http://{ITEMS_API_HOST}:{ITEMS_API_PORT}",  # Note how the base URL is the **Items API** URL, not the MCP server URL
-)
+mcp = FastApiMCP(app)
 
-# And then mount the MCP server to a separate FastAPI app
+# Mount the MCP server to a separate FastAPI app
 mcp_app = FastAPI()
 mcp.mount(mcp_app)
 
-
-def run_items_app():
-    uvicorn.run(app, port=ITEMS_API_PORT)
-
-
-def run_mcp_app():
-    uvicorn.run(mcp_app, port=MCP_SERVER_PORT)
-
-
-# The MCP server depends on the Items API to be available, so we need to run both.
-async def main():
-    await asyncio.gather(asyncio.to_thread(run_items_app), asyncio.to_thread(run_mcp_app))
-
-
+# Run the MCP server separately from the original FastAPI app.
+# It still works 🚀
+# Your original API is **not exposed**, only via the MCP server.
 if __name__ == "__main__":
-    asyncio.run(main())
+    import uvicorn
+
+    uvicorn.run(mcp_app, host="0.0.0.0", port=8000)
diff --git a/examples/05_reregister_tools_example.py b/examples/05_reregister_tools_example.py
@@ -1,17 +1,12 @@
 """
 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
-from examples.shared.setup import setup_logging
-
+from examples.shared.items_app import app # The FastAPI app
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
-
 
-# Add MCP server to the FastAPI app
-mcp = FastApiMCP(app)
-mcp.mount()
+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
@@ -26,5 +21,4 @@ async def new_endpoint():
 
 if __name__ == "__main__":
     import uvicorn
-
     uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/examples/06_custom_mcp_router_example.py b/examples/06_custom_mcp_router_example.py
@@ -1,26 +1,21 @@
 """
 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
-from examples.shared.setup import setup_logging
-
+from examples.shared.items_app import app # The FastAPI app
 from fastapi import APIRouter
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
-
 
-router = APIRouter(prefix="/other/route")
-app.include_router(router)
+other_router = APIRouter(prefix="/other/route")    
+app.include_router(other_router)
 
 mcp = FastApiMCP(app)
 
 # Mount the MCP server to a specific router.
 # It will now only be available at `/other/route/mcp`
-mcp.mount(router)
+mcp.mount(other_router)
 
 
 if __name__ == "__main__":
     import uvicorn
-
     uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/examples/07_configure_http_timeout_example.py b/examples/07_configure_http_timeout_example.py
@@ -4,21 +4,17 @@
 """
 import httpx
 
-from examples.shared.apps.items import app
-from examples.shared.setup import setup_logging
-
+from examples.shared.items_app import app # The FastAPI app
 from fastapi_mcp import FastApiMCP
 
-setup_logging()
 
 mcp = FastApiMCP(
     app,
-    http_client=httpx.AsyncClient(timeout=10)
+    http_client=httpx.AsyncClient(timeout=20)
 )
-mcp.mount(mcp)
+mcp.mount()
 
 
 if __name__ == "__main__":
     import uvicorn
-
     uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/examples/README.md b/examples/README.md
@@ -2,7 +2,7 @@
 
 The following examples demonstrate various features and usage patterns of FastAPI-MCP:
 
-1. [Simple Example](examples/01_simple_example.py) - Basic FastAPI-MCP integration
+1. [Basic Usage Example](examples/01_basic_usage_example.py) - Basic FastAPI-MCP integration
 2. [Full Schema Description](examples/02_full_schema_description_example.py) - Customizing schema descriptions
 3. [Custom Exposed Endpoints](examples/03_custom_exposed_endpoints_example.py) - Controlling which endpoints are exposed
 4. [Separate Server](examples/04_separate_server_example.py) - Deploying MCP server separately
diff --git a/examples/full_schema_description_example.py b/examples/full_schema_description_example.py
diff --git a/examples/shared/apps/__init__.py b/examples/shared/apps/__init__.py
diff --git a/examples/shared/items_app.py b/examples/shared/items_app.py
@@ -2,12 +2,12 @@
 Simple example of using FastAPI-MCP to add an MCP server to a FastAPI app.
 """
 
-from fastapi import APIRouter, HTTPException, Query
+from fastapi import FastAPI, HTTPException, Query
 from pydantic import BaseModel
 from typing import List, Optional
 
 
-router = APIRouter()
+app = FastAPI()
 
 
 class Item(BaseModel):
@@ -21,7 +21,7 @@ class Item(BaseModel):
 items_db: dict[int, Item] = {}
 
 
-@router.get("/items/", response_model=List[Item], tags=["items"], operation_id="list_items")
+@app.get("/items/", response_model=List[Item], tags=["items"], operation_id="list_items")
 async def list_items(skip: int = 0, limit: int = 10):
     """
     List all items in the database.
@@ -31,7 +31,7 @@ async def list_items(skip: int = 0, limit: int = 10):
     return list(items_db.values())[skip : skip + limit]
 
 
-@router.get("/items/{item_id}", response_model=Item, tags=["items"], operation_id="get_item")
+@app.get("/items/{item_id}", response_model=Item, tags=["items"], operation_id="get_item")
 async def read_item(item_id: int):
     """
     Get a specific item by its ID.
@@ -43,7 +43,7 @@ async def read_item(item_id: int):
     return items_db[item_id]
 
 
-@router.post("/items/", response_model=Item, tags=["items"], operation_id="create_item")
+@app.post("/items/", response_model=Item, tags=["items"], operation_id="create_item")
 async def create_item(item: Item):
     """
     Create a new item in the database.
@@ -54,7 +54,7 @@ async def create_item(item: Item):
     return item
 
 
-@router.put("/items/{item_id}", response_model=Item, tags=["items"], operation_id="update_item")
+@app.put("/items/{item_id}", response_model=Item, tags=["items"], operation_id="update_item")
 async def update_item(item_id: int, item: Item):
     """
     Update an existing item.
@@ -69,7 +69,7 @@ async def update_item(item_id: int, item: Item):
     return item
 
 
-@router.delete("/items/{item_id}", tags=["items"], operation_id="delete_item")
+@app.delete("/items/{item_id}", tags=["items"], operation_id="delete_item")
 async def delete_item(item_id: int):
     """
     Delete an item from the database.
@@ -83,7 +83,7 @@ async def delete_item(item_id: int):
     return {"message": "Item deleted successfully"}
 
 
-@router.get("/items/search/", response_model=List[Item], tags=["search"], operation_id="search_items")
+@app.get("/items/search/", response_model=List[Item], tags=["search"], operation_id="search_items")
 async def search_items(
     q: Optional[str] = Query(None, description="Search query string"),
     min_price: Optional[float] = Query(None, description="Minimum price"),
diff --git a/examples/shared/setup.py b/examples/shared/setup.py
