Αποσφαλμάτωση με το MCP Inspector

Το MCP Inspector είναι ένα βασικό εργαλείο αποσφαλμάτωσης που σας επιτρέπει να δοκιμάζετε διαδραστικά και να αντιμετωπίζετε προβλήματα στους MCP διακομιστές σας χωρίς να χρειάζεστε μια πλήρη εφαρμογή φιλοξενίας AI. Σκεφτείτε το σαν το "Postman για MCP" - παρέχει ένα οπτικό περιβάλλον για αποστολή αιτημάτων, προβολή απαντήσεων και κατανόηση της συμπεριφοράς του διακομιστή σας.

Γιατί να χρησιμοποιήσετε το MCP Inspector;

Κατά την κατασκευή MCP διακομιστών, συχνά θα αντιμετωπίσετε τις εξής προκλήσεις:

"Λειτουργεί καν ο διακομιστής μου;" - Ο Inspector δείχνει την κατάσταση σύνδεσης
"Έχουν καταχωριστεί σωστά τα εργαλεία μου;" - Ο Inspector εμφανίζει όλα τα διαθέσιμα εργαλεία
"Ποια είναι η μορφή της απάντησης;" - Ο Inspector εμφανίζει πλήρεις απαντήσεις JSON
"Γιατί δεν λειτουργεί αυτό το εργαλείο;" - Ο Inspector δείχνει λεπτομερή μηνύματα σφάλματος

Προαπαιτούμενα

Εγκατεστημένο Node.js 18+
npm (συνοδεύει το Node.js)
Ένας MCP διακομιστής για δοκιμή (βλέπε Ενότητα 3.1 - Πρώτος Διακομιστής)

Εγκατάσταση

Επιλογή 1: Εκτέλεση με npx (Συνιστάται για γρήγορη δοκιμή)

npx @modelcontextprotocol/inspector

Επιλογή 2: Παγκόσμια Εγκατάσταση

npm install -g @modelcontextprotocol/inspector
mcp-inspector

Επιλογή 3: Προσθήκη στο Έργο σας

cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector

Προσθήκη στο package.json:

{
  "scripts": {
    "inspector": "mcp-inspector"
  }
}

Σύνδεση με το διακομιστή σας

stdio Διακομιστές (Τοπική διαδικασία)

Για διακομιστές που επικοινωνούν μέσω standard input/output:

# Εξυπηρετητής Python
npx @modelcontextprotocol/inspector python -m your_server_module

# Εξυπηρετητής Node.js
npx @modelcontextprotocol/inspector node ./build/index.js

# Με μεταβλητές περιβάλλοντος
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

SSE/HTTP Διακομιστές (Δίκτυο)

Για διακομιστές που τρέχουν ως HTTP υπηρεσίες:

Εκκινήστε πρώτα το διακομιστή σας:

python server.py  # Ο διακομιστής εκτελείται στο http://localhost:8080

Εκκινήστε τον Inspector και συνδεθείτε:

npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

Επισκόπηση διεπαφής Inspector

Όταν εκκινήσει ο Inspector, θα δείτε μια διαδικτυακή διεπαφή (συνήθως στη διεύθυνση http://localhost:5173):

┌─────────────────────────────────────────────────────────────┐
│  MCP Inspector                              [Connected ✅]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   🔧 Tools  │  │ 📄 Resources│  │ 💬 Prompts  │         │
│  │    (3)      │  │    (2)      │  │    (1)      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📋 Message Log                                       │ │
│  │  ─────────────────────────────────────────────────── │ │
│  │  → initialize                                         │ │
│  │  ← initialized (server info)                          │ │
│  │  → tools/list                                         │ │
│  │  ← tools (3 tools)                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Δοκιμή Εργαλείων

Εμφάνιση Διαθέσιμων Εργαλείων

Κάντε κλικ στην καρτέλα Tools
Ο Inspector καλεί αυτόματα το tools/list
Θα δείτε όλα τα καταχωρισμένα εργαλεία με:
- Όνομα εργαλείου
- Περιγραφή
- Σχήμα εισόδου (παράμετροι)

Εκτέλεση Εργαλείου

Επιλέξτε ένα εργαλείο από τη λίστα
Συμπληρώστε τις απαιτούμενες παραμέτρους στη φόρμα
Κάντε κλικ στο Run Tool
Δείτε την απάντηση στον πίνακα αποτελεσμάτων

Παράδειγμα: Δοκιμή εργαλείου αριθμομηχανής

Tool: add
Parameters:
  a: 25
  b: 17

Response:
{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

Αποσφαλμάτωση Σφαλμάτων Εργαλείων

Όταν ένα εργαλείο αποτυγχάνει, ο Inspector εμφανίζει:

Error Response:
{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

Κοινοί κωδικοί σφαλμάτων:

Κωδικός	Σημασία
-32700	Σφάλμα ανάλυσης (μη έγκυρο JSON)
-32600	Μη έγκυρο αίτημα
-32601	Μέθοδος δεν βρέθηκε
-32602	Μη έγκυρες παράμετροι
-32603	Εσωτερικό σφάλμα

Δοκιμή Πόρων

Εμφάνιση Πόρων

Κάντε κλικ στην καρτέλα Resources
Ο Inspector καλεί το resources/list
Θα δείτε:
- URI πόρων
- Ονόματα και περιγραφές
- Τύπους MIME

Ανάγνωση Πόρου

Επιλέξτε έναν πόρο
Κάντε κλικ στο Read Resource
Δείτε το περιεχόμενο που επιστρέφεται

Παραδειγματική έξοδος:

Resource: file:///config/settings.json
Content-Type: application/json

{
  "config": {
    "debug": true,
    "maxConnections": 10
  }
}

Δοκιμή Προτροπών

Εμφάνιση Προτροπών

Κάντε κλικ στην καρτέλα Prompts
Ο Inspector καλεί το prompts/list
Δείτε διαθέσιμα πρότυπα προτροπών

Λήψη Προτροπής

Επιλέξτε μια προτροπή
Συμπληρώστε τυχόν απαιτούμενα επιχειρήματα
Κάντε κλικ στο Get Prompt
Δείτε τα απεικονισμένα μηνύματα προτροπής

Ανάλυση Αρχείου Καταγραφής Μηνυμάτων

Το αρχείο καταγραφής εμφανίζει όλα τα μηνύματα πρωτοκόλλου MCP:

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":[...]}}

Τι να Προσέξετε

Ζεύγη Αιτημάτων/Απαντήσεων: Κάθε → πρέπει να έχει το αντίστοιχο ←
Μηνύματα σφάλματος: Ψάξτε για "error" στις απαντήσεις
Χρονισμός: Μεγάλα κενά ενδέχεται να υποδεικνύουν προβλήματα απόδοσης
Έκδοση πρωτοκόλλου: Βεβαιωθείτε ότι ο διακομιστής και ο πελάτης συμφωνούν στην έκδοση

Ενσωμάτωση με το VS Code

Μπορείτε να εκτελέσετε τον Inspector απευθείας από το VS Code:

Χρήση launch.json

Προσθέστε στο .vscode/launch.json:

{
  "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"
    }
  ]
}

Χρήση Tasks

Προσθέστε στο .vscode/tasks.json:

{
  "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"
        }
      }
    }
  ]
}

Συνηθισμένα Σενάρια Αποσφαλμάτωσης

Σενάριο 1: Ο Διακομιστής δεν Συνδέεται

Συμπτώματα: Ο Inspector εμφανίζει "Disconnected" ή κολλάει στο "Connecting..."

Τσεκάρισμα:

✅ Η εντολή του διακομιστή είναι σωστή;
✅ Έχουν εγκατασταθεί όλες οι εξαρτήσεις;
✅ Η διαδρομή του διακομιστή είναι απόλυτη ή σχετική ως προς τον τρέχοντα φάκελο;
✅ Έχουν οριστεί οι απαιτούμενες μεταβλητές περιβάλλοντος;

Βήματα αποσφαλμάτωσης:

# Δοκιμάστε τον διακομιστή χειροκίνητα πρώτα
python -c "import your_server_module; print('OK')"

# Ελέγξτε για σφάλματα εισαγωγής
python -m your_server_module 2>&1 | head -20

# Επαληθεύστε ότι το MCP SDK είναι εγκατεστημένο
pip show mcp

Σενάριο 2: Τα εργαλεία δεν εμφανίζονται

Συμπτώματα: Η καρτέλα εργαλείων εμφανίζει κενή λίστα

Πιθανοί λόγοι:

Τα εργαλεία δεν καταχωρίστηκαν κατά την εκκίνηση του διακομιστή
Ο διακομιστής κατέρρευσε μετά την εκκίνηση
Ο χειριστής tools/list επιστρέφει κενό πίνακα

Βήματα αποσφαλμάτωσης:

Ελέγξτε το αρχείο καταγραφής για την απάντηση του tools/list
Προσθέστε καταγραφή (logging) στον κώδικα καταχώρισης εργαλείων σας
Επιβεβαιώστε ότι υπάρχουν οι διακοσμητές @mcp.tool() (Python)

Σενάριο 3: Ένα εργαλείο επιστρέφει σφάλμα

Συμπτώματα: Η κλήση εργαλείου επιστρέφει σφάλμα

Προσέγγιση αποσφαλμάτωσης:

Διαβάστε προσεκτικά το μήνυμα σφάλματος
Ελέγξτε αν οι τύποι παραμέτρων συμφωνούν με το σχήμα
Προσθέστε try/catch με αναλυτικά μηνύματα σφάλματος
Ελέγξτε τα αρχεία καταγραφής του διακομιστή για stack traces

Παράδειγμα βελτιωμένης διαχείρισης σφάλματος:

@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
    try:
        # Λογική εργαλείου εδώ
        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}")

Σενάριο 4: Το περιεχόμενο πόρου είναι κενό

Συμπτώματα: Ο πόρος επιστρέφει, αλλά το περιεχόμενο είναι κενό ή null

Τσεκάρισμα:

✅ Η διαδρομή αρχείου ή το URI είναι σωστό
✅ Ο διακομιστής έχει δικαίωμα ανάγνωσης του πόρου
✅ Το περιεχόμενο του πόρου επιστρέφεται σωστά

Προηγμένες λειτουργίες Inspector

Προσαρμοσμένες κεφαλίδες (SSE)

npx @modelcontextprotocol/inspector \
  --sse http://localhost:8080/sse \
  --header "Authorization: Bearer your-token"

Αναλυτική Καταγραφή

DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py

Εγγραφή Συνεδριών

Ο Inspector μπορεί να εξάγει τα αρχεία καταγραφής για μελλοντική ανάλυση:

Κάντε κλικ στο Export Log στον πίνακα μηνυμάτων
Αποθηκεύστε το αρχείο JSON
Μοιραστείτε το με μέλη της ομάδας για αποσφαλμάτωση

Καλές πρακτικές

Δοκιμάστε νωρίς και συχνά - Χρησιμοποιήστε τον Inspector κατά την ανάπτυξη, όχι μόνο όταν παρουσιαστεί πρόβλημα
Ξεκινήστε απλά - Δοκιμάστε βασική συνδεσιμότητα πριν από σύνθετες κλήσεις εργαλείων
Ελέγξτε το σχήμα - Πολλά σφάλματα προέρχονται από ασυμφωνίες τύπων παραμέτρων
Διαβάστε τα μηνύματα σφάλματος - Τα σφάλματα MCP συνήθως είναι περιγραφικά
Κρατήστε ανοιχτό τον Inspector - Βοηθάει να εντοπίζετε προβλήματα κατά την ανάπτυξη

Τι ακολουθεί

Ολοκληρώσατε την Ενότητα 3: Ξεκινώντας! Συνεχίστε τη μάθησή σας:

Ενότητα 4: Πρακτική Εφαρμογή

Πρόσθετοι Πόροι

Αποποίηση ευθυνών:
Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης AI Co-op Translator. Παρόλο που επιδιώκουμε την ακρίβεια, παρακαλούμε να σημειώσετε ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν σφάλματα ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται η επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Αποσφαλμάτωση με το MCP Inspector

Γιατί να χρησιμοποιήσετε το MCP Inspector;

Προαπαιτούμενα

Εγκατάσταση

Επιλογή 1: Εκτέλεση με npx (Συνιστάται για γρήγορη δοκιμή)

Επιλογή 2: Παγκόσμια Εγκατάσταση

Επιλογή 3: Προσθήκη στο Έργο σας

Σύνδεση με το διακομιστή σας

stdio Διακομιστές (Τοπική διαδικασία)

SSE/HTTP Διακομιστές (Δίκτυο)

Επισκόπηση διεπαφής Inspector

Δοκιμή Εργαλείων

Εμφάνιση Διαθέσιμων Εργαλείων

Εκτέλεση Εργαλείου

Αποσφαλμάτωση Σφαλμάτων Εργαλείων

Δοκιμή Πόρων

Εμφάνιση Πόρων

Ανάγνωση Πόρου

Δοκιμή Προτροπών

Εμφάνιση Προτροπών

Λήψη Προτροπής

Ανάλυση Αρχείου Καταγραφής Μηνυμάτων

Τι να Προσέξετε

Ενσωμάτωση με το VS Code

Χρήση launch.json

Χρήση Tasks

Συνηθισμένα Σενάρια Αποσφαλμάτωσης

Σενάριο 1: Ο Διακομιστής δεν Συνδέεται

Σενάριο 2: Τα εργαλεία δεν εμφανίζονται

Σενάριο 3: Ένα εργαλείο επιστρέφει σφάλμα

Σενάριο 4: Το περιεχόμενο πόρου είναι κενό

Προηγμένες λειτουργίες Inspector

Προσαρμοσμένες κεφαλίδες (SSE)

Αναλυτική Καταγραφή

Εγγραφή Συνεδριών

Καλές πρακτικές

Τι ακολουθεί

Πρόσθετοι Πόροι