MCP Apps: interface inside the client (official extension)

// app.mjs — the classes server + an MCP App (official extension io.modelcontextprotocol/ui):
// the ver_turmas tool points to the ui://turmas/painel.html interface, which the client
// renders in an isolated iframe. A client without MCP Apps support gets the normal text.
import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
import * as z from 'zod/v4';
import { createServer, TURMAS } from './servidor.mjs';

const URI = 'ui://turmas/painel.html';
// The App class comes ready-made in the package (app-with-deps.js); the View is a single HTML file, no build.
// To fit in a single <script>, we swap the final "export {… X as App …}" for "const App = X;".
const bruto = readFileSync(createRequire(import.meta.url).resolve('@modelcontextprotocol/ext-apps/app-with-deps'), 'utf8');
const exporta = bruto.match(/export\s*\{([^}]*)\};?\s*$/);
const nomeApp = exporta[1].match(/(\w+)\s+as\s+App\b/)[1];
const appJs = bruto.slice(0, exporta.index) + `\nconst App = ${nomeApp};\n`;
const html = readFileSync(new URL('./painel.html', import.meta.url), 'utf8').replace('/*APP_JS*/', () => appJs); // a function: the bundle has "$&", which replace would read as a pattern

export function createServerComApp() {
  const server = createServer();
  registerAppTool(server, 'ver_turmas', {
    title: 'Ver turmas (painel)',
    description: 'Mostra as turmas com vagas num painel. Só leitura.',
    inputSchema: z.object({ termo: z.string().min(2) }),
    outputSchema: z.object({ turmas: z.array(z.object({ id: z.string(), titulo: z.string(), vagas: z.int() })) }),
    annotations: { readOnlyHint: true },
    _meta: { ui: { resourceUri: URI } }
  }, async ({ termo }) => {
    const turmas = TURMAS.filter(t => t.titulo.toLowerCase().includes(termo.toLowerCase()));
    return { content: [{ type: 'text', text: `${turmas.length} turmas` }], structuredContent: { turmas } };
  });
  registerAppResource(server, 'Painel de turmas', URI, { description: 'Lista visual das turmas' },
    async () => ({ contents: [{ uri: URI, mimeType: RESOURCE_MIME_TYPE, text: html }] }));
  return server;
}

if (import.meta.url === `file://${process.argv[1]}`) {
  serveStdio(createServerComApp);
  console.error('turmas + MCP App: servidor no stdio');
}

<!doctype html>
<html lang="pt-BR">
<head>
<meta charset="utf-8">
<title>Turmas</title>
<style>
  body { font: 15px/1.4 system-ui, sans-serif; margin: 12px; color: #111; }
  li { margin: 4px 0; }
  .zero { color: #a00; }
</style>
</head>
<body>
<h3>Turmas encontradas</h3>
<ul id="lista"><li>aguardando o resultado da ferramenta…</li></ul>
<script type="module">
  /*APP_JS*/
  // The View talks to the client (host) via postMessage; the App class handles the handshake.
  const app = new App({ name: 'painel-turmas', version: '1.0.0' }, {});
  app.ontoolresult = ({ structuredContent }) => {
    const lista = document.getElementById('lista');
    lista.replaceChildren(...(structuredContent?.turmas ?? []).map(t => {
      const li = document.createElement('li');
      li.textContent = `${t.titulo} — ${t.vagas} vagas`;
      if (t.vagas === 0) li.className = 'zero';
      return li;
    }));
  };
  await app.connect();
</script>
</body>
</html>