Sneaker Catalog — Data Layer, MCP Server & Agent

A small e-commerce catalog for sneakers, built in three layers:

1. Data layer — Postgres + pgvector, with keyword and semantic search over products.
2. MCP server — exposes the catalog as tools (search, get_product_details, get_stock) over the Model Context Protocol.
3. Agent — a CLI chat agent that connects to the MCP server and answers questions about the catalog purely by calling those tools.

Architecture

┌─────────────┐   MCP (stdio)   ┌──────────────┐        ┌────────────────┐
│  agent/cli   │ ──────────────▶ │ mcp_server   │ ─────▶ │ Postgres +     │
│ (OpenAI llm) │ ◀────────────── │ (tool calls) │ ◀───── │ pgvector       │
└─────────────┘                 └──────────────┘        └────────────────┘

• db/ — plain Python functions (search_products, get_product, check_stock, filter_products) that query Postgres directly.
• mcp_server/ — wraps those functions as MCP tools using the official Python MCP SDK.
• agent/ — a REPL that spawns the MCP server as a subprocess, converts its tool schemas to OpenAI's function-calling format, and runs the request → tool-call → result loop until the model has a final answer.

Search is hybrid: full-text keyword ranking (Postgres tsvector) blended with semantic similarity (OpenAI embeddings + pgvector cosine distance).

Prerequisites

• Docker (recommended path), or Python 3.14 + a local Postgres with the vector extension
• An OpenAI API key with access to an embeddings model (text-embedding-3-small) and a chat model (e.g. gpt-5-mini)

Quickstart (Docker)

make setup   # cp .env.example .env — then edit it: POSTGRES_* / OPENAI_API_KEY
make up      # starts Postgres, seeds the catalog
make logs    # confirm "Seed complete." (Ctrl+C to stop tailing)

make agent   # chat with the catalog

agent (and mcp-server) depend on seed, so make agent re-runs the seed step first on every invocation. Seeding checks whether the catalog is already populated and skips instantly if so, so this is fast and harmless.

Type a question at the > prompt. Type exit (or Ctrl+D) to quit.

Other services

make mcp-server   # run the MCP server standalone, e.g. to attach MCP Inspector
make inspector    # run MCP Inspector against the containerized server

The MCP server uses stdio transport, so it only runs attached to a terminal — it's excluded from make up's default services (behind the tools compose profile) to avoid a crash loop when started detached.

Run make help to see all available commands, or make down to stop everything.

Quickstart (local, no Docker)

make venv       # create venv + install requirements
make db-up      # just the Postgres container
make seed-local # seed the catalog once

make agent-local  # chat with the agent

To test the MCP server directly with Inspector:

source venv/bin/activate
npx @modelcontextprotocol/inspector python -m mcp_server.server

Project layout

db/
  schema.sql      products, variants, inventory, prices + pgvector/tsvector indexes
  seed.py         idempotent catalog seeding (embeds descriptions via OpenAI)
  search.py       hybrid keyword + semantic search
  product.py      get_product() — product + all variants
  stock.py        check_stock() — inventory by SKU
  filters.py      SQL filtering by category / price

mcp_server/
  server.py       MCP tool definitions (search, get_product_details, get_stock)

agent/
  cli.py          interactive chat agent (OpenAI function-calling + MCP client)

docker-compose.yml   db, seed, mcp-server, agent services
Dockerfile           shared image for seed / mcp-server / agent
Makefile             `make help` for all available commands
agent-start.sh       local (non-Docker) launcher for the agent

Environment variables

Variable	Used by	Notes
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB	db, all Python services
POSTGRES_HOST / POSTGRES_PORT	db connections	defaults to localhost:5432; Docker services override POSTGRES_HOST=db
OPENAI_API_KEY	seeding (embeddings), search (query embeddings), agent (chat)

See .env.example for a template.