Notatki RAG — przykładowy serwer MCP

Serwer MCP (Model Context Protocol) w Pythonie, który łączy LLM + bazę danych w pełny przepływ RAG zbudowany na LangChain (LCEL). Notatki trafiają do PostgreSQL (system zapisu), ich treść+embeddingi do ChromaDB, a odpowiedzi generuje Google Gemini. Ćwiczenie do kursu IBM Build AI Agents using MCP.

Architektura

Warstwa	Rola	Plik
PostgreSQL	system zapisu dla notatek (notes, CRUD, lista)	db.py, schema.sql
ChromaDB (langchain-chroma)	vector store: treść + embeddingi → retriever	rag_chain.py
Gemini (langchain-google-genai)	embeddingi (gemini-embedding-001) + generacja (gemini-2.5-flash)	rag_chain.py
LCEL	łańcuch RAG: retriever | prompt | llm | parser	rag_chain.py
MCP / FastMCP	wystawia narzędzia klientowi MCP (stdio)	server.py

Przepływ pytania (ask) jako łańcuch LCEL:

{"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt | llm | StrOutputParser()

retriever (Chroma) zwraca dopasowane notatki → format_docs skleja kontekst → Gemini odpowiada tylko na jego podstawie. PostgreSQL pozostaje źródłem prawdy dla treści i pozwala odbudować indeks (rag_chain.reindex_all).

Narzędzia MCP

Narzędzie	Opis
add_note(title, content)	zapis do Postgresa + embedding do Chromy
search_notes(query, top_k=3)	wyszukiwanie semantyczne (tytuł, fragment, dystans)
ask(question, top_k=3)	pełny RAG: retrieval + odpowiedź Gemini
list_notes()	lista wszystkich notatek
summarize_note(note_id)	streszczenie notatki przez Gemini
delete_note(note_id)	usuwa z Postgresa i z Chromy

Dodatkowo zasób notes://{id} zwraca treść notatki.

Wymagania

• Python ≥ 3.12 (przetestowane na 3.14)
• PostgreSQL działający lokalnie (tu: Homebrew postgresql@15 na :5432)
• Klucz API Gemini: https://aistudio.google.com/apikey

Setup

# 1. Zależności (w aktywnym venv)
python -m pip install -e .

# 2. Baza danych (jeśli jeszcze nie istnieje)
createdb notes_mcp

# 3. Konfiguracja
cp .env.example .env
#   → wpisz GEMINI_API_KEY w .env
#   → sprawdź DATABASE_URL (domyślnie konto bieżącego usera, trust na localhost)

Tabela notes tworzy się automatycznie przy starcie serwera (db.init_schema()). Można też ręcznie: psql -d notes_mcp -f schema.sql.

Uruchomienie i test

Z inspektorem MCP (interaktywny GUI w przeglądarce — najwygodniej do nauki):

mcp dev server.py

W Inspectorze (zakładka Tools):

1. add_note("Python GIL", "GIL to globalna blokada interpretera CPython...")
2. dodaj jeszcze 2–3 notatki na różne tematy,
3. search_notes("czym jest GIL") → trafienie wskazuje notatkę o GIL,
4. ask("wyjaśnij GIL na podstawie moich notatek") → odpowiedź ugruntowana w treści,
5. summarize_note(1), potem delete_note(1) → sprawdź spójność Postgres ↔ Chroma.

Podpięcie do klienta MCP (np. Claude Desktop) — wpis w configu:

{
  "mcpServers": {
    "notes-rag": {
      "command": "/pełna/ścieżka/.venv/bin/python",
      "args": ["/pełna/ścieżka/server.py"]
    }
  }
}

Pliki

server.py        # FastMCP + narzędzia MCP (entry point)
rag_chain.py     # LangChain: Gemini + Chroma + łańcuch LCEL (RAG)
db.py            # PostgreSQL (psycopg3) — system zapisu
schema.sql       # tabela notes
pyproject.toml   # zależności
.env(.example)   # konfiguracja

Poza zakresem (świadomie)

Chunking długich dokumentów, autoryzacja/multi-user, testy automatyczne — ćwiczenie skupia się na integracji RAG + MCP.