Skip to content

feat: add server helpers, make connect() to default to parent post transport #165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ochafik merged 5 commits into from
Dec 16, 2025
Merged

feat: add server helpers, make connect() to default to parent post transport #165

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f2bbb77
feat: add server helpers and optional connect() transport
ochafik Dec 16, 2025
c5fc927
Update src/server/index.ts
ochafik Dec 16, 2025
5fb7426
fix: refine server helper types
ochafik Dec 16, 2025
95054c0
refactor: simplify RESOURCE_URI_META_KEY re-export
ochafik Dec 16, 2025
82322a7
refactor: consolidate export statements
ochafik Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions examples/basic-server-react/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
import fs from "node:fs/promises";
import path from "node:path";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand All @@ -22,7 +22,7 @@ function createServer(): McpServer {
// MCP Apps require two-part registration: a tool (what the LLM calls) and a
// resource (the UI it renders). The `_meta` field on the tool links to the
// resource URI, telling hosts which UI to display when the tool executes.
server.registerTool(
registerAppTool(server,
"get-time",
{
title: "Get Time",
Expand All @@ -38,7 +38,7 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(server,
RESOURCE_URI,
RESOURCE_URI,
{ mimeType: RESOURCE_MIME_TYPE },
Expand Down
2 changes: 1 addition & 1 deletion examples/basic-server-vanillajs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,5 +52,5 @@ button.addEventListener("click", () => {
});

// Connect to host
app.connect(new PostMessageTransport(window.parent));
app.connect();
```
6 changes: 3 additions & 3 deletions examples/basic-server-vanillajs/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
import fs from "node:fs/promises";
import path from "node:path";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand All @@ -22,7 +22,7 @@ function createServer(): McpServer {
// MCP Apps require two-part registration: a tool (what the LLM calls) and a
// resource (the UI it renders). The `_meta` field on the tool links to the
// resource URI, telling hosts which UI to display when the tool executes.
server.registerTool(
registerAppTool(server,
"get-time",
{
title: "Get Time",
Expand All @@ -38,7 +38,7 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(server,
RESOURCE_URI,
RESOURCE_URI,
{ mimeType: RESOURCE_MIME_TYPE },
Expand Down
4 changes: 2 additions & 2 deletions examples/basic-server-vanillajs/src/mcp-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* @file App that demonstrates a few features using MCP Apps SDK with vanilla JS.
*/
import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
import { App } from "@modelcontextprotocol/ext-apps";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import "./global.css";
import "./mcp-app.css";
Expand Down Expand Up @@ -98,4 +98,4 @@ openLinkBtn.addEventListener("click", async () => {


// Connect to host
app.connect(new PostMessageTransport(window.parent));
app.connect();
11 changes: 8 additions & 3 deletions examples/budget-allocator-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@ import type {
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand Down Expand Up @@ -235,7 +238,8 @@ function createServer(): McpServer {
version: "1.0.0",
});

server.registerTool(
registerAppTool(
server,
"get-budget-data",
{
title: "Get Budget Data",
Expand Down Expand Up @@ -277,7 +281,8 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{
Expand Down
4 changes: 2 additions & 2 deletions examples/budget-allocator-server/src/mcp-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* Budget Allocator App - Interactive budget allocation with real-time visualization
*/
import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
import { App } from "@modelcontextprotocol/ext-apps";
import { Chart, registerables } from "chart.js";
import "./global.css";
import "./mcp-app.css";
Expand Down Expand Up @@ -631,4 +631,4 @@ window
});

// Connect to host
app.connect(new PostMessageTransport(window.parent));
app.connect();
11 changes: 8 additions & 3 deletions examples/cohort-heatmap-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@ import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand Down Expand Up @@ -156,7 +159,8 @@ function createServer(): McpServer {
// Register tool and resource
const resourceUri = "ui://get-cohort-data/mcp-app.html";

server.registerTool(
registerAppTool(
server,
"get-cohort-data",
{
title: "Get Cohort Retention Data",
Expand All @@ -179,7 +183,8 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{ mimeType: RESOURCE_MIME_TYPE },
Expand Down
11 changes: 8 additions & 3 deletions examples/customer-segmentation-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@ import type {
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";
import {
generateCustomers,
Expand Down Expand Up @@ -65,7 +68,8 @@ function createServer(): McpServer {
{
const resourceUri = "ui://customer-segmentation/mcp-app.html";

server.registerTool(
registerAppTool(
server,
"get-customer-data",
{
title: "Get Customer Data",
Expand All @@ -83,7 +87,8 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{
Expand Down
2 changes: 1 addition & 1 deletion examples/customer-segmentation-server/src/mcp-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -463,7 +463,7 @@ app.onhostcontextchanged = (params) => {
}
};

app.connect(new PostMessageTransport(window.parent)).then(() => {
app.connect().then(() => {
// Apply initial host context after connection
const ctx = app.getHostContext();
if (ctx?.theme) {
Expand Down
2 changes: 1 addition & 1 deletion examples/qr-server/widget.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
}
};

await app.connect(new PostMessageTransport(window.parent));
await app.connect();
</script>
</body>
</html>
11 changes: 8 additions & 3 deletions examples/scenario-modeler-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@ import type {
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand Down Expand Up @@ -256,7 +259,8 @@ function createServer(): McpServer {
{
const resourceUri = "ui://scenario-modeler/mcp-app.html";

server.registerTool(
registerAppTool(
server,
"get-scenario-data",
{
title: "Get Scenario Data",
Expand Down Expand Up @@ -288,7 +292,8 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{ mimeType: RESOURCE_MIME_TYPE, description: "SaaS Scenario Modeler UI" },
Expand Down
11 changes: 8 additions & 3 deletions examples/system-monitor-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@ import os from "node:os";
import path from "node:path";
import si from "systeminformation";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

// Schemas - types are derived from these using z.infer
Expand Down Expand Up @@ -111,7 +114,8 @@ function createServer(): McpServer {
// Register the get-system-stats tool and its associated UI resource
const resourceUri = "ui://system-monitor/mcp-app.html";

server.registerTool(
registerAppTool(
server,
"get-system-stats",
{
title: "Get System Stats",
Expand Down Expand Up @@ -149,7 +153,8 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{ mimeType: RESOURCE_MIME_TYPE, description: "System Monitor UI" },
Expand Down
4 changes: 2 additions & 2 deletions examples/system-monitor-server/src/mcp-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* @file System Monitor App - displays real-time OS metrics with Chart.js
*/
import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
import { App } from "@modelcontextprotocol/ext-apps";
import { Chart, registerables } from "chart.js";
import "./global.css";
import "./mcp-app.css";
Expand Down Expand Up @@ -360,7 +360,7 @@ window
// Register handlers and connect
app.onerror = log.error;

app.connect(new PostMessageTransport(window.parent));
app.connect();

// Auto-start polling after a short delay
setTimeout(startPolling, 500);
14 changes: 10 additions & 4 deletions examples/threejs-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@ import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand Down Expand Up @@ -142,7 +145,8 @@ function createServer(): McpServer {
});

// Tool 1: show_threejs_scene
server.registerTool(
registerAppTool(
server,
"show_threejs_scene",
{
title: "Show Three.js Scene",
Expand Down Expand Up @@ -175,7 +179,8 @@ function createServer(): McpServer {
);

// Tool 2: learn_threejs
server.registerTool(
registerAppTool(
server,
"learn_threejs",
{
title: "Learn Three.js",
Expand All @@ -191,7 +196,8 @@ function createServer(): McpServer {
);

// Resource registration
server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{ mimeType: RESOURCE_MIME_TYPE, description: "Three.js Widget UI" },
Expand Down
11 changes: 8 additions & 3 deletions examples/wiki-explorer-server/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,10 @@ import * as cheerio from "cheerio";
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
import {
RESOURCE_MIME_TYPE,
RESOURCE_URI_META_KEY,
} from "@modelcontextprotocol/ext-apps/server";
import { startServer } from "../shared/server-utils.js";

const DIST_DIR = path.join(import.meta.dirname, "dist");
Expand Down Expand Up @@ -76,7 +79,8 @@ function createServer(): McpServer {
// Register the get-first-degree-links tool and its associated UI resource
const resourceUri = "ui://wiki-explorer/mcp-app.html";

server.registerTool(
registerAppTool(
server,
"get-first-degree-links",
{
title: "Get First-Degree Links",
Expand Down Expand Up @@ -124,7 +128,8 @@ function createServer(): McpServer {
},
);

server.registerResource(
registerAppResource(
server,
resourceUri,
resourceUri,
{ mimeType: RESOURCE_MIME_TYPE },
Expand Down
4 changes: 2 additions & 2 deletions examples/wiki-explorer-server/src/mcp-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* Wiki Explorer - Force-directed graph visualization of Wikipedia link networks
*/
import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
import { App } from "@modelcontextprotocol/ext-apps";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import {
forceCenter,
Expand Down Expand Up @@ -367,4 +367,4 @@ app.onerror = (err) => {
};

// Connect to host
app.connect(new PostMessageTransport(window.parent));
app.connect();
4 changes: 4 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@
"types": "./dist/src/app-bridge.d.ts",
"default": "./dist/src/app-bridge.js"
},
"./server": {
"types": "./dist/src/server/index.d.ts",
"default": "./dist/src/server/index.js"
},
"./schema.json": "./dist/src/generated/schema.json"
},
"files": [
Expand Down
Loading
Loading