diff --git a/snippets/1041_ResearchAssisstant/data/phd-master.zip b/snippets/1041_ResearchAssisstant/data/phd-master.zip new file mode 100644 index 0000000..1ddead9 Binary files /dev/null and b/snippets/1041_ResearchAssisstant/data/phd-master.zip differ diff --git a/snippets/1041_ResearchAssisstant/index.md b/snippets/1041_ResearchAssisstant/index.md new file mode 100644 index 0000000..3961c6b --- /dev/null +++ b/snippets/1041_ResearchAssisstant/index.md @@ -0,0 +1,73 @@ +--- +layout: default +codename: 1041_MCPServerforResearch +title: MCP szerver fejlesztése GitHub integrációhoz, kutatási eredmények rendszerezett rögzítésére +tags: snippets mieset +authors: Dongó Tamás +--- + +# MCP szerver fejlesztése GitHub integrációhoz, kutatási eredmények rendszerezett rögzítésére + +A feladat egy olyan személyes AI kutatási asszisztens infrastruktúra kialakítása volt egy PhD projekthez, amely lehetővé teszi a természetes nyelvű beszélgetést egy LLM-mel (pl. Claude), miközben a beszélgetés során hozott döntések és új ötletek automatikusan (de jóváhagyás után) bekerülnek a kutatás hivatalos, GitHub-on tárolt Markdown dokumentációjába. Ehhez egy privát MCP (Model Context Protocol) szerver készült, amit a render.com szerverén kereszül köti össze a kliens által generált eszközhívásokat a GitHub repóval. + +Ebben az esettanulmányban részletesen bemutatom, hogyan használtam fel a GitHub Copilot Agentet a rendszer programozására, milyen akadályokba ütközött az MI és hogyan oldotta meg azokat, majd azt is, hogyan néz ki a rendszer a mindennapi használatban immár több hónap távlatából. + +## A kódoló ágens (Copilot Agent) működésének mélyreható elemzése + +A fejlesztés során megfigyeltem, hogy az MI ágens hogyan "gondolkodik" és hajtja végre a feladatokat. Az alábbi kulcsfontosságú tapasztalatokat szereztem: + +### 1. A robusztus, több szekciós promptolás ereje +Az Agentnek egy hatalmas, strukturált promptot adtam át. Ebben nemcsak a feladatot írtam le, hanem kategóriákba szedtem a peremfeltételeket (`HIGH-LEVEL ARCHITECTURE`, `CORE DESIGN PRINCIPLE`, `MCP TOOLS`, `SAFETY / RESEARCH INTEGRITY`, `OBSERVABILITY`, `MVP FIRST`, `HOW I WANT YOU TO WORK`). + +**A tanulság:** Mivel kifejezetten tiltottam dolgokat (*"Do NOT build Kubernetes"*, *"Do NOT build a microservice architecture"*), az Agent nem kezdett el "kód-kúszásba" (scope creep). A keretek pontos kijelölése miatt egy letisztult, egyetlen FastAPI fájlból álló alkalmazást generált, ami pontosan azt tudta, amit kértem. + +### 2. Belső állapotkezelés és ToDo listák +Az Agent a munkát nem azonnali kódolással kezdte. Először egy beépített `manage_todo_list` tool-t hívott meg, amiben felvázolta a saját feladatait: +1. Inspect repository contents +2. Propose architecture brief +3. Create minimal project scaffold +4. Implement MVP... stb. + +**A tanulság:** Az Agentek számára elengedhetetlen egy belső feladatlista. Ez segített a modellnek abban, hogy a 7 lépéses feladatot ne felejtse el a kontextusablak növekedésével sem. A folyamat során (amikor például a teszteket implementálta), visszanyúlt ehhez a listához és frissítette a státuszokat. + +### 3. Önjavító mechanizmus az útvonalaknál +Az egyik legérdekesebb hiba az első fájlgeneráláskor (`requirements.txt`) történt. Az Agent az `apply_patch` eszközt relatív útvonallal próbálta meghívni. A rendszer ezt a hibát dobta: +> `ERROR while calling tool: Invalid input path: requirements.txt. Be sure to use an absolute path. Please check your input and try again.` + +**A megfejtés:** Az Agent nem állt le, és nem kérte a segítségemet. Létrehozott egy belső gondolkodási (`thinking`) blokkot, majd újra meghívta a `list_dir` tool-ból korábban megismert abszolút útvonalat (`c:\Users\Tamas\Desktop\PhD\AI EDIH\1041_ResearchAssisstant\requirements.txt`). **Ez jól mutatja, hogy a modern kódoló ágensek képesek a saját eszköz-hibáik értelmezésére és emberi beavatkozás nélküli javítására.** + +### 4. Egyéb megfigyelések: tesztelés és proaktív implementáció +Az Agent a tesztelésnél is önállóan gondolkodott: mivel tudta, hogy a GitHub API teszteléséhez token kellene (ami a CI környezetben alapból nincs beállítva), nem bonyolult mock-osztályokat gyártott, hanem a saját maga által korábban implementált `LOCAL_REPO_PATH` fallback-et használta fel egy önálló, külső API-hívás nélküli tesztkörnyezet felépítésére. + +Emellett a prompt `OBSERVABILITY` szekciójában leírt, de konkrétan meg nem fogalmazott igényt ("minden módosítás legyen visszakövethető") proaktívan egy strukturált JSON-lines audit-log függvénnyé alakította. + +## Korábbi beszélgetések importálása kötegelt feldolgozással + +A rendszer egyik legnagyobb gyakorlati próbája nem az élő, valós idejű használat volt, hanem a múltbeli kutatási beszélgetések archívumának visszadolgozása a dokumentációba. A kutatásom közel két éve alatt három különböző AI-eszközzel (Gemini, ChatGPT, Claude) is folytattam beszélgetéseket, ezek azonban soha nem kerültek be strukturáltan a GitHub-repóba - csak a felhasználói fiókok saját exportjaiban léteztek. + +**A forrásadat:** a Google Takeout-tal exportált Gemini-aktivitási napló egy 18,8 MB méretű, közel 6100 bejegyzést tartalmazó JSON fájl volt, október 2024 és augusztus 2026 közötti időszakra. A ChatGPT és a Claude exportjai hasonló, bár nem azonos szerkezetű JSON formátumban érhetők el - a lényeg, hogy mindhárom platform strukturált, géppel feldolgozható exportot ad a beszélgetés-előzményekről, így ugyanaz a feldolgozási módszer elvben mindhárom forrásra alkalmazható, csak a nyers adat parse-oló lépését kell platformonként igazítani. + +**Miért kellett kötegelni?** Az első próbálkozás - az összes releváns szövegrészt egyszerű kulcsszavas kereséssel kiszűrni - hamar kiderült, hogy nem elég megbízható: pontatlan kulcsszólistával könnyű elveszíteni valódi döntéseket, amiket máshogy fogalmaztak meg, mint ahogy a keresés várta. A megoldás az volt, hogy a teljes archívumot időrendben, kronologikus kötegekbe (batch-ekbe) szeleteltem, minden köteg méretét a felhasználható kontextusablak (context window) feléhez igazítva - ez biztosította, hogy egyetlen kötegen belül is elférjen elég kontextus az AI számára ahhoz, hogy valóban értelmezze, mi történik, ahelyett hogy csak izolált mondattöredékeket látna. +Egy finomítási körben ezt tovább optimalizáltuk: az egymáshoz időben közeli beszélgetéseket egy "session"-ként kezelve csoportosítottuk, és csak azokat a session-öket tartottuk meg teljes egészében, amik legalább egy releváns technikai kulcsszót tartalmaztak - így a végső feldolgozandó anyag jelentősen csökkent anélkül, hogy bármilyen releváns döntést elveszítettünk volna. + +**A végeredmény:** a teljes archívum feldolgozása és a kutatási dokumentáció ez alapján történő frissítése/pontosítása ezzel a módszerrel egyetlen munkamenetben végigvihető volt - AI-asszisztencia nélkül ez gyakorlatilag lehetetlen lett volna, hiszen közel 6100 különálló kérdés-válasz párost kellett volna manuálisan átnézni és értelmezni, hogy kiderüljön, melyik döntés még érvényes, és melyiket írta felül egy későbbi beszélgetés. + +## A rendszer élesben: napi használat Claude-dal + +A szerver elkészülte óta a gyakorlatban is bevált: mivel MCP szerverként fut, ugyanaz a kapcsolat elérhető webes felületen, asztali alkalmazásban és Android appon keresztül is - így a kutatási döntéseket akár útközben, hangalapú beszélgetés formájában is rögzíteni tudom, anélkül hogy laptopot kellene nyitnom. +Egy tipikus munkamenet így néz ki: hangosan átbeszélem Claude-dal a felmerülő tervezési kérdést (pl. egy hardveres vagy szoftveres architektúra-döntést), az AI a beszélgetés végén összefoglalja a változtatást, branch-et nyit, majd Pull Requestet készít - amit én a GitHubon nézek át és hagyok jóvá, mielőtt a `master` ágba kerülne. Ez a jóváhagyási lépés tudatosan nincs automatizálva: **a kutatási dokumentáció integritása szempontjából kritikus, hogy semmi ne kerüljön be ellenőrizetlenül.** + +## A kutatás bemutatása weboldalon keresztül + +Mivel a teljes dokumentáció végig egységes, előre meghatározott szerkezetű Markdown fájlokban íródott (mindegyik dokumentum azonos, gépileg feldolgozható metaadat-fejléccel: cím, kategória, dátum, rövid leírás), adta magát az ötlet, hogy ebből **automatikusan generáljunk egy publikus bemutató weboldalt** is - anélkül, hogy a tartalmat máshova kellene átmásolni vagy duplikálni. + +Az oldal egy Next.js alapú statikus site, amit a Vercel szolgáltat ki, és build időben közvetlenül a repó Markdown-mappáiból építkezik: a főoldal a kutatási témák (projekt, szakirodalom, szoftver, hardver, kísérletek, publikációk stb.) tartalomjegyzékét adja, minden témakörnek saját aloldala van, minden dokumentum pedig önálló, formázott oldalként jelenik meg - a matematikai képletekkel, táblázatokkal együtt. Így minden GitHubra bekerülő, jóváhagyott változtatás a következő build-del automatikusan megjelenik a nyilvános oldalon is, külön karbantartási munka nélkül. + +## Kihívások, amikkel használat közben szembesültem + +A fejlesztés és a napi használat során több váratlan probléma is felmerült, amelyek jó tanulsággal szolgáltak: + +- **Elavult információ felismerése:** mivel a beszélgetések hónapokon, sőt éveken át húzódtak, ugyanarról a kérdésről (pl. az eszköz fizikai kialakításáról) többször is más-más döntés született. Az AI-nak explicit utasítást kellett adnom, hogy időrendben haladjon végig az archívumon, és a későbbi döntéseket tekintse mérvadónak a korábbiakkal szemben - enélkül a dokumentáció ellentmondásossá vált volna. +- **Szerzői jogi kérdés a forrásirodalomnál:** a szakirodalmi mappába feltöltött, más szerzők által jegyzett cikkek teljes szövege - bár a saját kutatáshoz jogszerűen felhasználható - nem publikálható változatlan formában egy nyilvános weboldalon. Erre megoldásként egy `public: false` jelzőt vezettünk be a dokumentumok metaadatában, amivel az adott fájl a repóban megmarad (saját referenciaként, és így az MI modell is eléri, ha szükség van rá), de a weboldal build folyamata kihagyja a nyilvános megjelenítésből. A cikkek helyett egy önállóan megfogalmazott, publikálható annotált bibliográfia készült. + +Az kutatást összefoglaló weboldal ezen a linken keresztül tekinthető meg: https://phd-xi.vercel.app/