MCP Inspector, tam bir yapay zeka ana bilgisayar uygulamasına ihtiyaç duymadan MCP sunucularınızı etkileşimli olarak test etmenizi ve sorun gidermenizi sağlayan temel bir hata ayıklama aracıdır. "MCP için Postman" gibi düşünebilirsiniz - istek göndermek, yanıtları görüntülemek ve sunucunuzun nasıl davrandığını anlamak için görsel bir arayüz sağlar.
MCP sunucuları oluştururken genellikle şu zorluklarla karşılaşırsınız:
- "Sunucum çalışıyor mu?" - Inspector bağlantı durumunu gösterir
- "Araçlarım doğru kayıtlı mı?" - Inspector tüm mevcut araçları listeler
- "Yanıt formatı nedir?" - Inspector tam JSON yanıtlarını gösterir
- "Bu araç neden çalışmıyor?" - Inspector ayrıntılı hata mesajları gösterir
- Node.js 18+ yüklü
- npm (Node.js ile birlikte gelir)
- Test etmek için bir MCP sunucusu (bkz. Modül 3.1 - İlk Sunucu)
npx @modelcontextprotocol/inspectornpm install -g @modelcontextprotocol/inspector
mcp-inspectorcd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspectorpackage.json dosyasına ekleyin:
{
"scripts": {
"inspector": "mcp-inspector"
}
}Standart girdi/çıktı üzerinden iletişim kuran sunucular için:
# Python sunucusu
npx @modelcontextprotocol/inspector python -m your_server_module
# Node.js sunucusu
npx @modelcontextprotocol/inspector node ./build/index.js
# Ortam değişkenleri ile
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.pyHTTP hizmeti olarak çalışan sunucular için:
-
Önce sunucunuzu başlatın:
python server.py # Sunucu http://localhost:8080 üzerinde çalışıyor -
Inspector'u başlatın ve bağlanın:
npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse
Inspector açıldığında, bir web arayüzü görürsünüz (genellikle http://localhost:5173 adresinde):
┌─────────────────────────────────────────────────────────────┐
│ MCP Inspector [Connected ✅] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 🔧 Tools │ │ 📄 Resources│ │ 💬 Prompts │ │
│ │ (3) │ │ (2) │ │ (1) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 📋 Message Log │ │
│ │ ─────────────────────────────────────────────────── │ │
│ │ → initialize │ │
│ │ ← initialized (server info) │ │
│ │ → tools/list │ │
│ │ ← tools (3 tools) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
- Araçlar sekmesine tıklayın
- Inspector otomatik olarak
tools/listçağrısı yapar - Tüm kayıtlı araçları şunlarla birlikte görürsünüz:
- Araç adı
- Açıklama
- Girdi şeması (parametreler)
- Listeden bir araç seçin
- Formda gerekli parametreleri doldurun
- Araç Çalıştır düğmesine tıklayın
- Yanıt sonuç panelinde görüntülenir
Örnek: Bir hesap makinesi aracını test etme
Tool: add
Parameters:
a: 25
b: 17
Response:
{
"content": [
{
"type": "text",
"text": "42"
}
]
}
Bir araç başarısız olduğunda, Inspector şunları gösterir:
Error Response:
{
"error": {
"code": -32602,
"message": "Invalid params: 'b' is required"
}
}
Yaygın hata kodları:
| Kod | Anlamı |
|---|---|
| -32700 | Ayrıştırma hatası (geçersiz JSON) |
| -32600 | Geçersiz istek |
| -32601 | Metot bulunamadı |
| -32602 | Geçersiz parametreler |
| -32603 | Dahili hata |
- Kaynaklar sekmesine tıklayın
- Inspector
resources/listçağrısı yapar - Şunları görürsünüz:
- Kaynak URI'ları
- İsimler ve açıklamalar
- MIME türleri
- Bir kaynak seçin
- Kaynağı Oku düğmesine tıklayın
- Dönen içeriği görüntüleyin
Örnek çıktı:
Resource: file:///config/settings.json
Content-Type: application/json
{
"config": {
"debug": true,
"maxConnections": 10
}
}
- Promptlar sekmesine tıklayın
- Inspector
prompts/listçağrısı yapar - Mevcut prompt şablonlarını görüntüleyin
- Bir prompt seçin
- Gerekli argümanları doldurun
- Prompt Al düğmesine tıklayın
- Oluşturulan prompt mesajlarını görün
Mesaj günlüğü tüm MCP protokol mesajlarını gösterir:
14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}
- İstek / Yanıt çiftleri: Her
→için eşleşen bir←olmalı - Hata mesajları: Yanıtlarda
"error"arayın - Zamanlama: Büyük boşluklar performans sorunlarını gösterebilir
- Protokol sürümü: Sunucu ve istemcinin sürümde anlaşması gerekir
Inspector'u doğrudan VS Code'dan çalıştırabilirsiniz:
.vscode/launch.json dosyasına ekleyin:
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug with MCP Inspector",
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"runtimeArgs": [
"@modelcontextprotocol/inspector",
"python",
"${workspaceFolder}/server.py"
],
"console": "integratedTerminal"
},
{
"name": "Debug SSE Server with Inspector",
"type": "chrome",
"request": "launch",
"url": "http://localhost:5173",
"preLaunchTask": "Start MCP Inspector"
}
]
}.vscode/tasks.json dosyasına ekleyin:
{
"version": "2.0.0",
"tasks": [
{
"label": "Start MCP Inspector",
"type": "shell",
"command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
"isBackground": true,
"problemMatcher": {
"pattern": {
"regexp": "^$"
},
"background": {
"activeOnStart": true,
"beginsPattern": "Inspector",
"endsPattern": "listening"
}
}
}
]
}Belirtiler: Inspector "Disconnected" gösteriyor veya "Connecting..." kısmında takılıyor
Kontrol Listesi:
- ✅ Sunucu komutu doğru mu?
- ✅ Tüm bağımlılıklar yüklü mü?
- ✅ Sunucu yolu mutlak mı yoksa mevcut dizine göre mi?
- ✅ Gerekli ortam değişkenleri ayarlandı mı?
Hata ayıklama adımları:
# Önce testi sunucusunu manuel olarak yapın
python -c "import your_server_module; print('OK')"
# İçe aktarma hatalarını kontrol edin
python -m your_server_module 2>&1 | head -20
# MCP SDK'nın kurulu olduğunu doğrulayın
pip show mcpBelirtiler: Araçlar sekmesinde liste boş
Olası nedenler:
- Sunucu başlatılırken araçlar kayıt edilmedi
- Sunucu başlatıldıktan sonra çöktü
tools/listişleyicisi boş dizi döndürüyor
Hata ayıklama adımları:
- Mesaj günlüğünde
tools/listyanıtını kontrol edin - Araç kayıt kodunuza logging ekleyin
@mcp.tool()dekoratörlerinin varlığını doğrulayın (Python)
Belirtiler: Araç çağrısı hata yanıtı alıyor
Hata ayıklama yaklaşımı:
- Hata mesajını dikkatle okuyun
- Parametre türlerinin şemayla uyumlu olduğundan emin olun
- Ayrıntılı hata mesajları için try/catch ekleyin
- Sunucu günlüklerinde yığın izlerini kontrol edin
Geliştirilmiş hata yönetimi örneği:
@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
try:
# Araç mantığı burada
result = process(param1, param2)
return str(result)
except ValueError as e:
raise McpError(f"Invalid parameter: {e}")
except Exception as e:
raise McpError(f"Tool failed: {type(e).__name__}: {e}")Belirtiler: Kaynak döndürüyor ama içerik boş veya null
Kontrol Listesi:
- ✅ Dosya yolu veya URI doğru mu?
- ✅ Sunucunun kaynağı okuma izni var mı?
- ✅ Kaynak içeriği doğru şekilde dönüyor mu?
npx @modelcontextprotocol/inspector \
--sse http://localhost:8080/sse \
--header "Authorization: Bearer your-token"DEBUG=mcp* npx @modelcontextprotocol/inspector python server.pyInspector mesaj günlüklerini daha sonra analiz için dışa aktarabilir:
- Mesaj panelinde Günlüğü Dışa Aktar'a tıklayın
- JSON dosyasını kaydedin
- Sorun gidermek için ekip üyeleriyle paylaşın
- Erken ve sık test edin - Sadece sorun çıktığında değil, geliştirme sırasında Inspector'u kullanın
- Basitten başlayın - Karmaşık araç çağrılarından önce temel bağlantıyı test edin
- Şemayı kontrol edin - Birçok hata parametre türü uyumsuzluğundan kaynaklanır
- Hata mesajlarını okuyun - MCP hataları genellikle açıklayıcıdır
- Inspector'u açık tutun - Geliştirirken sorunları yakalamaya yardımcı olur
Modül 3: Başlarken bölümü tamamladınız! Öğrenmeye devam edin:
Feragat: Bu belge, AI çeviri hizmeti Co-op Translator kullanılarak çevrilmiştir. Doğruluk için çaba göstermemize rağmen, otomatik çevirilerin hatalar veya yanlışlıklar içerebileceğini lütfen unutmayın. Orijinal belge, kendi dilinde yetkili kaynak olarak değerlendirilmelidir. Önemli bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu oluşabilecek yanlış anlamalar veya yanlış yorumlardan sorumlu değiliz.