/fastapi-crud-mcp

A minimal example of FastAPI with MCP library fastapi-mcp

Primary LanguagePythonMIT LicenseMIT

codecov Python Version License: MIT

FastAPI CRUD MCP

A minimal CRUD API for “items,” built with FastAPI and exposed as MCP tools via FastAPI-MCP. Includes a scenario-driven client harness using PydanticAI and Rich.

🚀 Features

  • FastAPI: high-performance HTTP API
  • SQLAlchemy + Pydantic: ORM models + input/output schemas
  • FastAPI-MCP: auto-expose your endpoints as MCP tools (/mcp/tools, /mcp/events)
  • Rich CLI: beautiful, colored terminal output for scenario runs
  • Scenario Runner: client harness that drives and validates your API via PydanticAI agents
  • SQLite backend for demo; easily swap to PostgreSQL, MySQL, etc.

📦 Project Layout


.
├── backend
│   ├── server
│   │   ├── main.py            # FastAPI + FastAPI-MCP wiring
│   │   ├── models.py          # SQLAlchemy + Pydantic schemas
│   │   ├── routes.py          # CRUD endpoints
│   │   ├── crud.py            # DB operations
│   │   ├── db.py              # session & engine
│   │   └── logger.py          # stdlib logging setup
│   └── client
│       ├── scenarios.py       # Scenario definitions
│       └── main.py            # run\_scenarios.py harness
├── .env                       # example environment variables
├── pyproject.toml             # Project dependencies
└── README.md                  # this file

⚙️ Installation & Setup

  1. Clone & enter directory

    git clone https://github.com/yourusername/fastapi-crud-mcp.git
cd fastapi-crud-mcp

  2. Create & activate a virtualenv

    uv venv
source .venv/bin/activate

  3. Install dependencies

    uv sync

  4. Environment variables Copy the example and adjust if needed:

    cp .env.example .env
    MCP_HOST_URL='http://127.0.0.1:8000/mcp'

LLM_PROVIDER='openai'
LLM_MODEL_NAME='gpt-4o-mini'
LLM_MODEL=${LLM_PROVIDER}:${LLM_MODEL_NAME}

OPENAI_API_KEY=sk-proj-your-api-key-here

🏃 Running the Server

docker compose up -d --build
  • API docs → http://localhost:8000/docs
  • OpenAPI JSON → http://localhost:8000/openapi.json

🤖 Running the Scenario Client

python3 -m backend.client.main

This harness will:

  1. Load your .env settings
  2. Spin up a PydanticAI agent against MCP_HOST_URL
  3. Execute each scenario (create/list/get/update/delete)
  4. Display rich panels for prompts & outputs

🚨 Notes & Tips

  • Switch DB: edit backend/server/db.py for PostgreSQL or MySQL.
  • Add auth: protect /mcp or /api via FastAPI dependencies.
  • Extend scenarios: drop new entries into backend/client/scenarios.py.
  • Production: add Alembic for migrations, and monitor with Prometheus.

🤝 Contributing

  1. Fork 🔱

  2. Create a feature branch:

    git checkout -b feature/my-feature

  3. Commit & push:

    git commit -am "Add awesome feature"
git push origin feature/my-feature

  4. Open a PR and we’ll review!

📄 License

This project is MIT-licensed—see the LICENSE file for details.