mirror of
https://github.com/tadata-org/fastapi_mcp.git
synced 2025-04-13 23:32:11 +03:00
update docs
This commit is contained in:
Shahar Abramov
@@ -2,46 +2,58 @@
|
||||
|
||||
First off, thank you for considering contributing to FastAPI-MCP!
|
||||
|
||||
## Development Setup
|
||||
|
||||
1. Make sure you have Python 3.10+ installed
|
||||
2. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip
|
||||
3. Fork the repository
|
||||
4. Clone your fork and set up the development environment:
|
||||
|
||||
```bash
|
||||
# Clone your fork
|
||||
git clone https://github.com/YOUR-USERNAME/fastapi_mcp.git
|
||||
cd fastapi-mcp
|
||||
|
||||
# Create a virtual environment with uv (recommended)
|
||||
uv venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
|
||||
# Install development dependencies with uv
|
||||
uv add -e ".[dev]"
|
||||
|
||||
# Alternatively, using pip
|
||||
# python -m venv venv
|
||||
# source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
# pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
## Development Process
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Make your changes
|
||||
4. Run the tests (`pytest`)
|
||||
5. Format your code (`black .` and `isort .`)
|
||||
6. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||||
7. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
8. Open a Pull Request
|
||||
|
||||
## Setting Up Development Environment
|
||||
|
||||
```bash
|
||||
# Clone your fork
|
||||
git clone https://github.com/tadata-org/fastapi_mcp
|
||||
cd fastapi-mcp
|
||||
|
||||
# Create a virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install development dependencies
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
4. Run type checking (`uv run mypy .`)
|
||||
5. Run the tests (`uv run pytest`)
|
||||
6. Format your code (`uv run ruff check .` and `uv run ruff format .`)
|
||||
7. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||||
8. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
9. Open a Pull Request
|
||||
|
||||
## Code Style
|
||||
|
||||
We use the following tools to ensure code quality:
|
||||
|
||||
- **Black** for code formatting
|
||||
- **isort** for import sorting
|
||||
- **ruff** for linting
|
||||
- **mypy** for type checking
|
||||
|
||||
Please make sure your code passes all checks before submitting a pull request:
|
||||
|
||||
```bash
|
||||
black .
|
||||
isort .
|
||||
# Using uv
|
||||
uv run ruff check .
|
||||
uv run mypy .
|
||||
|
||||
# Or directly if tools are installed
|
||||
ruff check .
|
||||
mypy .
|
||||
```
|
||||
@@ -51,9 +63,23 @@ mypy .
|
||||
We use pytest for testing. Please write tests for any new features and ensure all tests pass:
|
||||
|
||||
```bash
|
||||
# Using uv
|
||||
uv run pytest
|
||||
|
||||
# Or directly
|
||||
pytest
|
||||
```
|
||||
|
||||
## Project Architecture
|
||||
|
||||
FastAPI-MCP uses a direct integration approach to add MCP functionality to FastAPI applications:
|
||||
|
||||
1. The `server.py` module handles creating and mounting MCP servers to FastAPI apps
|
||||
2. The `http_tools.py` module converts FastAPI endpoints to MCP tools
|
||||
3. All integration happens at runtime - there is no code generation involved
|
||||
|
||||
When contributing, please keep this architecture in mind and ensure your changes maintain the seamless integration experience.
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Ensure your code follows the style guidelines of the project
|
||||
|
||||
57
INSTALL.md
57
INSTALL.md
@@ -1,57 +0,0 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide will help you install and set up FastAPI-MCP on your system.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.10 or higher
|
||||
- pip (Python package installer)
|
||||
|
||||
## Installation from PyPI (Recommended)
|
||||
|
||||
The recommended way to install FastAPI-MCP is directly from [PyPI](https://pypi.org/project/fastapi-mcp/):
|
||||
|
||||
```bash
|
||||
pip install fastapi-mcp
|
||||
```
|
||||
|
||||
This will install the latest stable version of FastAPI-MCP along with all its dependencies.
|
||||
|
||||
## Installation from Source
|
||||
|
||||
If you need the latest development version or want to contribute to the project, you can install FastAPI-MCP from source:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/tadata-org/fastapi_mcp.git
|
||||
cd fastapi-mcp
|
||||
|
||||
# Install the package
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
To verify that FastAPI-MCP is installed correctly, run:
|
||||
|
||||
```bash
|
||||
fastapi-mcp --help
|
||||
```
|
||||
|
||||
You should see the help message for the FastAPI-MCP CLI.
|
||||
|
||||
## Installing Development Dependencies
|
||||
|
||||
If you want to contribute to FastAPI-MCP or run the tests, you can install the development dependencies:
|
||||
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
To run the tests, make sure you have installed the development dependencies, then run:
|
||||
|
||||
```bash
|
||||
pytest
|
||||
```
|
||||
140
README.md
140
README.md
@@ -16,7 +16,13 @@ A zero-configuration tool for integrating Model Context Protocol (MCP) servers w
|
||||
|
||||
## Installation
|
||||
|
||||
You can install FastAPI-MCP directly from [PyPI](https://pypi.org/project/fastapi-mcp/):
|
||||
We recommend using [uv](https://docs.astral.sh/uv/), a fast Python package installer:
|
||||
|
||||
```bash
|
||||
uv add fastapi-mcp
|
||||
```
|
||||
|
||||
Alternatively, you can install with pip:
|
||||
|
||||
```bash
|
||||
pip install fastapi-mcp
|
||||
@@ -24,9 +30,7 @@ pip install fastapi-mcp
|
||||
|
||||
For detailed installation instructions and alternative methods, see [INSTALL.md](INSTALL.md).
|
||||
|
||||
## Usage
|
||||
|
||||
### Direct integration (Recommended)
|
||||
## Basic Usage
|
||||
|
||||
The simplest way to use FastAPI-MCP is to add an MCP server directly to your FastAPI application:
|
||||
|
||||
@@ -34,67 +38,50 @@ The simplest way to use FastAPI-MCP is to add an MCP server directly to your Fas
|
||||
from fastapi import FastAPI
|
||||
from fastapi_mcp import add_mcp_server
|
||||
|
||||
# Create your FastAPI app
|
||||
# Your FastAPI app
|
||||
app = FastAPI()
|
||||
|
||||
# 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}
|
||||
|
||||
# Add an MCP server to your app
|
||||
mcp_server = add_mcp_server(
|
||||
# Mount the MCP server to your app
|
||||
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
|
||||
)
|
||||
```
|
||||
|
||||
That's it! Your auto-generated MCP server is now available at `https://app.base.url/mcp`.
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
FastAPI-MCP provides several ways to customize and control how your MCP server is created and configured. Here are some advanced usage patterns:
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
from fastapi_mcp import add_mcp_server
|
||||
|
||||
app = FastAPI()
|
||||
|
||||
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
|
||||
describe_all_responses=True, # False by default. Include all possible response schemas in tool descriptions, instead of just the successful response.
|
||||
describe_full_response_schema=True # False by default. Include full JSON schema in tool descriptions, instead of just an LLM-friendly response example.
|
||||
)
|
||||
|
||||
# Optionally add custom MCP tools
|
||||
# Add custom tools in addition to existing APIs.
|
||||
@mcp_server.tool()
|
||||
async def get_item_count() -> int:
|
||||
"""Get the total number of items in the database."""
|
||||
return 42 # Your custom implementation
|
||||
async def get_server_time() -> str:
|
||||
"""Get the current server time."""
|
||||
from datetime import datetime
|
||||
return datetime.now().isoformat()
|
||||
```
|
||||
|
||||
Your FastAPI app will now have an MCP server mounted at the specified path, with all your API endpoints available as MCP tools.
|
||||
|
||||
### Legacy CLI Usage
|
||||
|
||||
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:
|
||||
|
||||
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
|
||||
|
||||
## Examples
|
||||
|
||||
See the [examples](examples) directory for complete examples.
|
||||
|
||||
### Simple direct integration example:
|
||||
### Simple integration example:
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
@@ -130,49 +117,30 @@ Once your FastAPI app with MCP integration is running, you can connect to it wit
|
||||
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
|
||||
|
||||
## Advanced Configuration
|
||||
## Development and Contributing
|
||||
|
||||
FastAPI-MCP provides several options for advanced configuration:
|
||||
If you're interested in contributing to FastAPI-MCP:
|
||||
|
||||
```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
|
||||
)
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/tadata-org/fastapi_mcp.git
|
||||
cd fastapi_mcp
|
||||
|
||||
# Create a virtual environment and install dependencies with uv
|
||||
uv venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
uv add -e ".[dev]"
|
||||
|
||||
# Run tests
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
You can also create and mount an MCP server separately:
|
||||
|
||||
```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")
|
||||
|
||||
# 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")
|
||||
```
|
||||
For more details about contributing, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.10+
|
||||
- FastAPI 0.100.0+
|
||||
- Pydantic 2.0.0+
|
||||
- MCP 1.3.0+
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
|
||||
- uv
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -1,66 +0,0 @@
|
||||
# FastAPI-MCP Examples
|
||||
|
||||
This directory contains examples of using FastAPI-MCP to integrate Model Context Protocol (MCP) servers with FastAPI applications.
|
||||
|
||||
## Examples
|
||||
|
||||
### `simple_integration.py`
|
||||
|
||||
Demonstrates the direct integration approach, where an MCP server is mounted directly to a FastAPI application.
|
||||
|
||||
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 run this example:
|
||||
|
||||
```bash
|
||||
# From the examples directory
|
||||
python run_example.py
|
||||
|
||||
# Or directly
|
||||
uvicorn simple_integration:app --reload
|
||||
```
|
||||
|
||||
Then visit:
|
||||
- API documentation: http://localhost:8000/docs
|
||||
- MCP server endpoint: http://localhost:8000/mcp
|
||||
|
||||
### `sample_app.py`
|
||||
|
||||
Original example app to demonstrate the legacy code generation approach.
|
||||
|
||||
To use with the CLI:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
## 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?
|
||||
|
||||
These examples demonstrate the basic functionality of FastAPI-MCP. For more advanced use cases, you can:
|
||||
|
||||
- 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
|
||||
Reference in New Issue
Block a user