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

Προσθήκη Διεπαφής με Εφαρμογές MCP

Μάθημα 6 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Πότε να προσθέσετε μια διεπαφή
  2. Η αρχή των Εφαρμογών MCP
  3. Πλευρά διακομιστή: δήλωση του πόρου και του εργαλείου
  4. Πλευρά iframe: η γέφυρα JSON-RPC
  5. Επιλογή παρουσίασης
  6. Επεκτάσεις ειδικές για το ChatGPT
  7. Τρία είδη κατάστασης
  8. Πολιτική Ασφαλείας Περιεχομένου (CSP)
  9. Βασικά σημεία

Μάθημα ξαναγράφηκε στις 3 Νοεμβρίου 2026 με βάση τη σελίδα Add UI to your MCP server από την τεκμηρίωση των Πρόσθετων OpenAI και τον κώδικα για το @modelcontextprotocol/ext-apps 1.7.5. Το προηγούμενο μάθημα περιέγραφε «widgets» (defineWidget) από ένα ανύπαρκτο SDK· μια διεπαφή είναι ένας πόρος Εφαρμογών MCP που αποδίδεται από το ChatGPT σε ένα iframe. Πηγές: Add UI to your MCP server · MCP Apps Specification.

Πότε να προσθέσετε μια διεπαφή

Η διεπαφή είναι προαιρετική. Προσθέστε μία όταν ο χρήστης χρειάζεται να επιθεωρήσει, να συγκρίνει, να τροποποιήσει, να επιβεβαιώσει ή να περιηγηθεί σε δομημένες πληροφορίες—και διατηρήστε τα εργαλεία σας χρήσιμα χωρίς αυτήν, ώστε το ChatGPT και το Codex να μπορούν να οδηγούν τη ροή εργασίας σε πελάτες που δεν εμφανίζουν ένα στοιχείο.

Η αρχή των Εφαρμογών MCP

Το ChatGPT υλοποιεί το ανοιχτό πρότυπο Εφαρμογών MCP. Ο διακομιστής δηλώνει έναν πόρο διεπαφής, αναγνωρισμένο από ένα URI ui://… και εξυπηρετούμενο με τον τύπο MIME text/html;profile=mcp-app· ένα εργαλείο συνδέεται σε αυτόν μέσω του _meta.ui.resourceUri. Όταν καλείται αυτό το εργαλείο, το ChatGPT εμφανίζει τον πόρο σε ένα iframe, δίπλα στη συνομιλία. Το στοιχείο επικοινωνεί με τον οικοδεσπότη μέσω JSON-RPC χρησιμοποιώντας postMessage:

ΜήνυμαΡόλος
ui/initialize και μετά ui/notifications/initializedΆνοιγμα διαλόγου με τον οικοδεσπότη
ui/notifications/tool-inputΛήψη ορισμάτων κλήσης εργαλείου
ui/notifications/tool-resultΛήψη αποτελέσματος εργαλείου
tools/callΚλήση εργαλείου διακομιστή από τη διεπαφή
ui/messageΑποστολή μηνύματος παρακολούθησης στη συνομιλία
ui/update-model-contextΕνημέρωση του μοντέλου για τρέχουσα επιλογή ή τροποποίηση

Πλευρά διακομιστή: δήλωση του πόρου και του εργαλείου

Ας επανεξετάσουμε τον διακομιστή σημειώσεων από το Μάθημα 4. Το πακέτο @modelcontextprotocol/ext-apps (στην έκδοση 1.x με SDK v1) παρέχει δύο βοηθήματα: το registerAppResource, το οποίο εφαρμόζει τον σωστό τύπο MIME που εκτίθεται από τη σταθερά RESOURCE_MIME_TYPE από προεπιλογή, και το registerAppTool, το οποίο απαιτεί τα μεταδεδομένα της διεπαφής.

import { readFileSync } from "node:fs";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const URI_CARTE = "ui://widget/notes-v1.html"; // με έκδοση: αυτό είναι ένα κλειδί cache
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Προσθήκη μέσα στο creerServeur(), δίπλα στα list_notes και add_note
registerAppResource(server, "notes-widget", URI_CARTE, {}, async () => ({
  contents: [{ uri: URI_CARTE, mimeType: RESOURCE_MIME_TYPE, text: carteHtml }],
}));

registerAppTool(
  server,
  "show_notes",
  {
    title: "Show notes",
    description:
      "Displays notes in a card. To show only a subset, call list_notes first.",
    inputSchema: {},
    outputSchema: schemaNotes,
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    _meta: { ui: { resourceUri: URI_CARTE } },
  },
  async () => ({
    structuredContent: { notes },
    content: [{ type: "text", text: `${notes.length} note(s) displayed.` }],
  })
);

Μόνο το show_notes φέρει τη διεπαφή. Αυτή είναι η αποσύνδεση που συνιστά η OpenAI: αν κάθε εργαλείο επέστρεφε ένα πρότυπο, το ChatGPT θα ξανασχεδίαζε το iframe πολύ συχνά. Τα εργαλεία δεδομένων (list_notes, add_note) αναζητούν, υπολογίζουν ή τροποποιούν και επιστρέφουν μόνο το αποτέλεσμά τους· τα εργαλεία απόδοσης λαμβάνουν τελικά δεδομένα και επιστρέφουν το πρότυπο. Το μοντέλο μπορεί έτσι να εργαστεί στα δεδομένα—φιλτράρισμα, διασταύρωση—πριν αποφασίσει να εμφανίσει, και η κάρτα εμφανίζεται μόνο μία φορά, με ένα επαληθευμένο πλαίσιο. Υποδείξτε την εξάρτηση στην περιγραφή του εργαλείου απόδοσης, όπως φαίνεται παραπάνω.

Πλευρά iframe: η γέφυρα JSON-RPC

Το στοιχείο ταιριάζει εδώ σε ένα μόνο αρχείο HTML, χωρίς βήμα δημιουργίας (build). Ανοίγει τον διάλογο με τον οικοδεσπότη και στη συνέχεια εμφανίζει κάθε αποτέλεσμα εργαλείου που λαμβάνει.

<!doctype html>
<html lang="en">
  <head><meta charset="utf-8" /><title>Notes</title></head>
  <body>
    <ul id="liste"></ul>
    <script type="module">
      const liste = document.querySelector("#liste");
      const enAttente = new Map();
      let dernierId = 0;

      const envoyer = (message) =>
        window.parent.postMessage({ jsonrpc: "2.0", ...message }, "*");
      const requete = (method, params) =>
        new Promise((resolve, reject) => {
          const id = ++dernierId;
          enAttente.set(id, { resolve, reject });
          envoyer({ id, method, params });
        });

      const afficher = (resultat) => {
        const notes = resultat?.structuredContent?.notes ?? [];
        liste.replaceChildren(
          ...notes.map((note) => {
            const li = document.createElement("li");
            li.textContent = note.text; // ποτέ innerHTML σε ληφθέντα δεδομένα
            return li;
          })
        );
      };

      window.addEventListener("message", (event) => {
        if (event.source !== window.parent) return;
        const msg = event.data;
        if (msg?.jsonrpc !== "2.0") return;
        if (typeof msg.id === "number" && enAttente.has(msg.id)) {
          const { resolve, reject } = enAttente.get(msg.id);
          enAttente.delete(msg.id);
          msg.error ? reject(msg.error) : resolve(msg.result);
        } else if (msg.method === "ui/notifications/tool-result") {
          afficher(msg.params);
        }
      });

      await requete("ui/initialize", {
        appInfo: { name: "notes-widget", version: "0.1.0" },
        appCapabilities: {},
        protocolVersion: "2026-01-26",
      });
      envoyer({ method: "ui/notifications/initialized", params: {} });
    </script>
  </body>
</html>

Το ληφθέν αποτέλεσμα είναι μη αξιόπιστα δεδομένα: εμφανίστε το με textContent, ποτέ injecting το ως HTML. Για μια πλουσιότερη διεπαφή, το ίδιο πακέτο παρέχει μια App κλάση πλευράς προγράμματος περιήγησης που encapsulates αυτή τη γέφυρα (λήψη αποτελεσμάτων, κλήση εργαλείων), προς ενσωμάτωση σε ένα bundle χτισμένο με esbuild· το αποθετήριο παραδειγμάτων OpenAI δείχνει πλήρη στοιχεία React.

Επιλογή παρουσίασης

Ξεκινήστε με την ενσωματωμένη εμφάνιση και ζητήστε περισσότερο χώρο μόνο εάν η ροή εργασίας το απαιτεί:

ΠαρουσίασηΧρήση
Ενσωματωμένη κάρταΈνα στοχευμένο αποτέλεσμα, μια επιβεβαίωση, λίγες ενέργειες, χωρίς βαθιά πλοήγηση
Ενσωματωμένο καρουζέλΠεριήγηση και επιλογή ανάμεσα σε λίγες παρόμοιες, οπτικές επιλογές
Πλήρης οθόνηΜια πλούσια εργασία: χάρτης, καμβάς επεξεργασίας, λεπτομερής εξερεύνηση· η περιοχή εισαγωγής του ChatGPT παραμένει διαθέσιμη
Picture-in-pictureΜια ongoing δραστηριότητα που πρέπει να παραμείνει ορατή κατά τη διάρκεια της συνομιλίας: live session, παιχνίδι, βίντεο

Επεκτάσεις ειδικές για το ChatGPT

Μόλις η ροή Εφαρμογών MCP είναι σε ισχύ, το ChatGPT προσφέρει επεκτάσεις μέσω του window.openai, προς χρήση μόνο για ό,τι δεν καλύπτει το πρότυπο. Για κοινές ανάγκες, προτιμήστε το πρότυπο· τα aliases του ChatGPT παραμένουν διαθέσιμα για υπάρχουσες ενσωματώσεις:

ΑνάγκηΠρότυπο Εφαρμογών MCPAlias ChatGPT
Σύνδεση εργαλείου με διεπαφή_meta.ui.resourceUri_meta["openai/outputTemplate"]
Λήψη ορισμάτωνui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Λήψη αποτελέσματοςui/notifications/tool-resultwindow.openai.toolOutput
Κλήση εργαλείουtools/callwindow.openai.callTool
Αποστολή μηνύματος παρακολούθησηςui/messagewindow.openai.sendFollowUpMessage

Οι επεκτάσεις χωρίς ισοδύναμο στο πρότυπο καλύπτουν την ενσωματωμένη ολοκλήρωση αγοράς (requestCheckout), αρχεία (uploadFile, selectFiles, getFileDownloadUrl), παράθυρα διαλόγου διαχειριζόμενα από τον οικοδεσπότη (requestModal), και την επιμονή κατάστασης στοιχείου (widgetState, setWidgetState). Ανιχνεύστε κάθε δυνατότητα πριν τη χρήση, με fallback όταν είναι εφικτό—και ποτέ μην ελέγχετε το όνομα του οικοδεσπότη, ελέγξτε τη συνάρτηση:

const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
  await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
  document.body.textContent = "This host does not support modal windows.";
}

Τρία είδη κατάστασης

ΚατάστασηΙδιοκτήτηςΔιάρκεια ζωήςΠαραδείγματα
Επιχειρηματικά δεδομένα, πηγή αλήθειαςΔιακομιστής MCP ή εξωτερική υπηρεσίαΜακροπρόθεσμαΕργασίες, tickets, έγγραφα
Κατάσταση διεπαφής, εφήμερηΣτιγμιότυπο στοιχείουΔιάρκεια της εμφάνισής τουΕπιλεγμένη γραμμή, ανοιχτό πάνελ, σειρά ταξινόμησης
Διαρκής κατάσταση μεταξύ συνεδριώνΑποθηκευτικός χώρος που ελέγχετεΜεταξύ συνομιλιών και συσκευώνΑποθηκευμένα φίλτρα, λειτουργία εμφάνισης

Τα επιχειρηματικά δεδομένα παραμένουν στον διακομιστή: η διεπαφή καλεί ένα εργαλείο, ο διακομιστής επικυρώνει και ενημερώνει, και στη συνέχεια επιστρέφει την κατάσταση αναφοράς, την οποία η διεπαφή εμφανίζει διατηρώντας ό,τι αφορά την παρουσίαση. Όταν το μοντέλο χρειάζεται να γνωρίζει μια επιλογή, στείλτε την μέσω ui/update-model-context. Το window.openai.setWidgetState (συγχρονικό, χωρίς await) διατηρεί την κατάσταση ενός στιγμιότυπου, όχι επιχειρηματικά δεδομένα. Η διαρκής κατάσταση πηγαίνει στον αποθηκευτικό σας χώρο, πίσω από έλεγχο ταυτότητας· αποφύγετε το localStorage, το οποίο δεν προσφέρει ούτε συνέχεια μεταξύ συσκευών ούτε αξιοπιστία σε ένα απομονωμένο iframe.

Πολιτική Ασφαλείας Περιεχομένου (CSP)

Το στοιχείο δηλώνει, στα μεταδεδομένα του πόρου του (_meta.ui.csp), τους ακριβείς τομείς που χρησιμοποιεί: connectDomains για κλήσεις API, resourceDomains για scripts, styles και images, frameDomains μόνο εάν πρέπει να ενσωματώσει συγκεκριμένα iframes—τα nested frames μπλοκάρονται από προεπιλογή. Διατηρήστε αυτές τις λίστες όσο το δυνατόν πιο στενές: η αναθεώρηση του πρόσθετου συγκρίνει την δηλωθείσα πολιτική με την πραγματική συμπεριφορά της διεπαφής. Και αντιμετωπίστε το URI του πόρου ως κλειδί cache: για κάθε ασύμβατη αλλαγή στο HTML, JavaScript ή CSS, δημοσιεύστε ένα νέο URI και ενημερώστε τα εργαλεία που το αναφέρουν.

Δύο τελικές λεπτομέρειες: ο οικοδεσπότης αντικατοπτρίζει τη γλώσσα του χρήστη στο document.documentElement.lang, προς χρήση για μετάφραση και μορφοποίηση ημερομηνιών και αριθμών· και η βιβλιοθήκη @openai/apps-sdk-ui παρέχει κουμπιά, κάρτες και πεδία που ταιριάζουν με το ChatGPT αν δεν θέλετε να επανασχεδιάσετε τα πάντα.

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

  • Μια διεπαφή είναι ένας πόρος ui:// τύπου text/html;profile=mcp-app, συνδεδεμένος με ένα εργαλείο μέσω _meta.ui.resourceUri
  • Το στοιχείο επικοινωνεί με τον οικοδεσπότη μέσω JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Διαχωρίστε τα εργαλεία δεδομένων από τα εργαλεία απόδοσης: μόνο το εργαλείο απόδοσης φέρει το πρότυπο
  • Το window.openai παρέχει μόνο επεκτάσεις, προς ανίχνευση πριν τη χρήση
  • Επιχειρηματικά δεδομένα στον διακομιστή, στενή CSP, URI πόρου με έκδοση