Acid-base/FastMCP-Proper

This repository provides a modern Python project template with a functional FastAPI REST API, designed for efficient development with uv, ruff, mypy, pytest, and Git hooks powered by pre-commit. It demonstrates best practices for building production-ready Python applications with robust testing, containerization, and CI/CD integration.
Features
* **REST API with FastAPI:** Ready-to-use API with data validation using Pydantic models.
* **Docker & Docker Compose:** Production-ready containerization with multi-stage builds.
* **uv for Dependency Management:** Fast and efficient dependency resolution and virtual environment management.
* **ruff for Linting and Formatting:** Enforces consistent code style, catches errors early, and provides auto-fixing capabilities.
* **mypy for Type Checking:** Adds static typing to your Python code, preventing type-related errors.
* **pytest for Testing:** Comprehensive test suite with unit, API, and integration tests.
* **pre-commit for Git Hooks:** Automates code quality checks before every commit.
* **GitHub Actions Workflow:** Ready-to-use CI pipeline for testing and quality assurance.
* **Dev Container Support:** Included configuration for instant development in VS Code or GitHub Codespaces.
Project Structure
API Features
The included FastAPI application provides:
* Data processing API with input validation
* Proper error handling and status codes
* CORS middleware for cross-origin requests
* Automatic OpenAPI documentation (available at /docs)
* Pydantic models for request/response schema validation
Getting Started
You can choose one of two approaches to set up this project:
Option 1: Using Dev Containers (Recommended)
If you have VS Code with the Dev Containers extension or GitHub Codespaces, you can get started quickly without any local setup:
1. **VS Code + Dev Containers:**
- Clone this repository
- Open the repository folder in VS Code
- When prompted "Reopen in Container", click "Reopen in Container"
- (Alternatively, press F1, type "Reopen in Container" and select the option)
2. **GitHub Codespaces:**
- Click the "Code" button on the GitHub repository
- Select the "Codespaces" tab
- Click "Create codespace on main"
The container includes all necessary tools and dependencies, properly configured and ready to use.
Option 2: Using Docker Compose
To run the API using Docker Compose:
Option 3: Local Setup with Linuxbrew/Homebrew
Before cloning the repository, make sure you have Linuxbrew installed (or Homebrew on macOS).
Windows/WSL Setup
1. **Install WSL:** Follow the official Microsoft instructions to install WSL and choose a Linux distribution (e.g., Ubuntu).
2. **Open a *Direct* WSL Terminal:**
* **Do NOT use wsl from a Windows terminal (like PowerShell or Command Prompt).**
* **In VS Code:** Open a *new* integrated terminal by clicking the "+" button on the terminals tab, and select your WSL distribution (e.g., "Ubuntu", "Debian") from the dropdown menu.
* **From Start Menu:** Alternatively, launch your WSL distribution's terminal directly from the Windows Start Menu (e.g., "Ubuntu", "Debian").
**All subsequent steps in this section must be executed within this *direct* WSL terminal.**
3. **Install Base Dependencies (Within WSL):**
4. **Install Linuxbrew:**
5. **Add Linuxbrew to PATH:**
Add the following lines to your ~/.bashrc or ~/.zshrc (depending on your shell):
Then run source ~/.bashrc or source ~/.zshrc.
6. **Install Python via Linuxbrew:** brew install python
macOS
1. **Install Homebrew:** If you don't have it already, install Homebrew by running the following command in the terminal:
2. **Install Python via Homebrew:** brew install python
Linux
1. **Install Linuxbrew:** Follow the instructions on the Linuxbrew homepage: https://brew.sh/
2. **Install Python via Linuxbrew:** brew install python