mcp-openapi-demo

Model Context Protocol

“LLM function calling” mekanizması ile MCP’yi otomatik tetikleyen küçük bir demo.

📂 Proje Dizini

mcp-openapi-demo/
│
├── server.js          # Node.js tarafı → MCP Server (Petstore API)
├── package.json       # Node bağımlılıkları
├── .env               # Ortam değişkenleri (API anahtarı vs.)
└── python-client/
    ├── client.py      # Python tarafı → MCP Client (OpenAI entegrasyonu ile)

Proje Nasıl Çalışır

👉 Modele sadece “Find available pets” denir. 👉 Model, kendi isteğiyle function call yapacak. 👉 Python kodu, bu function call’u yakalayacak, MCP server’a yönlendirecek, cevabı alacak. 👉 Sonucu tekrar modele verip son yanıtı yazdıracak.

---

🚀 Adım 1: MCP Server’ı Çalıştır

Önce Node.js tarafını aç ve terminalde:

cd mcp-openapi-demo
node server.js

Eğer doğruysa:

🚀 MCP Server running on http://localhost:4000

mesajını görmen lazım ✅

---

🚀 Adım 2: Python Ortamını Kur

Python client klasörüne geç:

cd python-client
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install requests openai

---

🚀 Adım 3: OpenAI API Key Ayarla

API anahtarını .env dosyasına yazabilirsin:

OPENAI_API_KEY=senin_api_key

Python kodunda anahtarı almak için python-dotenv paketini kur:

pip install python-dotenv

Ve client.py içinde şöyle ekle:

from dotenv import load_dotenv
load_dotenv()

Artık anahtar otomatik olarak .env dosyasından alınacak.

---

🚀 Adım 4: Python Client Çalıştır

python client.py

Beklenen çıktı:

1. Önce Petstore API’den gelen JSON → yani “available pets” listesi.
2. Ardından OpenAI modelinin doğal dilde özeti → mesela “There are 20 available pets, most are dogs and cats...” gibi.

📌 Özetle:

• Node.js tarafı → Petstore MCP Server
• Python tarafı → Hem MCP’den veri çekiyor hem de OpenAI modeline verip yorum alıyor

LLM Function Calling Mekanizması Nasıl Çalışır?

👉 Modelin "find_available_pets" fonksiyonunu çağırması senin yazdığın prompt + ona verdiğin tools tanımı sayesinde oluyor. Yani bu çağrı senin API çağrının bir yanıtı olarak, modelin output’unda gerçekleşiyor.

📍 Nerede olur?

OpenAI’nin chat.completions.create cevabında olur. Örneğin Python’da:

from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "function",
        "function": {
            "name": "find_available_pets",
            "description": "Find pets in the Petstore API by status",
            "parameters": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": ["available", "pending", "sold"]
                    }
                },
                "required": ["status"],
            },
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Can you show me all available pets?"}
    ],
    tools=tools
)

print(response.choices[0].message)

📍 Modelin cevabı nasıl olur?

Model sana düz metin dönmez, function call döner:

{
  "role": "assistant",
  "tool_calls": [
    {
      "id": "call_1",
      "type": "function",
      "function": {
        "name": "find_available_pets",
        "arguments": "{ \"status\": \"available\" }"
      }
    }
  ]
}

📍 Sen ne yaparsın?

1. Buradaki function.name ve arguments değerini alırsın.

2. Bu bilgiyi MCP server’a JSON-RPC request olarak gönderirsin (pet/findByStatus).

3. Dönen cevabı tekrar modele verirsin →

   client.chat.completions.create(
       model="gpt-4o-mini",
       messages=[
           {"role": "user", "content": "Can you show me all available pets?"},
           response.choices[0].message,  # function call çıktısı
           {
             "role": "tool",
             "tool_call_id": response.choices[0].message.tool_calls[0].id,
             "content": json.dumps(mcp_result)
           }
       ]
   )
   

✅ Yani “find_available_pets” çağrısı senin kodunda değil, modelin output’unda gerçekleşiyor. Sen sadece bu function call’u yakalayıp gerçekten çalıştırıyorsun (MCP’ye gönderiyorsun).

tam zincir:

kullanıcı → LLM → function call → MCP → sonuç → tekrar LLM

Tool tanımındaki description mı süreci etkiliyor?

Aynen öyle ✅ — tool tanımındaki description kısmı sürecin en kritik parçalarından biri.

LLM, kullanıcı mesajını alıyor → sonra kendisine senin verdiğin tool schemayı inceliyor. Tool’un adı, parametreleri ve özellikle description kısmı, modelin hangi durumda o tool’u çağıracağına karar vermesini sağlıyor.

🔎 Detaylı olarak etkileyen faktörler:

1. Tool adı (name)

   • Model için bir “anahtar kelime”.
   • Ama tek başına yeterli değil, çünkü kullanıcı hep “find pets” demeyebilir.
   • Örn: kullanıcı “show me all dogs available for adoption” derse → model description’a bakıp “bu tool adoption için available pets getiriyor” diye eşleştirir.

2. Description (Açıklama)

   • Modelin karar verme sürecinde en güçlü sinyal.

   • Buraya yazdığın açıklama ne kadar açık, görev tanımı ne kadar iyi olursa model o kadar doğru karar verir.

   • Örn:

     "description": "Find pets that are currently available in the Petstore API. Use this function if the user asks about pets, animals, or available pets."
     

     Böyle yazarsan, model daha doğru tetikler.

   • Eğer description zayıfsa, model yanlış tool’u seçebilir ya da hiç tool çağırmayabilir.

3. Parameters (şema)

   • Modelin doğru argüman üretmesini sağlar.
   • Mesela enum ["available", "pending", "sold"] dersen, model bu üç değerden birini seçecektir.
   • Bu da seni gereksiz validation’dan kurtarır.

📌 Özet:

• Evet, description doğrudan etkiliyor.
• Description, modelin “hangi tool ne işe yarıyor” bilgisini anlaması için kritik.
• İyi yazılmış description → doğru tool seçimi ve doğru parametreler.