Προσθήκη Διεπαφής με Εφαρμογές MCP
Σε αυτήν τη σελίδα
Μάθημα ξαναγράφηκε στις 3 Νοεμβρίου 2026 με βάση τη σελίδα Add UI to your MCP server από την τεκμηρίωση των Πρόσθετων OpenAI και τον κώδικα για το
@modelcontextprotocol/ext-apps1.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 παραμένουν διαθέσιμα για υπάρχουσες ενσωματώσεις:
| Ανάγκη | Πρότυπο Εφαρμογών MCP | Alias ChatGPT |
|---|---|---|
| Σύνδεση εργαλείου με διεπαφή | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Λήψη ορισμάτων | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Λήψη αποτελέσματος | ui/notifications/tool-result | window.openai.toolOutput |
| Κλήση εργαλείου | tools/call | window.openai.callTool |
| Αποστολή μηνύματος παρακολούθησης | ui/message | window.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 πόρου με έκδοση