Studiu de caz: RagCode MCP, căutare semantică în cod pentru asistenții AI, 100% local

Oricine a lucrat cu Cursor, Copilot sau Claude Code pe un proiect mare a văzut scena asta: îi ceri asistentului să modifice o funcție, iar el începe să citească fișier după fișier ca să înțeleagă contextul. Fiecare fișier citit înseamnă tokeni plătiți și loc ocupat în context window¹, adică exact spațiul de care modelul are nevoie ca să gândească. La un moment dat uită ce a citit la început sau, mai rău, inventează o funcție care „probabil” există.

RagCode MCP e răspunsul nostru la problema asta. E un server open source, scris în Go, care îi dă asistentului AI exact bucata de cod de care are nevoie, nu fișiere întregi. Și face asta fără să trimită o linie de cod în afara calculatorului.

Problema, pe scurt

Un asistent AI din editor are două variante proaste:

1. Citește mult. Deschide fișiere întregi ca să găsească o funcție de 20 de linii. Merge, dar costă și umple contextul.
2. Citește puțin. Caută după text, cu grep, și ratează lucrurile care nu se numesc cum crede el. Cine caută „autentificare” nu găsește funcția checkSession.

Ne-am dorit a treia variantă: asistentul întreabă „unde se verifică dacă utilizatorul e logat?” și primește direct funcțiile relevante, cu semnătura, fișierul și liniile lor.

Ce face RagCode, în 4 pași

1. Înțelege structura codului

RagCode nu taie codul în bucăți de lungime fixă, cum fac multe sisteme RAG² generice. Îl citește cu parsere reale și îl împarte pe simboluri: funcții, metode, clase, tipuri. Fiecare bucată știe în ce fișier e, între ce linii, ce semnătură și ce comentarii are.

Pentru Go folosim parserul din biblioteca standard, go/ast³, care e exact cel folosit de compilatorul Go. Pentru PHP folosim parserul VKCOM, cu reguli în plus pentru Laravel (modele Eloquent, rute, controllere) și WordPress (hooks, widgets, WooCommerce). Pentru Python, JavaScript, TypeScript, React și Vue folosim Tree-sitter⁴, aceeași familie de parsere pe care o folosesc editoarele moderne pentru colorarea codului.

2. Transformă fiecare simbol într-un vector

Fiecare bucată de cod trece printr-un model de embeddings care rulează local, prin Ollama⁵. Modelul implicit e qwen3-embedding:0.6b⁶, destul de mic cât să meargă pe un laptop. Rezultatul e un vector: o listă de numere care descrie sensul codului. Două funcții care fac lucruri asemănătoare ajung cu vectori apropiați, chiar dacă au nume complet diferite.

Vectorii se păstrează în Qdrant⁷, o bază de date vectorială open source, care rulează tot local, într-un container Docker.

3. Caută în două feluri deodată

Când asistentul întreabă ceva, RagCode pornește în paralel două căutări:

• o căutare semantică în Qdrant, după sens;
• o căutare exactă în structura codului, după nume de simboluri.

Pentru că rulează în paralel, durata e cea a căutării mai lente, nu suma lor. Rezultatele aflate aproape de fișierul la care lucrezi primesc un bonus, pentru că, de cele mai multe ori, acolo e și răspunsul.

4. Trimite cât trebuie, nu mai mult

Aici se câștigă cei mai mulți tokeni. Dacă rezultatele sunt multe sau nesigure, RagCode trimite doar semnăturile funcțiilor, ca asistentul să aleagă. Dacă potrivirea e clară, trimite codul complet al funcției. Documentația proiectului estimează că modul compact economisește până la circa 17.000 de tokeni pe o întrebare, față de citirea fișierelor întregi⁸. Cifra exactă depinde de proiect, dar mecanismul e simplu: în loc de un fișier de 2.000 de linii, asistentul primește 20.

Uneltele pe care le primește asistentul

RagCode vorbește cu editorul prin Model Context Protocol⁹, standardul deschis prin care asistenții AI folosesc unelte externe. Asistentul primește, printre altele:

• rag_search, căutarea principală, care alege singură între căutarea semantică și cea exactă;
• rag_find_usages, care arată unde e folosit un simbol;
• rag_call_hierarchy, cine apelează o funcție și pe cine apelează ea;
• rag_list_package_exports, ce expune public un pachet;
• rag_read_file_context, câteva linii de cod plus contextul lor din structura fișierului;
• rag_install_skill, care instalează pachete de cunoștințe din registrul ai-agent-skills.

Merge cu Cursor, Windsurf, VS Code cu GitHub Copilot, Claude Code, Claude Desktop, Gemini CLI, Zed și Codex. Instalarea e o singură comandă, care pornește Ollama și Qdrant în Docker și scrie configurația în editoarele alese.

Deciziile tehnice și de ce le-am luat

Totul local. Pentru multe firme, codul sursă e cel mai valoros lucru pe care îl au. Un serviciu care îl trimite la un server străin ca să-l indexeze e, pur și simplu, exclus. Cu Ollama și Qdrant pe calculatorul dezvoltatorului, întrebarea „unde ajunge codul nostru?” are un răspuns scurt: nicăieri.

Go. RagCode se distribuie ca un singur fișier executabil pentru fiecare sistem de operare, fără runtime de instalat. Go ne-a dat și concurența de care aveam nevoie: indexare în fundal, căutări în paralel, mai multe proiecte deodată.

Un daemon și un adaptor. În prima versiune, fiecare fereastră de editor pornea propriul server. Cu trei proiecte deschise aveai trei servere, trei conexiuni la Qdrant și de trei ori memoria. În versiunea 2, editorul pornește doar un adaptor mic, de circa 1 MB, care trimite cererile printr-un Unix socket¹⁰ către un singur daemon, folosit de toate ferestrele. Când instalezi o versiune nouă, adaptorul observă că daemonul e mai vechi și îl repornește singur.

Fiecare branch, indexul lui. Identitatea unui proiect se calculează din cale, branch și worktree. Dacă treci pe alt branch, asistentul nu mai primește funcții care există doar pe branch-ul vechi. Pare un detaliu, dar e una dintre cele mai frecvente surse de răspunsuri greșite.

Fără cod fantomă. Fișierele se urmăresc cu fsnotify¹¹: o modificare salvată se reindexează după o secundă. Și dacă totuși un rezultat vine dintr-un fișier care între timp a fost șters, RagCode verifică fișierul înainte să-l trimită, îl scoate din rezultate și curăță vectorii vechi în fundal.

Căutare și cât timp se indexează. Primul index al unui proiect mare durează. Ca să nu stai după el, RagCode răspunde între timp din structura codului ținută în memorie, iar căutarea semantică intră în joc pe măsură ce indexul se umple.

Ce am învățat măsurând

În septembrie 2026 am măsurat de ce indexarea unui proiect mare mergea greu pe un calculator cu 16 nuclee și fără placă video. RagCode însuși aproape nu folosea procesor și avea sub 110 MB de memorie. Ollama, în schimb, lucra din plin, iar fiecare simbol trecea prin modelul de embeddings în 81–300 de milisecunde.

Surpriza a fost alta: după fiecare simbol, codul aștepta fix 150 de milisecunde, o pauză lăsată acolo din prudență. Pauza asta însemna mai mult de jumătate din timpul total de indexare. Am trecut la trimiterea simbolurilor în loturi către Ollama și urmează mai mulți workeri și o singură coadă de indexare pentru toate proiectele.

Lecția e veche, dar merită repetată: înainte să optimizezi, măsoară. Problema nu era „Go e lent” sau „modelul e prea mare”, ci un sleep uitat.

Unde a ajuns proiectul

Prima versiune publică a apărut la finalul lui 2025, iar ultima versiune stabilă publicată e 1.1.21. Versiunea 2, cu arhitectura daemon și adaptor, căutarea dublă și indexul separat pe branch, e pe branch-ul dev, încă în testare: merge, dar mai are buguri de rezolvat înainte de o versiune stabilă. Proiectul are licență MIT, iar codul, documentația și instrucțiunile de instalare sunt pe GitHub.

Ce înseamnă asta pentru o firmă

Aceleași piese pe care le-am folosit aici, un model de embeddings local, o bază vectorială și un strat care decide ce ajunge la modelul AI, stau la baza sistemelor RAG pe documentele firmei pe care le construim. Diferența e doar ce indexăm: în loc de funcții, contracte, proceduri și fișe tehnice. Iar întrebarea „unde ajung datele noastre?” poate avea același răspuns scurt.

La DO IT MAGIC SOFTWARE construim software la comandă și sisteme AI care rulează și pe infrastructura ta. Dacă vrei un asistent AI care înțelege codul sau documentele firmei, scrie-ne.

Surse

Întrebări frecvente