Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Ο διακομιστής MCP: Εργαλεία, αποτελέσματα και ανάπτυξη

Μάθημα 5 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Ο διακομιστής, η ταυτότητά του και οι οδηγίες του
  2. Ένα εργαλείο ανά ενέργεια
  3. Χρήσιμα αποτελέσματα χωρίς διεπαφή
  4. Σημειώσεις και elicitation
  5. Πολλαπλοί λογαριασμοί και εταιρική γνώση
  6. Ανάπτυξη του σημείου τελικού
  7. Εξέλιξη χωρίς διακοπές
  8. Υπενθυμίσεις ασφαλείας
  9. Βασικά σημεία

Μάθημα ξαναγράφηκε στις 3 Νοεμβρίου 2026 με βάση τη σελίδα Build an MCP server από την τεκμηρίωση των OpenAI Plugins και τον κώδικα του MCP TypeScript SDK (1.32.2). Το προηγούμενο μάθημα περιέγραφε «ενέργειες» (defineAction, ActionError) από ένα ανύπαρκτο SDK· αυτόν τον ρόλο έχουν πλέον τα εργαλεία MCP. Πηγές: Build an MCP server · MCP TypeScript SDK.

Ο διακομιστής, η ταυτότητά του και οι οδηγίες του

Δημιουργήστε έναν διακομιστή MCP με σταθερό όνομα και έκδοση. Κατά την αρχικοποίηση, μπορεί επίσης να επιστρέψει ένα πεδίο instructions που το ChatGPT και το Codex διαβάζουν παράλληλα με τα μεταδεδομένα των εργαλείων. Προορίστε αυτό το πεδίο για οδηγίες που ισχύουν για όλα τα εργαλεία—όπως μια υποχρεωτική σειρά κλήσεων ή ένα κοινό όριο ρυθμού—και κρατήστε το βασικό περιεχόμενο εντός των πρώτων 512 χαρακτήρων. Μην αντιγράφετε-επικολλάτε περιγραφές εργαλείων εδώ και μην προσπαθείτε να αλλάξετε την προσωπικότητα του μοντέλου.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer(
  { name: "acme-projects", version: "1.0.0" },
  {
    instructions:
      "Before modifying a project, call get_project to confirm its ID and status.",
  }
);

Ένα εργαλείο ανά ενέργεια

Δημιουργήστε ένα εργαλείο για κάθε διακριτή ενέργεια: list_projects, get_project, update_project, αντί για ένα ενιαίο εργαλείο γενικής χρήσης με πολυάριθμες λειτουργίες. Κάθε εργαλείο συνδυάζει ένα όνομα προσανατολισμένο στη δράση, έναν ευανάγνωστο τίτλο, μια περιγραφή που εξηγεί πότε να το χρησιμοποιήσετε, ένα ρητό σχήμα εισόδου, ένα σχήμα εξόδου εάν επιστρέφει δομημένα δεδομένα, ακριβείς σημειώσεις και έναν χειριστή που εξουσιοδοτεί το αίτημα πριν ενεργήσει. Το μοντέλο βασίζεται σε αυτά τα μεταδεδομένα για να αποφασίσει εάν και πώς θα καλέσει το εργαλείο—αντιμετωπίστε το ως μέρος της εμπειρίας χρήστη.

import { z } from "zod";

const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });

server.registerTool(
  "get_project",
  {
    title: "View a project",
    description:
      "Use when the user wants details about a specific project in their Acme workspace. " +
      "Requires the ID returned by list_projects.",
    inputSchema: { id: z.string().min(1) },
    outputSchema: { project: project },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
  },
  async ({ id }, extra) => {
    const user = await authenticate(extra); // Your access control (Lesson 8)
    const found = await loadProject(user, id); // Your data access
    if (!found) {
      return {
        isError: true,
        content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
      };
    }
    return {
      structuredContent: { project: found },
      content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
    };
  }
);

Οι συναρτήσεις authenticate και loadProject είναι δικές σας. Το κρίσιμο σημείο είναι η τοποθέτησή τους: η εξουσιοδότηση γίνεται στον διακομιστή, με κάθε αίτημα. Μην βασίζεστε ποτέ στο μοντέλο για να αποφασίσει εάν ένας χρήστης έχει άδεια πρόσβασης σε δεδομένα.

Χρήσιμα αποτελέσματα χωρίς διεπαφή

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

  • structuredContent: συνοπτικά δεδομένα που το μοντέλο μπορεί να επιθεωρήσει και να επαναχρησιμοποιήσει σε επόμενες κλήσεις·
  • content: κείμενο ή άλλο περιεχόμενο MCP που το βοηθά να απαντήσει·
  • _meta: δεδομένα που προορίζονται για τον πελάτη, κρυμμένα από το μοντέλο.

Επιστρέψτε αρκετές πληροφορίες ώστε το μοντέλο να ολοκληρώσει την εργασία χωρίς οπτικό στοιχείο, χρησιμοποιώντας σταθερά αναγνωριστικά που μπορούν να επαναχρησιμοποιηθούν από επόμενα εργαλεία. Δύο συμπεριφορές του SDK αξίζουν προσοχής. Ένα εργαλείο που δηλώνει outputSchema πρέπει να επιστρέφει συμμορφούμενο structuredContent σε όλα τα επιτυχημένα αποτελέσματα· διαφορετικά, το SDK ρίχνει σφάλμα επικύρωσης. Ένα επιχειρηματικό σφάλμα—όπως ένα λείπον έργο ή μια απορριφθείσα ενέργεια—σηματοδοτείται από ένα αποτέλεσμα με isError: true συνοδευόμενο από επεξηγηματικό κείμενο που το μοντέλο μπορεί να μεταφέρει στον χρήστη· αυτός ο τύπος αποτελέσματος παρακάμπτει την επικύρωση του σχήματος εξόδου.

Μην συμπεριλαμβάνετε ποτέ μυστικά, διακριτικά πρόσβασης ή περιττά προσωπικά δεδομένα σε ένα αποτέλεσμα και μην αντιμετωπίζετε το _meta ως ασφαλές κρυφό σημείο: αυτό το πεδίο είναι κρυμμένο από το μοντέλο, αλλά δεν είναι προστατευμένο.

Σημειώσεις και elicitation

Οι σημειώσεις πρέπει να αντικατοπτρίζουν την πραγματική συμπεριφορά του εργαλείου: ορίστε το readOnlyHint σε true μόνο εάν δεν μπορεί να τροποποιήσει τίποτα, το destructiveHint σε true εάν μπορεί να προκαλέσει μη αναστρέψιμο ή δύσκολα αναιρέσιμο αποτέλεσμα, και το openWorldHint σε true εάν αγγίζει το δημόσιο διαδίκτυο ή ανοιχτές εξωτερικές οντότητες. Βοηθούν το ChatGPT και το Codex να επιλέξουν τη σωστή συμπεριφορά επιβεβαίωσης· δεν αντικαθιστούν την εξουσιοδότηση, την επικύρωση ή τη λογική επιβεβαίωσης στον διακομιστή σας.

Όταν ο διακομιστής χρειάζεται δομημένες πληροφορίες που λείπουν από την κλήση—όπως μια ημερομηνία ή μια επιλογή μεταξύ δύο επιλογών—μπορεί να τις ζητήσει μέσω elicitation, ενός μηχανισμού του πρωτοκόλλου MCP. Περιορίστε αυτό σε ό,τι ο χρήστης μπορεί εύλογα να παράσχει· μην το χρησιμοποιείτε ποτέ για τη συλλογή μυστικών ή την παράκαμψη της κανονικής αυθεντικοποίησης.

Πολλαπλοί λογαριασμοί και εταιρική γνώση

Δύο προαιρετικές συμβατότητες βελτιώνουν την ενσωμάτωση. Για να βοηθήσετε τους χρήστες που συνδέουν πολλαπλούς λογαριασμούς, εκθέστε ένα εργαλείο προφίλ που είναι αυθεντικοποιημένο, μόνο για ανάγνωση και σημειωμένο με _meta["openai/profile"]: true. Η OpenAI το χρησιμοποιεί για να αναγνωρίσει συνδεδεμένους λογαριασμούς και να βοηθήσει τους χρήστες να τους διακρίνουν. Το προφίλ προέρχεται από τα επικυρωμένα διαπιστευτήρια του αιτήματος και κάθε κλήση παραμένει περιορισμένη σε αυτά τα διαπιστευτήρια.

Η λειτουργία company knowledge του ChatGPT μπορεί να χρησιμοποιήσει τα εργαλεία μόνο για ανάγνωση του διακομιστή σας. Για να καταστεί ένα πρόσθετο επιλέξιμο ως πηγή, υλοποιήστε τα τυπικά σχήματα εισόδου για τα εργαλεία search και fetch, σημειώστε άλλα εργαλεία μόνο για ανάγνωση με readOnlyHint: true και επιστρέψτε απόλυτες, ανοιχτές από τον χρήστη URL για πηγές που το μοντέλο πρέπει να αναφέρει.

Ανάπτυξη του σημείου τελικού

Η δημόσια υποβολή απαιτεί έναν διακομιστή σε μια σταθερή, δημόσια προσβάσιμη διεύθυνση HTTPS. Αυτό το σημείο τελικού πρέπει να υποστηρίζει τη μεταφορά streamable HTTP, να αποκρίνεται σε μια σταθερή URL (συνήθως καταλήγει σε /mcp), να καλύπτει τις απαιτήσεις λανθάνουσας κατάστασης και διαθεσιμότητας των ροών εργασίας σας, να φτάνει στις υπηρεσίες και τα δεδομένα σας, να διατηρεί τα όρια αυθεντικοποίησης και εξουσιοδότησης και να παράγει αρχεία καταγραφής και μετρικές για την αρχικοποίηση και τις αποτυχίες κλήσεων εργαλείων.

Το Secure MCP Tunnel της OpenAI σας επιτρέπει να συνδέσετε έναν ιδιωτικό διακομιστή στο ChatGPT, αλλά δεν πληροί τις απαιτήσεις δημόσιας υποβολής, όπως ούτε και μια προσωρινή σήραγγα ή τοπική διεύθυνση. Εάν ο διακομιστής πρέπει να παραμείνει ιδιωτικός, τοποθετήστε έναν δημόσιο διακομιστή μεσολάβησης HTTPS μπροστά του: το mTLS που διαχειρίζεται η OpenAI αυθεντικοποιεί το ChatGPT ως πελάτη, το OAuth 2.1 αυθεντικοποιεί τους χρήστες σας και μια λίστα επιτρεπόμενων IP—συμπεριλαμβανομένων των εύρους που δημοσιεύονται από την OpenAI για συνδέσμους ChatGPT, ενημερωμένα αυτόματα—μπορεί να προστεθεί, αλλά δεν αντικαθιστά ποτέ την αυθεντικοποίηση.

Πριν τη δημοσίευση: εισάγετε διαπιστευτήρια μέσω του διαχειριστή μυστικών του host σας, διαμορφώστε τον διακομιστή εξουσιοδότησης και τις ανακατευθύνσεις, ορίστε χρονικά όρια και όρια ρυθμού για ακριβά ή εξωτερικά ορατά εργαλεία, αφαιρέστε αποκρίσεις εντοπισμού σφαλμάτων και περιττά προσωπικά δεδομένα και επαληθεύστε ότι τα αρχεία καταγραφής δεν περιέχουν διακριτικά ή ευαίσθητα αποτελέσματα. Μετά την ανάπτυξη, επαναλάβετε το MCP Inspector έναντι της διεύθυνσης παραγωγής.

Εξέλιξη χωρίς διακοπές

Διατηρήστε τα δημοσιευμένα ονόματα εργαλείων και τα σχήματα συμβατά προς τα πίσω: προσθέστε πεδία ή εργαλεία, αλλά μην σπάσετε υπάρχουσες συμβάσεις. Εάν αλλάξουν τα μεταδεδομένα, ανανεώστε τη σύνδεση και επαναλάβετε τη σουίτα αξιολόγησής σας πριν την υποβολή. Για μια διεπαφή, αλλάξτε το αναγνωριστικό πόρου όταν το HTML, το JavaScript ή το CSS εξελίσσονται με τρόπο που θα μπορούσε να σπάσει ένα στοιχείο σε cache.

Υπενθυμίσεις ασφαλείας

  • Όλες οι είσοδοι εργαλείων είναι μη έμπιστες: επικυρώστε τες και επιβάλετε την εξουσιοδότηση στον διακομιστή
  • Απαιτήστε επιβεβαίωση για εγγραφές υψηλού αντίκτυπου
  • Κρατήστε μυστικά και ευαίσθητα δεδομένα εκτός μεταδεδομένων και αποτελεσμάτων
  • Καταγράψτε αρκετά για διερεύνηση, αλλά αποκλείστε διαπιστευτήρια και περιττά προσωπικά δεδομένα
  • Περιορίστε τον ρυθμό για ακριβές ή εξωτερικά ορατές ενέργειες

Βασικά σημεία

  • Ένας διακομιστής με όνομα και έκδοση με σύντομες, διατομεακές instructions
  • Ένα εργαλείο ανά ενέργεια, με τίτλο, περιγραφή πρόθεσης, σχήματα, σημειώσεις και εξουσιοδότηση στον χειριστή
  • structuredContent συμβατό με το σχήμα εξόδου, isError: true για επιχειρηματικά σφάλματα, τίποτα μυστικό στο _meta
  • Δημοσίευση: σταθερό, δημόσιο HTTPS μέσω streamable HTTP· το Secure MCP Tunnel είναι ανεπαρκές
  • Συμβάσεις συμβατές προς τα πίσω και εκδοσιοποιημένα αναγνωριστικά πόρων