WIP

Author: shahar4499

README.md

@@ -1,20 +1,18 @@
 # FastAPI-MCP
 
-A magical, zero-configuration tool for generating Model Context Protocol (MCP) servers from FastAPI applications.
+A zero-configuration tool for integrating Model Context Protocol (MCP) servers with FastAPI applications.
 
 [![PyPI version](https://badge.fury.io/py/fastapi-mcp.svg)](https://pypi.org/project/fastapi-mcp/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-mcp.svg)](https://pypi.org/project/fastapi-mcp/)
 
 ## Features
 
-- **Automatic discovery** of all FastAPI endpoints in your application
+- **Direct integration** - Mount an MCP server directly to your FastAPI app
 - **Zero configuration** required - just point it at your FastAPI app and it works
-- **CLI tool** for easy generation and execution of MCP servers
-- **Stdio support** for MCP protocol communication
+- **Automatic discovery** of all FastAPI endpoints and conversion to MCP tools
 - **Type-safe conversion** from FastAPI endpoints to MCP tools
 - **Documentation preservation** from FastAPI to MCP
-- **Claude integration** for easy installation and use with Claude desktop application
-- **API Integration** - automatically makes HTTP requests to your FastAPI endpoints
+- **Custom tools** - Add custom MCP tools alongside your API endpoints
 
 ## Installation
 
@@ -28,163 +26,149 @@ For detailed installation instructions and alternative methods, see [INSTALL.md]
 
 ## Usage
 
-### Generate an MCP server from a FastAPI app
+### Direct integration (Recommended)
 
-```bash
-# Point to a FastAPI application file or module
-fastapi-mcp generate app.py
+The simplest way to use FastAPI-MCP is to add an MCP server directly to your FastAPI application:
 
-# Or specify the app variable if it's not named 'app'
-fastapi-mcp generate module.py:my_app
+```python
+from fastapi import FastAPI
+from fastapi_mcp import add_mcp_server
 
-# Use a custom base URL for the API endpoints (default: http://localhost:8000)
-fastapi-mcp generate app.py --base-url https://api.example.com
-```
+# Create your FastAPI app
+app = FastAPI()
 
-### Preview the generated MCP server
+# Define your endpoints...
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: str = None):
+    """Get details for a specific item"""
+    return {"item_id": item_id, "q": q}
 
-```bash
-fastapi-mcp preview
+# Add an MCP server to your app
+mcp_server = add_mcp_server(
+    app,                    # Your FastAPI app
+    mount_path="/mcp",      # Where to mount the MCP server
+    name="My API MCP",      # Name for the MCP server
+    base_url="http://localhost:8000"  # Base URL for API requests
+)
+
+# Optionally add custom MCP tools
+@mcp_server.tool()
+async def get_item_count() -> int:
+    """Get the total number of items in the database."""
+    return 42  # Your custom implementation
 ```
 
-### Run the generated MCP server
+Your FastAPI app will now have an MCP server mounted at the specified path, with all your API endpoints available as MCP tools.
 
-```bash
-fastapi-mcp run
-```
+### Legacy CLI Usage
 
-### Install the server for Claude
+The CLI is still available for backward compatibility:
 
 ```bash
+# Generate an MCP server from a FastAPI app
+fastapi-mcp generate app.py
+
+# Preview the generated server
+fastapi-mcp preview
+
+# Run the generated server
+fastapi-mcp run
+
+# Install the server for Claude
 fastapi-mcp install
 ```
 
 ## How It Works
 
-FastAPI-MCP automatically:
+FastAPI-MCP:
+
+1. Takes your FastAPI application
+2. Creates an MCP server instance
+3. Mounts the MCP server to your FastAPI app
+4. Extracts endpoint information from your OpenAPI schema
+5. Creates MCP tools that make HTTP requests to your API endpoints
+6. Preserves documentation and type information
+7. Registers the tools with the MCP server
 
-1. Discovers all FastAPI endpoints in your application
-2. Converts route handlers to MCP tools
-3. Maps request/response models to MCP schemas
-4. Preserves documentation and type information
-5. Generates a standalone MCP server that uses the official MCP Python SDK
-6. **Makes actual HTTP requests** to the underlying FastAPI endpoints
+## Examples
 
-## Example
+See the [examples](examples) directory for complete examples.
 
-Original FastAPI code:
+### Simple direct integration example:
 
 ```python
 from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
+from fastapi_mcp import add_mcp_server
 
-class Item(BaseModel):
-    name: str
-    price: float
-    is_offer: bool = None
+app = FastAPI(title="Simple API")
 
-@app.get("/items/{item_id}")
-def read_item(item_id: int, q: str = None):
-    """Get details for a specific item"""
-    return {"item_id": item_id, "q": q}
+@app.get("/hello/{name}")
+async def hello(name: str):
+    """Say hello to someone"""
+    return {"message": f"Hello, {name}!"}
 
-@app.put("/items/{item_id}")
-def update_item(item_id: int, item: Item):
-    """Update an item with new information"""
-    return {"item_id": item_id, "item": item}
-```
+# Add MCP server
+mcp_server = add_mcp_server(app, mount_path="/mcp")
 
-Generated MCP server:
-
-```python
-# Generated MCP server
-# Original FastAPI app: FastAPI
-
-from mcp.server import FastMCP
-import json
-import requests
-from typing import Dict, List, Optional, Union, Any
-try:
-    from pydantic import BaseModel
-except ImportError:
-    from pydantic.main import BaseModel
-
-class Item(BaseModel):
-    name: str
-    price: float
-    is_offer: Optional[bool] = None
-
-# Original handler: __main__.read_item
-# Original handler: __main__.update_item
-
-mcp = FastMCP("FastAPI")
-
-@mcp.tool()
-async def read_item(item_id: int, q: str = None) -> Any:
-    """Get details for a specific item
-
-    Original route: GET /items/{item_id}
-    """
-    # Original handler: __main__.read_item
-    url = f'http://localhost:8000/items/{item_id}'
-    params = {}
-    if q is not None:
-        params['q'] = q
-    response = requests.get(url, params=params)
-    response.raise_for_status()
-    return response.json()
-
-@mcp.tool()
-async def update_item(item_id: int, name: str, price: float, is_offer: bool = None) -> Any:
-    """Update an item with new information
-
-    Original route: PUT /items/{item_id}
-    """
-    # Original handler: __main__.update_item
-    url = f'http://localhost:8000/items/{item_id}'
-    item = Item(**{"name": name, "price": price, "is_offer": is_offer})
-    json_data = item.dict()
-    response = requests.put(url, json=json_data)
-    response.raise_for_status()
-    return response.json()
+# Optionally add custom tools
+@mcp_server.tool()
+async def get_current_time():
+    """Get the current server time"""
+    from datetime import datetime
+    return datetime.now().isoformat()
 
 if __name__ == "__main__":
-    # Run the MCP server
-    mcp.run()
+    import uvicorn
+    uvicorn.run(app, host="127.0.0.1", port=8000)
 ```
 
-## Integration with FastAPI
+## Connecting to the MCP Server
 
-The generated MCP server makes HTTP requests to your actual FastAPI server, which must be running separately. You can:
+Once your FastAPI app with MCP integration is running, you can connect to it with any MCP client, such as Claude:
 
-1. Run your FastAPI application normally (e.g., with `uvicorn app:app`)
-2. Generate the MCP server with a base URL pointing to your running FastAPI server
-3. Run the MCP server separately to provide MCP tools for LLMs
+1. Run your application
+2. In Claude, use the URL of your MCP server endpoint (e.g., `http://localhost:8000/mcp`)
+3. Claude will discover all available tools and resources automatically
 
-If your API requires authentication, you can customize the generated server code to include the necessary headers or tokens.
+## Advanced Configuration
 
-## Using with Claude
+FastAPI-MCP provides several options for advanced configuration:
 
-FastAPI-MCP makes it easy to use your API endpoints with Claude:
+```python
+mcp_server = add_mcp_server(
+    app,
+    mount_path="/mcp",
+    name="My Custom MCP Server",
+    description="Custom description for the MCP server",
+    capabilities={"streaming": True},  # Set MCP capabilities
+    serve_tools=True,  # Whether to serve API endpoints as MCP tools
+    base_url="https://api.example.com"  # Base URL for API requests
+)
+```
 
-1. Generate an MCP server from your FastAPI app
-2. Install the server: `fastapi-mcp install`
-3. Open Claude desktop app
-4. Your API endpoints will be available as tools to Claude
+You can also create and mount an MCP server separately:
 
-## Examples
+```python
+from fastapi_mcp import create_mcp_server, mount_mcp_server
+
+# Create an MCP server
+mcp_server = create_mcp_server(app, name="My MCP Server")
 
-For more examples, see the [examples](examples) directory.
+# Add custom tools
+@mcp_server.tool()
+async def custom_tool():
+    return "Custom tool result"
+
+# Mount the MCP server to the FastAPI app
+mount_mcp_server(app, mcp_server, mount_path="/mcp")
+```
 
 ## Requirements
 
 - Python 3.10+
 - FastAPI 0.100.0+
 - Pydantic 2.0.0+
-- mcp 1.3.0+
-- requests 2.25.0+
+- MCP 1.3.0+
 
 ## Contributing
 

examples/README.md

@@ -1,43 +1,66 @@
 # FastAPI-MCP Examples
 
-This directory contains examples of using FastAPI-MCP to generate MCP servers from FastAPI applications.
+This directory contains examples of using FastAPI-MCP to integrate Model Context Protocol (MCP) servers with FastAPI applications.
 
-## Sample App
+## Examples
 
-The `sample_app.py` file contains a simple FastAPI application with CRUD operations for an "Item" resource.
+### `simple_integration.py`
 
-To run the FastAPI application:
+Demonstrates the direct integration approach, where an MCP server is mounted directly to a FastAPI application.
 
-```bash
-python sample_app.py
-```
+Features:
+- FastAPI app with CRUD operations for items
+- MCP server mounted at `/mcp`
+- Automatic conversion of API endpoints to MCP tools
+- Custom MCP tool not based on an API endpoint
 
-To generate an MCP server from the sample app:
+To run this example:
 
 ```bash
-cd ..  # Go to the root directory
-python -m fastapi_mcp generate examples/sample_app.py
+# From the examples directory
+python run_example.py
+
+# Or directly
+uvicorn simple_integration:app --reload
 ```
 
-This will create a `mcp_server` directory with the generated MCP server.
+Then visit:
+- API documentation: http://localhost:8000/docs
+- MCP server endpoint: http://localhost:8000/mcp
 
-To preview the generated MCP server:
+### `sample_app.py`
 
-```bash
-python -m fastapi_mcp preview
-```
+Original example app to demonstrate the legacy code generation approach.
 
-To run the generated MCP server:
+To use with the CLI:
 
 ```bash
-python -m fastapi_mcp run
+# Generate MCP server
+fastapi-mcp generate sample_app.py
+
+# Preview the generated server
+fastapi-mcp preview
+
+# Run the sample app
+uvicorn sample_app:app --reload
+
+# In another terminal, run the MCP server
+fastapi-mcp run
 ```
 
-## How It Works
+## Using with Claude
+
+To connect Claude to your MCP server:
+
+1. Run any of the examples above
+2. In Claude, use the URL of your MCP server (e.g., `http://localhost:8000/mcp`)
+3. Claude will discover the available tools and resources automatically
+
+## What's Next?
 
-1. FastAPI-MCP discovers all endpoints in the FastAPI application
-2. It converts the endpoints to MCP tools
-3. It generates a standalone MCP server
-4. It preserves documentation and type information
+These examples demonstrate the basic functionality of FastAPI-MCP. For more advanced use cases, you can:
 
-The generated MCP server can be used with any MCP client, such as Claude. 
+- Add authentication to your API endpoints
+- Customize the MCP server with additional capabilities
+- Add custom MCP tools that go beyond your API functionality
+- Deploy your integrated app to a production environment 

examples/run_example.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+"""
+Run the FastAPI-MCP example.
+"""
+
+import uvicorn
+
+if __name__ == "__main__":
+    print("Starting FastAPI-MCP example...")
+    print("Visit http://localhost:8000/docs to see the API documentation")
+    print("Your MCP server is available at http://localhost:8000/mcp")
+
+    uvicorn.run(
+        "simple_integration:app",
+        host="127.0.0.1",
+        port=8000,
+        reload=True,
+    )