{"id":31060815,"url":"https://github.com/up2dul/books-fastapi-mcp","last_synced_at":"2026-04-13T01:02:08.938Z","repository":{"id":308123227,"uuid":"1031699317","full_name":"up2dul/books-fastapi-mcp","owner":"up2dul","description":"📚 Learning FastAPI with MCP integrations","archived":false,"fork":false,"pushed_at":"2025-09-14T16:26:41.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T18:29:27.733Z","etag":null,"topics":["docker","fastapi","fastmcp","mcp","python","sqlite","uv"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/up2dul/books-fastapi","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/up2dul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T07:45:59.000Z","updated_at":"2025-09-14T16:27:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"20ee8d93-af50-44d2-94bc-92429e40ca83","html_url":"https://github.com/up2dul/books-fastapi-mcp","commit_stats":null,"previous_names":["up2dul/books-fastapi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/up2dul/books-fastapi-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up2dul%2Fbooks-fastapi-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up2dul%2Fbooks-fastapi-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up2dul%2Fbooks-fastapi-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up2dul%2Fbooks-fastapi-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/up2dul","download_url":"https://codeload.github.com/up2dul/books-fastapi-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up2dul%2Fbooks-fastapi-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275245951,"owners_count":25430803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","fastmcp","mcp","python","sqlite","uv"],"created_at":"2025-09-15T10:48:00.738Z","updated_at":"2025-12-30T21:23:13.151Z","avatar_url":"https://github.com/up2dul.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📚 Books RESTful API\n\nA simple and elegant RESTful API for managing a books collection, built with **FastAPI**, **SQLite**, and **Docker**. This project serves as a learning exercise for building modern Python web APIs with automatic documentation, database migrations, and containerization.\n\n## ✨ Features\n\n- 🚀 **FastAPI** - High-performance, easy-to-use web framework\n- 📊 **SQLite** - Lightweight, file-based database\n- 🗃️ **SQLModel** - SQL databases in Python, designed for simplicity and type safety\n- 📖 **Automatic API Documentation** - Interactive docs with Scalar UI\n- 🤖 **MCP Integration** - Model Context Protocol server for AI assistant integration\n- 🐳 **Docker** - Containerized deployment\n- 🗄️ **Alembic** - Database migration management\n- 🎨 **UV** - Fast Python package manager\n- 🔧 **Ruff** - Lightning-fast Python linter and formatter\n\n## 🛠️ Tech Stack\n\n- **Backend**: FastAPI\n- **Database**: SQLite with SQLModel ORM\n- **Migration**: Alembic\n- **Package Management**: UV\n- **Containerization**: Docker\n- **Code Quality**: Ruff (linting \u0026 formatting)\n\n## 📋 API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/` | Welcome message and API info |\n| GET | `/scalar` | Interactive API documentation |\n| GET | `/books` | Get all books |\n| POST | `/books` | Create a new book |\n| GET | `/books/{id}` | Get a book by ID |\n| PUT | `/books/{id}` | Update a book |\n| DELETE | `/books/{id}` | Delete a book |\n\n## 🏗️ Project Structure\n\n```\nbooks-fastapi/\n├── app/\n│   ├── __init__.py\n│   ├── main.py          # FastAPI application entry point\n│   ├── database.py      # Database configuration\n│   ├── routes.py        # API route definitions\n│   ├── schemas.py       # Pydantic models for request/response\n│   └── settings.py      # Application settings\n├── migrations/          # Alembic database migrations\n│   ├── env.py\n│   └── versions/\n├── alembic.ini         # Alembic configuration\n├── books_mcp.py       # Model Context Protocol server\n├── pyproject.toml      # Project dependencies and configuration\n├── uv.lock            # Lock file for dependencies\n├── Dockerfile         # Docker container configuration\n├── Makefile          # Development commands\n└── README.md         # Project documentation\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.12+\n- [UV](https://docs.astral.sh/uv/) package manager\n- Docker (optional, for containerized deployment)\n\n### Local Development\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/up2dul/books-fastapi.git\n\n   # or if using ssh\n   git clone git@github.com:up2dul/books-fastapi.git\n\n   # open the project folder\n   cd books-fastapi\n   ```\n\n2. **Install dependencies**\n   ```bash\n   uv sync\n   ```\n\n3. **Run database migrations**\n   ```bash\n   make db-migrate\n   # or\n   uv run alembic upgrade head\n   ```\n\n4. **Start the development server**\n   ```bash\n   make dev\n   # or\n   uv run uvicorn app.main:app --reload\n   ```\n\n5. **Visit the API**\n   - API: http://localhost:8000\n   - Interactive Docs: http://localhost:8000/scalar\n   - OpenAPI Schema: http://localhost:8000/openapi.json\n\n### 🐳 Docker Deployment\n\n1. **Build the Docker image**\n   ```bash\n   docker build -t books-api .\n   ```\n\n2. **Run the container**\n   ```bash\n   docker run -p 8000:8000 books-api\n   ```\n\nThe API will be available at http://localhost:8000\n\n## 📝 Usage Examples\n\n### Create a Book\n```bash\ncurl -X POST \"http://localhost:8000/books\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"title\": \"The Devotion of Suspect X\",\n       \"author\": \"Keigo Higashino\",\n       \"year\": 2005,\n       \"genre\": \"Fiction\"\n     }'\n```\n\n### Get All Books\n```bash\ncurl -X GET \"http://localhost:8000/books\"\n```\n\n### Get a Specific Book\n```bash\ncurl -X GET \"http://localhost:8000/books/1\"\n```\n\n### Update a Book\n```bash\ncurl -X PUT \"http://localhost:8000/books/1\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"title\": \"The Devotion of Suspect X - Updated\",\n       \"year\": 2005\n     }'\n```\n\n### Delete a Book\n```bash\ncurl -X DELETE \"http://localhost:8000/books/1\"\n```\n\n## 🗄️ Database Schema\n\n### Book Model\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| id | Integer | Auto | Primary key |\n| title | String | Yes | Book title |\n| author | String | Yes | Author name |\n| year | Integer | Yes | Publication year |\n| genre | String | No | Book genre |\n\n## 🤖 Model Context Protocol (MCP) Integration\n\nThis project includes an MCP server that provides AI assistants with tools to interact with the Books API. The MCP server exposes the following tools:\n\n- `get_books()` - Retrieve all books\n- `get_book(book_id)` - Get a specific book by ID\n- `create_book(title, author, year, genre)` - Create a new book\n- `update_book(book_id, title, author, year, genre)` - Update an existing book\n- `delete_book(book_id)` - Delete a book by ID\n\n### Running the MCP Server\n\n1. **Start the FastAPI server first**\n   ```bash\n   make dev\n   ```\n\n2. **In a separate terminal, start the MCP server**\n   ```bash\n   make mcp\n   # or\n   uv run books_mcp.py\n   ```\n\nThe MCP server will run on port 8001 and will be available for AI assistants to connect and interact with your books database through the defined tools.\n\n## 🔧 Development Commands\n\n```bash\n# Start development server with auto-reload\nmake dev\n\n# Start MCP server (requires API server to be running)\nmake mcp\n\n# Format code and fix linting issues\nmake format\n\n# Run database migrations\nmake db-migrate\n\n# Create new migration\nuv run alembic revision --autogenerate -m \"description\"\n\n# Check code quality\nuv run ruff check\nuv run ruff format --check\n```\n\n## 🌟 Learning Outcomes\n\nThis project demonstrates:\n\n- **FastAPI Framework**: Building REST APIs with automatic documentation\n- **Database Integration**: Using SQLModel for database operations\n- **Migration Management**: Handling database schema changes with Alembic\n- **Modern Python**: Type hints, Pydantic models, and async/await patterns\n- **API Design**: RESTful principles and HTTP status codes\n- **MCP Integration**: Creating Model Context Protocol servers for AI assistant integration\n- **Containerization**: Docker best practices for Python applications\n- **Development Workflow**: Code formatting, linting, and development automation\n\n## 🔗 Resources\n\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [SQLModel Documentation](https://sqlmodel.tiangolo.com/)\n- [UV Documentation](https://docs.astral.sh/uv/)\n- [Alembic Documentation](https://alembic.sqlalchemy.org/)\n- [Docker Documentation](https://docs.docker.com/)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fup2dul%2Fbooks-fastapi-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fup2dul%2Fbooks-fastapi-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fup2dul%2Fbooks-fastapi-mcp/lists"}