Utilizarea MCP pentru a naviga prin fișierele locale

În acest articol vom discuta despre cum putem folosi MCP (Model Context Protocol) și python pentru a naviga printre fișierele de pe calculatorul nostru folosind un LLM local – în acest caz Llama 3.2.

1. Câteva cuvinte despre MCP

Protocolul MCP este un set de reguli care standardizează modul în care LLM-urile interacționează cu datele și instrumentele externe. În loc de metode ad-hoc, MCP propune o abordare mai organizată și mai flexibilă.

În acest tutorial, vom crea un server MCP care oferă câteva instrumente simple și vom demonstra cum un model Llama 3.2 le poate utiliza. Înainte de a începe, este recomandabil să citiți articolul de bază despre MCP și utilizarea Ollama și a modelelor AI locale.

2. Crearea serverului MCP cu instrumente de bază

Vom începe prin a instala biblioteca `mcp` folosind `pip`:

pip install mcp
pip list | grep mcp

# Output:
# mcp 1.5.0

Apoi, vom crea un server MCP numit „Local Agent Helper”. Acesta va oferi trei instrumente:

* `ls`: Listează conținutul unui director.
* `cat`: Citește conținutul unui fișier.
* `echo`: Scrie text într-un fișier.

from mcp.server.fastmcp import FastMCP

server = FastMCP("Local Agent Helper")

Iată codul Python pentru a implementa aceste instrumente:

@server.tool()
def ls(directory: str) -> str:
"List the contents of a directory."
import os
return "\n".join(os.listdir(directory))

@server.tool()
def cat(file: str) -> str:
"Read the contents of a file."
try:
with open(file, "r") as f:
return f.read()
except:
return ""

@server.tool()
def echo(message: str, file: str) -> str:
"Write text to a file."
try:
with open(file, "w") as f:
f.write(message)
return "success"
except:
return "failed"

Puteți testa serverul folosind un inspector MCP pentru a verifica dacă funcționează corect.

3. Conectarea la Serverul MCP cu un LLM Local (Llama 3.2)

Acum vom crea un client MCP care va interacționa cu serverul nostru și va rula modelul LLM. Vom folosi Llama 3.2-1B-Instruct și biblioteca `transformers` de la HuggingFace.

from transformers import AutoTokenizer, AutoModelForCausalLM

model = "meta-llama/Llama-3.2-1b-instruct"

tokenizer = AutoTokenizer.from_pretrained(model)
model = AutoModelForCausalLM.from_pretrained(model)

Vom porni serverul MCP ca un proces separat folosind `subprocess`:

import subprocess

server = subprocess.Popen(
['python3', 'server.py'],
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
stdin=subprocess.PIPE,
text=True,
)

Pentru comunicare, vom utiliza funcții utilitare pentru a crea, trimite și primi mesaje JSON-RPC:

import json
def create_message(method_name, params, id = None):
message = {
"jsonrpc": "2.0",
"method": method_name,
"params": params,
"id": id
}
return json.dumps(message)

def send_message(message):
server.stdin.write(message + "\n")
server.stdin.flush()

def receive_message():
server_output = json.loads(server.stdout.readline())
if "result" in server_output:
return server_output["result"]
else:
return "Error"

4. Inițializarea sesiunii și obținerea listei de instrumente

Conform protocolului MCP, trebuie să trimitem un mesaj de inițializare pentru a începe sesiunea de comunicare. Serverul va răspunde cu detalii despre capacitățile sale. Apoi, vom solicita lista de instrumente disponibile folosind metoda `tools/list`.

id = 1
init_message = create_message(
"initialize",
{
"clientInfo": {
"name": "Llama Agent",
"version": "0.1"
},
"protocolVersion": "2024-11-05",
"capabilities": {},
},
id
)

send_message(init_message)
response = receive_message()
server_name = response["serverInfo"]["name"]
print("Initializing " + server_name + "...")

init_complete_message = create_message("notifications/initialized", {})
send_message(init_complete_message)
print("Initialization complete.")

Vom trimie o listă de instrumente pe care LLM-ul le poate utiliza:

id += 1
list_tools_message = create_message("tools/list", {}, id)
send_message(list_tools_message)
response = json.loads(server.stdout.readline())["result"]
for tool in response["tools"]:
print(tool["name"])
print(tool["description"])
print(tool["inputSchema"]["properties"])
print("")

# Output:
# ls
# List the contents of a directory.
# {'directory': {'title': 'Directory', 'type': 'string'}}
#
# cat
# Read the contents of a file.
# {'file': {'title': 'File', 'type': 'string'}}
# 
# echo
# Write text to a file.
# {'message': {'title': 'Message', 'type': 'string'}, 
# 'file': {'title': 'File', 'type': 'string'}}

Vom crea un array `available_functions` pentru a stoca instrumentele într-un format pe care modelul Llama îl poate utiliza.

available_functions = []
for tool in response["tools"]:
func = {
"type": "function",
"function": {
"name": tool["name"],
"description": tool["description"],
"parameters": {
"type": "object",
"properties": tool["inputSchema"]["properties"],
"required": tool["inputSchema"]["required"],
},
},
}
available_functions.append(func)

5. Utilizarea instrumentelor pentru răspunsuri contextuale

Cu instrumentele disponibile, putem trimite o solicitare către modelul Llama, incluzând array-ul `available_functions`. Modelul ar trebui să determine care instrument este necesar și să genereze un apel de funcție.

prompt = "Ce avem în directorul /tmp ?"

messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": prompt},
]

template = tokenizer.apply_chat_template(
messages, tools=available_functions,
tokenize=False
)

inputs = tokenizer(template, return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=30, do_sample=True)
print(tokenizer.decode(outputs[0]))

# Output:
# What's there in the /tmp directory?<|eot_id|>
# <|start_header_id|>assistant<|end_header_id|>
# <|python_tag|>{"type": "function", "function": 
# "ls", "parameters": {"directory": "/tmp"}}
# <|eom_id|>
```

Vom extrage funcțiile apeleate cu ajutorul LLM-ului (acestea se afla între `<|python_tag|>` și `<|eom_id|>`), le vom converti într-un mesaj JSON-RPC și le vom trimite serverului MCP. Răspunsul serverului va fi apoi afișat.

last_line = generated_text.split("\n")[-1]
start_marker = "<|python_tag|>"
end_marker = "<|eom_id|>"
id += 1
if start_marker in last_line and end_marker in last_line:
    code = last_line.split(start_marker)[1].split(end_marker)[0]
    code = json.loads(code)
    function_call = create_message("tools/call", {
        "name": code["function"],
        "arguments": code["parameters"],
    }, id)
    send_message(function_call)
    response = receive_message()["content"][0]["text"]

# Output:
# tmp1.html
# tmp2.html

Concluzie

Am demonstrat cu succes cum să folosim protocolul MCP pentru a îmbunătăți un model Llama 3.2 local cu acces la instrumente externe.

Această abordare oferă o modalitate standardizată și flexibilă de a extinde capacitățile LLM-urilor, permițându-le să interacționeze cu lumea exterioară și să ofere răspunsuri mai contextuale și mai precise.

Utilizarea MCP poate fi un pas important în crearea unor agenți AI mai inteligenți și mai adaptabili. Pornind de la acest model se poate construi o aplicație și mai complexă prin care putem interacționa într-un limbaj uman cu toate fișierele de pe calculatorul nostru (de exemplu putem face căutări, organizări, ștergeri, copieri etc).