@sendora/mcp 1.4.1 → 1.5.1

package/dist/handler.js

@@ -13,8 +13,10 @@ export const MAX_BODY_BYTES = 8 * 1024 * 1024;
  * the oldest forgotten first. A key or an app's token is never kept: a
  * request hands it on and drops it (docs/design/mcp.md §2.3); the exchange's
  * own credential is kept for that minute. A revoked key or an ended
- * connection may list tools for that minute; every call it makes is refused
- * by the API meanwhile (docs/design/oauth.md §6.1).
+ * connection may list tools for that minute, and every call that reaches the
+ * API is refused meanwhile. A connected app's `list_servers` answers from
+ * the kept exchange and never reaches the API, so it may still list servers
+ * the grant no longer reaches (docs/design/oauth.md §6.1).
  */
 export class KeyCache {
     #entries = new Map();

package/dist/screens.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+/*
+ * The two screens (docs/design/oauth.md §9), as MCP Apps: the extension
+ * io.modelcontextprotocol/ui. A tool names its screen in `_meta`, and a host
+ * that renders MCP Apps shows the tool's structured content in it; every
+ * other client reads the tool's text answer, which a screen leaves as it was.
+ * Each screen is one HTML document with its own script and style, which
+ * scripts/build-screens.ts builds from screens/. It loads nothing from
+ * outside, so it declares no origins and the host's strictest policy holds.
+ */
+export const SCREEN_MIME_TYPE = 'text/html;profile=mcp-app';
+export const messageTimeline = {
+    name: 'message-timeline',
+    uri: 'ui://sendora/message-timeline',
+    title: 'Message timeline',
+    description: "A message's status for each recipient, its stream, and every event with its time and the receiver's answer.",
+};
+export const domainRecords = {
+    name: 'domain-records',
+    uri: 'ui://sendora/domain-records',
+    title: 'DNS records',
+    description: "A sending domain's two DNS records, whether each checks out and when they were last checked, with a button that checks again.",
+};
+export const screens = [messageTimeline, domainRecords];
+/** The `_meta` of a tool shown in a screen: the extension's key, and the flat key that hosts read before it. */
+export function shownIn(screen) {
+    return { ui: { resourceUri: screen.uri }, 'ui/resourceUri': screen.uri };
+}
+/** The host draws the border and the background, which a screen leaves transparent. */
+const RESOURCE_META = { ui: { prefersBorder: true } };
+const HOUR = { ttlMs: 3_600_000, cacheScope: 'public' };
+const generated = new URL('./generated/screens/', import.meta.url);
+const documents = new Map();
+/** The screen's document beside this file: src/generated in the repository, dist/generated in the package. */
+export function htmlOf(screen) {
+    let document = documents.get(screen.name);
+    if (document === undefined) {
+        try {
+            document = readFileSync(new URL(`${screen.name}.html`, generated), 'utf8');
+        }
+        catch (error) {
+            throw new Error('The screens are missing; in the repository, run node apps/mcp/scripts/build-screens.ts', { cause: error });
+        }
+        documents.set(screen.name, document);
+    }
+    return document;
+}
+/** Registers each screen as a resource. The document is read when a host first asks for it. */
+export function registerScreens(server, shown) {
+    for (const screen of shown) {
+        server.registerResource(screen.name, screen.uri, {
+            title: screen.title,
+            description: screen.description,
+            mimeType: SCREEN_MIME_TYPE,
+            _meta: RESOURCE_META,
+            cacheHint: HOUR,
+        }, () => ({
+            contents: [
+                {
+                    uri: screen.uri,
+                    mimeType: SCREEN_MIME_TYPE,
+                    text: htmlOf(screen),
+                    _meta: RESOURCE_META,
+                },
+            ],
+        }));
+    }
+}

package/dist/server.js

@@ -3,6 +3,7 @@ import { registerDocuments } from './documents.js';
 import { instructionsFor } from './instructions.js';
 import { listed, targetsFor } from './listing.js';
 import { registerPrompts } from './prompts.js';
+import { registerScreens } from './screens.js';
 import { toolTable } from './tool-table.js';
 import { MCP_VERSION } from './version.js';
 const HOUR = { ttlMs: 3_600_000, cacheScope: 'public' };
@@ -13,7 +14,8 @@ const MINUTE = { ttlMs: 60_000, cacheScope: 'private' };
  * lists and no other, so a tool it may not use is unknown to it. Without a
  * key every list is the documentation's, which changes only with a release,
  * so anyone may cache it an hour; with one, what is listed depends on the
- * key, so only this client may, for a minute (§4.1).
+ * key, so only this client may, for a minute (§4.1). A screen is registered
+ * where a tool that names it is (docs/design/oauth.md §9).
  */
 export function buildServer(docs, connection) {
     const lists = connection.kind === 'none' ? HOUR : MINUTE;
@@ -33,11 +35,16 @@ export function buildServer(docs, connection) {
             'server/discover': lists,
         },
     });
+    const screens = new Set();
     for (const tool of toolTable) {
         if (listed(tool, connection)) {
             tool.register(server, { docs, connection, targets: targetsFor(tool, connection) });
+            if (tool.screen !== undefined) {
+                screens.add(tool.screen);
+            }
         }
     }
+    registerScreens(server, screens);
     registerDocuments(server, docs);
     registerPrompts(server);
     return server;

package/dist/tools/domains.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { toolError } from '../errors.js';
+import { domainRecords, shownIn } from '../screens.js';
 import { READING } from '../tool.js';
 import { accountConnectionOf } from './servers.js';
 /** A DNS record a domain needs and whether it was seen, for a sending domain and a domain for receiving alike. */
@@ -78,6 +79,7 @@ export const checkDomainTool = {
     class: 'read',
     reach: 'account',
     operations: ['POST /v1/domains/{id}/verify'],
+    screen: domainRecords,
     register: (server, { connection }) => server.registerTool('check_domain', {
         title: 'Check a sending domain',
         description: "Looks up both records of one of the account's sending domains now and answers the domain as it stands, with what each lookup found: ok, missing, mismatch or dns_error. Mail may go out from the domain once both are ok; a record just added may take a while to be seen. A verified domain whose record is found missing keeps sending for 24 hours (failingSince), and a dns_error changes nothing. A check that begins that warning or ends the verification mails the account's administrators, as Sendora's own checks do.",
@@ -86,6 +88,7 @@ export const checkDomainTool = {
         }),
         outputSchema: checkedDomainOutput,
         annotations: { ...READING, openWorldHint: true },
+        _meta: shownIn(domainRecords),
     }, async ({ domainId }) => {
         try {
             const domain = await accountConnectionOf(connection).account.domains.verify(domainId);
@@ -106,6 +109,7 @@ export const addDomainTool = {
     class: 'write',
     reach: 'account',
     operations: ['POST /v1/domains'],
+    screen: domainRecords,
     register: (server, { connection }) => server.registerTool('add_domain', {
         title: 'Add a sending domain',
         description: "Adds a domain the account sends from, with a DKIM key of its own, and answers the two records for the user to add to the domain's DNS: a CNAME for the return path, which also satisfies SPF, and a TXT record with the DKIM key. check_domain then looks them up, and every server of the account may send from the domain once both are seen. A domain the account already has is refused with domain_exists.",
@@ -121,6 +125,7 @@ export const addDomainTool = {
             idempotentHint: false,
             openWorldHint: false,
         },
+        _meta: shownIn(domainRecords),
     }, async (request) => {
         try {
             const domain = await accountConnectionOf(connection).account.domains.create(request);

package/dist/tools/messages.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { toolError } from '../errors.js';
+import { messageTimeline, shownIn } from '../screens.js';
 import { READING } from '../tool.js';
 import { registerServerTool } from '../target.js';
 const recipientStatus = z.enum(['queued', 'delivered', 'deferred', 'bounced', 'expired']);
@@ -124,6 +125,7 @@ export const getMessageTool = {
     class: 'read',
     reach: 'server',
     operations: ['GET /v1/messages/{id}'],
+    screen: messageTimeline,
     register: (server, { connection, targets }) => registerServerTool(server, targets, 'get_message', {
         title: 'Read one message and its timeline',
         description: "Reads one message of this server's log by its messageId: its recipients and their state, its attachments described but never their content, and every event on its timeline, oldest first, with the receiver's answer. The body is never returned.",
@@ -132,6 +134,7 @@ export const getMessageTool = {
         }),
         outputSchema: messageDetailOutput,
         annotations: READING,
+        _meta: shownIn(messageTimeline),
     }, async ({ messageId }, { sendora }) => {
         try {
             const message = await sendora.messages.get(messageId);

package/dist/tools/send.js

@@ -1,6 +1,7 @@
 import { SendoraError } from '@sendora/sdk';
 import { z } from 'zod';
 import { toolError } from '../errors.js';
+import { messageTimeline, shownIn } from '../screens.js';
 import { messageDetailOutput } from './messages.js';
 import { sendInput } from './send-input.js';
 import { modesOf, registerServerTool } from '../target.js';
@@ -82,7 +83,7 @@ export function notesFor(outcome, test, waitSeconds) {
     }
     return notes;
 }
-const outputSchema = z.object({
+export const sentOutput = z.object({
     messageId: z.string().describe('The id get_message and search_messages find it by.'),
     submittedAt: z.string().describe('When the API accepted it.'),
     test: z.boolean().describe('True when a test server took it: nobody receives it.'),
@@ -110,19 +111,21 @@ export const sendEmailTool = {
     class: 'write',
     reach: 'server',
     operations: ['POST /v1/email', 'GET /v1/messages/{id}'],
+    screen: messageTimeline,
     register: (server, { connection, targets }) => {
         const modes = modesOf(targets);
         registerServerTool(server, targets, 'send_email', {
             title: 'Send one email',
             description: descriptionFor(modes),
             inputSchema: sendInput,
-            outputSchema,
+            outputSchema: sentOutput,
             annotations: {
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: false,
                 openWorldHint: modes.includes('live'),
             },
+            _meta: shownIn(messageTimeline),
         }, async (input, { sendora }) => {
             let accepted;
             try {

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This package's version, held equal to its package.json by a test. */
-export const MCP_VERSION = '1.4.1';
+export const MCP_VERSION = '1.5.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendora/mcp",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "The official MCP server for Sendora: its documentation and API for coding agents.",
   "license": "MIT",
   "type": "module",
@@ -29,22 +29,25 @@
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "2.1.2",
+    "@axe-core/playwright": "^4.13.0",
     "@modelcontextprotocol/client": "^2.1.0",
     "@modelcontextprotocol/conformance": "0.2.0-alpha.11",
     "@modelcontextprotocol/node": "^2.1.0",
+    "@playwright/test": "^1.63.0",
     "esbuild": "^0.28.2",
     "fast-check": "^4.10.2",
     "fflate": "^0.8.3",
     "typescript": "~7.0.2",
     "vitest": "^4.1.11",
+    "@sendora/api": "0.0.0",
     "@sendora/db": "0.0.0",
     "@sendora/domain": "0.0.0",
     "@sendora/observability": "0.0.0",
-    "@sendora/api": "0.0.0",
     "@sendora/site": "0.0.0"
   },
   "scripts": {
-    "build": "pnpm --filter @sendora/sdk build && node scripts/build-docs.ts && node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"fs.mkdirSync('dist/generated',{recursive:true});fs.copyFileSync('src/generated/docs.json','dist/generated/docs.json')\"",
-    "eval": "node eval/run.ts"
+    "build": "pnpm --filter @sendora/sdk build && node scripts/build-docs.ts && node scripts/build-screens.ts && node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"fs.mkdirSync('dist/generated',{recursive:true});fs.copyFileSync('src/generated/docs.json','dist/generated/docs.json');fs.cpSync('src/generated/screens','dist/generated/screens',{recursive:true})\"",
+    "eval": "node eval/run.ts",
+    "e2e": "playwright test"
   }
 }