Tutorial de creare a agenților AI cu MCP și Ollama

Prin intermediul acestui tutorial de creare a agenților AI, vom învăța cum să configurăm un client MCP care interacționează cu un server MCP pentru operațiuni de sistem de fișiere, folosind un model LLM rulat local prin Ollama.

În ultimii ani, inteligența artificială a evoluat rapid, ajungând la un punct în care modelele LLM nu mai sunt doar instrumente de generare de text, ci pot deveni agenți AI autonomi capabili să interacționeze cu mediul extern. Această transformare este posibilă datorită unor standarde emergente precum Model Context Protocol (MCP), un nou cadru dezvoltat de Anthropic pentru a facilita comunicarea între modelele de inteligență artificială și resursele externe — cum ar fi fișierele de pe disc, aplicațiile de cloud sau bazele de date. În același timp, platforme precum Ollama permit utilizatorilor să ruleze modele complexe direct pe dispozitivele lor locale, fără a depinde de servicii cloud.

În acest articol, vom explora cum să combinăm aceste două tehnologii pentru a crea un agent AI local capabil să execute sarcini practice, cum ar fi editarea fișierelor, organizarea dosarelor sau generarea de cod HTML.

1. Introducere în Model Context Protocol (MCP)

Model Context Protocol (MCP) reprezintă o evoluție semnificativă în modul în care modelele de inteligență artificială interacționează cu lumea reală. Înainte de MCP, integrarea unui model LLM cu funcționalități externe era adesea o sarcină complexă, personalizată și dificil de întreținut. Fiecare aplicație trebuia să implementeze propriul sistem de interfață cu API-uri, fișiere sau servicii, ceea ce ducea la o lipsă de standardizare. MCP rezolvă această problemă prin oferirea unui cadru comun pentru comunicare între un client MCP (de obicei un model LLM) și un server MCP (o aplicație care oferă acces la resurse externe).

Un client MCP poate fi orice instrument care utilizează un model de inteligență artificială — cum ar fi ChatGPT, Claude Desktop sau, în cazul nostru, un model rulat local prin Ollama.

Un server MCP, pe de altă parte, este un program care oferă un set de unelte sau resurse, cum ar fi accesul la sistemul de fișiere, baze de date sau API-uri de email. De exemplu, dacă vrem ca un agent AI să poată crea un fișier HTML pe discul nostru, clientul va trimite o cerere către serverul MCP, care va executa operațiunea și va returna rezultatul.

Principiul de bază al MCP este că modelele pot fi instruite să recunoască și să utilizeze un set standardizat de unelte, fără a trebui să fie programate individual pentru fiecare resursă. Acest lucru face posibilă crearea de agenți AI flexibili și extensibili. De asemenea, MCP suportă două mecanisme de transport: stdio și Streamable HTTP. În acest tutorial, vom folosi stdio, care este mai simplu de configurat și este ideal pentru experimente locale. Cu această abordare, clientul pornește serverul ca un proces subordonat și comunică cu el prin canalele stdin/stdout, folosind mesaje JSON-RPC.

2. Configurarea mediului de lucru

Pentru a urmări acest tutorial, trebuie să avem instalate câteva componente de bază pe sistemul nostru. În primul rând, este necesar să avem o versiune a limbajului Python ≥ 3.10, deoarece codul va fi scris în Python și va folosi biblioteci moderne. În al doilea rând, avem nevoie de npm (Node Package Manager), deoarece serverul MCP pentru sistemul de fișiere este scris în JavaScript și va fi instalat prin npm.

Pașii de instalare sunt următorii:

2.1. Instalarea bibliotecii MCP pentru Python

Deschide terminalul și rulează comanda:

pip install "mcp[cli]"

2.2. Instalarea serverului MCP pentru fișiere

Rulează comanda:

npm install -g @modelcontextprotocol/server-filesystem

2.3. Verificarea instalării

Asigură-te că ambele pachete sunt instalate corect. Poți verifica prin comenzile:

ollama --version node --version

2.4. Configurarea unui server MCP

În continuare, trebuie să configurăm un server MCP care să aibă acces la anumite directoare din sistemul nostru. În exemplul nostru, vom permite accesul doar la directorul curent, indicat prin "./". Acest lucru este esențial pentru securitate: serverul nu va putea accesa fișiere din alte locații, ceea ce reduce riscurile de compromitere a datelor personale.

Serverul MCP este configurat prin intermediul unui fișier Python care definește parametrii de conectare. În acest caz, vom folosi un server predefinit pentru operațiuni de sistem de fișiere. Codul care configurează conexiunea este următorul:

from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="node",
    args=[
        "/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "./"
    ],
    env=None,
)

În acest cod, command="node" indică că serverul va fi rulat de către interpretorul Node.js. Primul argument din args este calea către fișierul principal al serverului, iar al doilea argument, "./", este directorul permis pentru operațiuni. Acesta este un pas crucial: fără permisiunea clară de acces, serverul nu va putea executa operațiuni.

3. Interacțiunea cu serverul MCP și utilizarea uneltelor

Odată configurat serverul, următorul pas este să ne conectăm la el și să verificăm ce unelte (tools) sunt disponibile. Aceste unelte sunt funcțiile pe care serverul le oferă clientului, cum ar fi citirea unui fișier, scrierea unui fișier nou sau mutarea unui fișier între directoare.

În codul Python, vom folosi o funcție asincronă pentru a obține informații despre server și unelte. Mai întâi, vom verifica informațiile de bază ale serverului, cum ar fi versiunea protocolului și numele serverului:

async def get_server_info():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            result = await session.initialize()
            print(result)

asyncio.run(get_server_info())

Rezultatul va arăta ce unelte sunt disponibile și ce funcționalități suportă serverul. În cazul nostru, serverul secure-filesystem-server v1.0 oferă 11 unelte, printre care:

• read_file – citește conținutul unui fișier
• write_file – creează un fișier nou sau suprascrie unul existent
• edit_file – modifică conținutul unui fișier existent
• create_directory – creează un nou director
• search_files – caută fișiere într-un director
• list_directory – listează fișierele dintr-un director
• move_file – mută un fișier între directoare
• get_file_info – returnează informații despre un fișier (dimensiune, tip)

Este important să observăm că fiecare unealtă (tool) are defintă o structură de tip schema de intrare (input schema), care descrie ce parametri trebuie să fie transmiși pentru a putea fi utilizată în mode corect. De exemplu, uneltei write_file i se cere un parametru path (calea fișierului) și un parametru content (conținutul nou). Acest lucru permite modelului să înțeleagă cum să o folosească corect.

În continuare, vom extrage toate uneltele și le vom transforma în formatul așteptat de Ollama, care este diferit de cel standard MCP. Ollama așteaptă o listă de obiecte JSON cu cheile type, function, name, description și parameters. Această conversie este simplă și se face în codul Python:

tools_response = await session.list_tools()
tools = [{
    'type': 'function',
    'function': {
        'name': tool.name,
        'description': tool.description,
        'parameters': tool.inputSchema
    }
} for tool in tools_response.tools]

Acum avem o listă de unelte pregătite pentru a fi folosite în interacțiunea cu modelul LLM.

4. Execuția unei sarcini prin intermediul Agentului AI

Acum că avem un client MCP conectat la un server și uneltele pregătite, putem trimite o cerere către modelul LLM rulat local prin Ollama. În acest exemplu, vom folosi modelul qwen3:8b, care este cunoscut pentru performanța sa stabilă în utilizarea uneltelor. Alte modele precum llama3.2 sau llama3.1 pot fi testate, dar în practică qwen3:8b a arătat rezultate mai consistente.

Interacțiunea cu modelul se face prin API-ul Ollama, care acceptă un parametru tools pentru a transmite uneltele disponibile. Codul pentru această interacțiune este următorul:

response = ollama.chat(
    model='qwen3:8b',
    tools=tools,
    messages=[
        {'role': 'system', 'content': 'You are a helper bot that helps users with their tasks. You can use the tools you have access to if you need them.'},
        {'role': 'user', 'content': 'Create a simple html page that displays the text "AI is going to take over the world!" in bold red text.'}
    ],
    stream=False
)

Modelul va analiza cererea și va decide dacă are nevoie de o uneltă. În acest caz, va decide să folosească uneltei write_file pentru a crea un fișier HTML. După ce modelul trimite o cerere de apelare a unei unelte, codul va executa apelul:

if response.message.tool_calls:
    for tool_call in response.message.tool_calls:
        result = await session.call_tool(tool_call.function.name, tool_call.function.arguments)
        print(result)

Rezultatul este un fișier HTML creat automat în directorul curent, cu conținutul:

<!DOCTYPE html>
<html>
<head>
<title>AI Message</title>
</head>
<body>
<b style="color: red;">AI is going to take over the world!</b>
</body>
</html>

Acest exemplu simplu demonstrează puterea folosirii protocolului MCP: un model LLM poate înțelege o sarcină și poate executa operațiuni reale pe sistemul de fișiere, fără a fi nevoie de codare manuală. De asemenea, este clar că această abordare poate fi extinsă la funcționalități mai complexe, cum ar fi accesul la Google Drive, baze de date sau API-uri de email.

5. Concluzie

Crearea de agenți AI capabili să interacționeze cu lumea reală nu mai este o idee futuristică, ci o realitate accesibilă pentru orice utilizator cu o cunoaștere de bază în programare. Prin combinarea MCP și Ollama, putem construi agenți locali, securizați și personalizabili, care să execute sarcini practice fără a depinde de servicii cloud.

Deși acest exemplu este simplu, el servește ca bază pentru aplicații mult mai complexe. De exemplu, un agent AI poate fi configurat să monitorizeze un dosar, să proceseze fișierele PDF, să genereze rapoarte sau chiar să automatizeze procese de lucru. Avantajele includ controlul total asupra datelor, securitatea sporită și lipsa dependenței de internet.

În viitor, așteptăm o evoluție a MCP, cu mai multe tipuri de transport, mai multe unelte standardizate și o integrare mai profundă cu aplicațiile zilnice. Dar chiar și în stadiul actual, tehnologia oferă o platformă puternică pentru dezvoltarea agenților AI autonomi, accesibilă oricui care dorește să exploreze potențialul inteligenței artificiale în mediul local.