Product CRUD — FastAPI + Strawberry GraphQL + MCP

A small learning/demo project with one CRUD entity (Product) and one shared business-logic layer (app/crud.py). The same business logic is exposed through both:

• /graphql — a Strawberry GraphQL API
• /mcp — MCP tools and a resource for AI hosts

This repo uses SQLite by default so it runs with zero external services. It is also designed so the database backend can be swapped later, for example to Oracle via python-oracledb.

Why this project exists

The main goal is to show how to keep core business logic separate from transport and API adapters:

• app/crud.py contains plain CRUD functions and SQLAlchemy access
• app/graphql_schema.py wraps that logic in a GraphQL schema
• app/mcp_server.py wraps the same logic in MCP tools and resources
• app/main.py mounts both the GraphQL router and a Streamable HTTP MCP app

That makes it easy for the same operations to support different clients and deployment modes without duplicating business rules.

Project layout

app/
  database.py         SQLAlchemy engine/session setup
  models.py           Product ORM model
  crud.py             Plain CRUD functions, used by both interfaces
  graphql_schema.py   Strawberry GraphQL query/mutation schema
  mcp_server.py       MCP tools and resource adapter
  main.py             FastAPI app mounting GraphQL and MCP
Dockerfile
docker-compose.yml
k8s/deployment.yaml
k8s/service.yaml
README.md
requirements.txt
.gitignore

Key files for contributors and tools

• app/crud.py — core business logic for products
• app/models.py — SQLAlchemy Product model
• app/database.py — database engine and session setup
• app/graphql_schema.py — GraphQL query/mutation definitions
• app/mcp_server.py — MCP tool/resource definitions
• app/main.py — FastAPI app and route mounting
• Dockerfile / docker-compose.yml — containerized deployment

Prerequisites

• macOS with Python 3.11+ installed
• Docker and Docker Compose installed if you want to run in Docker
• Optional: uv or claude if using the MCP CLI/Inspector workflows

Run locally on macOS

From the repository root:

cd "/Users/sauvi/Developer/2026 Job Switch/Coding Main Folder/mcp-crud-demo"
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Start the app on a specific host and port:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

If you want a different port, replace 8000 with any available port.

Verify it is running

Open in your browser:

• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/graphql

Example GraphQL mutation:

mutation {
  createProduct(name: "Keyboard", description: "Mechanical", price: 49.99, quantity: 10) {
    id
  }
}

Then query:

query {
  products {
    id
    name
    price
    quantity
  }
}

Run in Docker

Build and start the service with Docker Compose:

docker compose up --build

Then open:

• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/graphql
• http://127.0.0.1:8000/mcp

Optional persistence

By default the SQLite file lives inside the container and resets when the container is rebuilt. To keep data across restarts, uncomment or add a volume mapping in docker-compose.yml:

services:
  product-crud-mcp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - product-data:/app

volumes:
  product-data:

Run with MCP tools

Option A — MCP Inspector

uv run mcp dev app/mcp_server.py

This opens a browser UI where you can call create_product, list_products, update_product, and delete_product.

Option B — Claude Desktop / Claude Code

uv run mcp install app/mcp_server.py

or for Claude Code:

claude mcp add product-crud -- uv run --with "mcp[cli]" mcp run /absolute/path/to/app/mcp_server.py

Option C — Mounted Streamable HTTP

With uvicorn app.main:app running, the same MCP tools are available at http://127.0.0.1:8000/mcp.

Kubernetes

To build the image and deploy to Kubernetes:

docker build -t product-crud-mcp:latest .
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl port-forward svc/product-crud-mcp 8000:80

The K8s YAML includes /health readiness and liveness probes.

Swap in Oracle

To use Oracle instead of SQLite, update app/database.py:

from sqlalchemy import create_engine
DATABASE_URL = "oracle+oracledb://user:password@host:1521/?service_name=FREEPDB1"
engine = create_engine(DATABASE_URL)

Add oracledb to requirements.txt. No other application code needs to change.

Notes for new contributors or AI tools

• The repository is intentionally small and designed for exploration.
• app/crud.py is the single source of truth for product operations.
• GraphQL and MCP are adapters on top of that single core.
• If you want to add a new interface, follow the same pattern: keep logic in crud.py and add a thin adapter layer.
• Start by reading app/main.py, app/crud.py, and app/mcp_server.py.

Support files

• .gitignore excludes virtual environments, editor settings, caches, and local SQLite files.
• requirements.txt lists runtime dependencies.
• Dockerfile and docker-compose.yml define container behavior.