feat: publish example servers to npm by jerome3o-anthropic · Pull Request #184 · modelcontextprotocol/ext-apps

jerome3o-anthropic · 2025-12-19T02:10:53Z

Summary

Make example MCP App servers publishable to npm under the @modelcontextprotocol scope. This enables users to run examples directly via npx without cloning the repo.

New packages (15):

@modelcontextprotocol/server-basic-preact
@modelcontextprotocol/server-basic-react
@modelcontextprotocol/server-basic-solid
@modelcontextprotocol/server-basic-svelte
@modelcontextprotocol/server-basic-vanillajs
@modelcontextprotocol/server-basic-vue
@modelcontextprotocol/server-budget-allocator
@modelcontextprotocol/server-cohort-heatmap
@modelcontextprotocol/server-customer-segmentation
@modelcontextprotocol/server-scenario-modeler
@modelcontextprotocol/server-sheet-music
@modelcontextprotocol/server-system-monitor
@modelcontextprotocol/server-threejs
@modelcontextprotocol/server-video-resource
@modelcontextprotocol/server-wiki-explorer

Changes:

Remove private: true from example package.json files
Add npm metadata (description, repository, license, files, prepublishOnly)
Update ext-apps dependency from relative path (../..) to versioned (^0.2.2)
Move server-utils.ts from src/ to package root for standalone use
Add stdio transport support (--stdio flag) to each server
Add publish-examples job to npm-publish.yml workflow (matrix-based, parallel)
Fix Windows ARM64 CI: add missing @rollup/rollup-win32-arm64-msvc to optionalDependencies

The examples will be published automatically when a GitHub release is created.

Test plan

All examples build successfully with npm run examples:build
CI passes on all platforms (Linux, macOS, Windows x64/ARM64)
Verify dry-run publish: npm publish --workspace examples/basic-server-react --dry-run
After release, verify packages appear on npm

🤖 Generated with Claude Code

Make example MCP App servers publishable to npm under the @modelcontextprotocol scope: - server-basic-react - server-basic-vanillajs - server-budget-allocator - server-cohort-heatmap - server-customer-segmentation - server-scenario-modeler - server-system-monitor - server-threejs - server-wiki-explorer Changes: - Remove `private: true` from example package.json files - Add proper npm metadata (description, repository, license, files) - Update ext-apps dependency from relative to ^0.2.2 - Copy server-utils.ts into each package for standalone use - Add publish-examples job to npm-publish.yml workflow The examples will be published automatically when a GitHub release is created, after the main SDK package is published. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

pkg-pr-new · 2025-12-19T02:11:43Z

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@184

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-react@184

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-vanillajs@184

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-budget-allocator@184

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-cohort-heatmap@184

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-customer-segmentation@184

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-scenario-modeler@184

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-system-monitor@184

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-threejs@184

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-wiki-explorer@184

commit: 061caa6

Resolve conflicts by: - Keep server-utils.ts next to server.ts (not in src/) - Simplify server-utils.ts to stateless HTTP only (no SSE) - Keep main() with explicit --stdio handling in server.ts - Add integration-server from main for E2E testing - Add npm start alias from main

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

ochafik

Thanks @jerome3o-anthropic !
Merged main and resolved conflicts. Key changes after #182:

Reverted the server-utils.ts location back to next to server.ts (not in src/)
Simplified server-utils.ts to stateless HTTP only (removed SSE legacy endpoints)
Kept main() with explicit --stdio handling in each server.ts

@jonathanhefner I reverted the inline stdio handling in server-utils.ts from #182 — IMO argv checking doesn't belong in a shared helper. Each server's main()
should own that decision, keeping server-utils.ts focused on just the HTTP transport setup.

Update golden screenshots for basic-react and basic-vanillajs after the tool output was simplified from JSON to plain text in #182. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

jonathanhefner · 2025-12-19T12:50:31Z

IMO argv checking doesn't belong in a shared helper. Each server's main() should own that decision, keeping server-utils.ts focused on just the HTTP transport setup.

In that case, why not make it boolean parameter? e.g.:

startServer(createServer, process.argv.includes("--stdio"));
// or
startServer(createServer, { stdio: process.argv.includes("--stdio") });

jonathanhefner · 2025-12-19T12:52:51Z

examples/basic-server-react/server.ts

-  // Two-part registration: tool + resource, tied together by the resource URI.
  const resourceUri = "ui://get-time/mcp-app.html";

-  // Register a tool with UI metadata. When the host calls this tool, it reads
-  // `_meta[RESOURCE_URI_META_KEY]` to know which resource to fetch and render
-  // as an interactive UI.
  registerAppTool(server,
    "get-time",
    {
      title: "Get Time",
-      description: "Returns the current server time as an ISO 8601 string.",
+      description: "Returns the current server time.",
      inputSchema: {},
      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
    },
    async (): Promise<CallToolResult> => {
-      const time = new Date().toISOString();
-      return { content: [{ type: "text", text: time }] };
+      return { content: [{ type: "text", text: new Date().toISOString() }] };
    },
  );

-  // Register the resource, which returns the bundled HTML/JavaScript for the UI.


Since these are educational examples, I would like to preserve these comments.

Hopefully restored

Did you mean restored in this PR or elsewhere? They still seem to be removed in the current diff for this PR.

jonathanhefner · 2025-12-19T12:54:05Z

examples/basic-server-vanillajs/server.ts

-  // Two-part registration: tool + resource, tied together by the resource URI.
-  const resourceUri = "ui://get-time/mcp-app.html";
-
-  // Register a tool with UI metadata. When the host calls this tool, it reads
-  // `_meta[RESOURCE_URI_META_KEY]` to know which resource to fetch and render
-  // as an interactive UI.
+  // 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.
  registerAppTool(server,
    "get-time",
    {
      title: "Get Time",
      description: "Returns the current server time as an ISO 8601 string.",
      inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
    },
    async (): Promise<CallToolResult> => {
      const time = new Date().toISOString();
-      return { content: [{ type: "text", text: time }] };
+      return {
+        content: [{ type: "text", text: JSON.stringify({ time }) }],
+      };
    },
  );

-  // Register the resource, which returns the bundled HTML/JavaScript for the UI.
  registerAppResource(server,
-    resourceUri,
-    resourceUri,
+    RESOURCE_URI,
+    RESOURCE_URI,
    { mimeType: RESOURCE_MIME_TYPE },
    async (): Promise<ReadResourceResult> => {
      const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");

      return {
        contents: [
-          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+          // Per the MCP App specification, "text/html;profile=mcp-app" signals
+          // to the Host that this resource is indeed for an MCP App UI.
+          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },


It looks like there was a bad rebase. This is reverting some of the changes I made in #182.

Hopefully restored

ochafik · 2025-12-19T16:11:45Z

In that case, why not make it boolean parameter? e.g.:
startServer(createServer, process.argv.includes("--stdio"));
// or
startServer(createServer, { stdio: process.argv.includes("--stdio") });

@jonathanhefner The signature would be awkard tbh... If we want to make it real clean, should probably look like:

export type ServerOptions = {
  name?: string;
} & (
  | { type: 'streamable-http', port: number, path?: string } // default path is /mcp
  | { type: 'stdio' }
);

But then it's more syntax to instantiate it...
I think the simplest would be to just name it startHttpServer({name, port}) and keep the stdio branch separate (there's little value in shoving it inside createServer - only saves 2 lines per examples and makes signature weird)

Wdyt?

jonathanhefner · 2025-12-19T17:54:24Z

If we want to make it real clean, should probably look like:
export type ServerOptions = {
  name?: string;
} & (
  | { type: 'streamable-http', port: number, path?: string } // default path is /mcp
  | { type: 'stdio' }
);
But then it's more syntax to instantiate it... I think the simplest would be to just name it startHttpServer({name, port}) and keep the stdio branch separate (there's little value in shoving it inside createServer - only saves 2 lines per examples and makes signature weird)

I'm not sure I see the value in providing name. When using concurrently (as in run-all.ts), then the example name (which is more exact than the server name) is already logged. When only running one server (without concurrently), the name is obvious.

I also think overriding the path isn't necessary for these examples. (Though I could see us supporting it if we wanted to offer this as a utility function in the SDK itself.)

Anyway, if you prefer to have separate functions, that's fine. I would suggest something like:

process.argv.includes("--stdio") ?
  startStdioServer(createServer) :
  startHttpServer(createServer);

You could add a port argument to startHttpServer(), but I feel like implicitly parsing from the PORT env var is fairly typical.

…publishing pattern - Move server-utils.ts from src/ to root level - Add npm publishing metadata (scoped name, repository, license, files) - Change ext-apps dependency from local to versioned ^0.2.2 - Update server.ts to handle stdio mode inline

Added 'nasa-earth' option - NASA ISS Earth observations (6.4MB). Source: archive.org/details/NASA-Ultra-High-Definition (public domain)

Add publishing metadata for: - @modelcontextprotocol/server-basic-preact - @modelcontextprotocol/server-basic-solid - @modelcontextprotocol/server-basic-svelte - @modelcontextprotocol/server-basic-vue Changes: - Move server-utils.ts from src/ to root - Add npm publishing metadata - Update ext-apps dep to versioned ^0.2.2 - Add stdio mode support in main()

This fixes the Windows ARM64 CI build failure caused by npm's optional dependency bug. The package.json was missing this platform-specific rollup binding.

Merge latest changes from main including: - Vue, Svelte, Preact, and Solid basic server examples (#141) - safeAreaInsets support (#202) - E2E test fixes (#206) - npm publishing for examples (#184) - ui.resourceUri optional (#210) - Method names as consts (#192) - toolInfo.id optional (#216) - PostMessageTransport security fixes (#207, #208) - Server-utils.ts refactoring

PR modelcontextprotocol#184 accidentally removed/reverted educational comments from `basic-server-react` and `basic-server-vanillajs` that were established in PR modelcontextprotocol#182. This restores consistency with the other basic-server examples (Vue, Svelte, Preact, Solid). Changes: - Add back the three-comment pattern explaining two-part registration - Restore full tool description ("as an ISO 8601 string") - Change vanillajs to return plain text instead of JSON (matching modelcontextprotocol#182) - Use local `resourceUri` variable instead of top-level constant Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jerome3o-anthropic added 2 commits December 19, 2025 15:32

feat: publish examples with pkg-pr-new for PR testing

a7ade06

feat: export createServer from example servers

c06ffb0

ochafik mentioned this pull request Dec 19, 2025

fix: ensure lib is built before examples:build #185

Merged

5 tasks

ochafik and others added 2 commits December 19, 2025 12:12

style: format integration-server/server.ts

771ff96

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

ochafik previously approved these changes Dec 19, 2025

View reviewed changes

ochafik dismissed their stale review via 68cddec December 19, 2025 12:28

jonathanhefner reviewed Dec 19, 2025

View reviewed changes

ochafik previously approved these changes Dec 19, 2025

View reviewed changes

ochafik added 2 commits January 8, 2026 16:58

merge

db515e8

merge

c5c9084

ochafik dismissed their stale review via c5c9084 January 8, 2026 17:00

ochafik added 9 commits January 8, 2026 17:05

update package-lock

752968b

fix: update package-lock.json for renamed server packages

8702898

feat: add NASA public domain video to video-resource-server

8e0dcc8

Added 'nasa-earth' option - NASA ISS Earth observations (6.4MB). Source: archive.org/details/NASA-Ultra-High-Definition (public domain)

fix: add default videoId for video-resource-server

06cfbd6

fix: use existing bunny-1mb as default video, remove nasa-earth

f477d93

Merge origin/main into jerome/publish-examples

6d9d3a0

Merge branch 'main' into jerome/publish-examples

011f6e3

ochafik previously approved these changes Jan 8, 2026

View reviewed changes

ochafik dismissed their stale review via a3267bb January 8, 2026 19:18

fix: add missing @rollup/rollup-win32-arm64-msvc to optionalDependencies

061caa6

This fixes the Windows ARM64 CI build failure caused by npm's optional dependency bug. The package.json was missing this platform-specific rollup binding.

ochafik force-pushed the jerome/publish-examples branch from a3267bb to 061caa6 Compare January 8, 2026 19:26

ochafik approved these changes Jan 8, 2026

View reviewed changes

ochafik merged commit c25d464 into main Jan 8, 2026
19 checks passed

ochafik mentioned this pull request Jan 9, 2026

chore: release 0.3.0 #204

Merged

jonathanhefner mentioned this pull request Jan 9, 2026

Restore educational comments in basic-server-* examples #228

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

feat: publish example servers to npm#184

feat: publish example servers to npm#184
ochafik merged 18 commits intomainfrom
jerome/publish-examples

jerome3o-anthropic commented Dec 19, 2025 •

edited by ochafik

Loading

Uh oh!

pkg-pr-new bot commented Dec 19, 2025 •

edited

Loading

Uh oh!

ochafik left a comment

Uh oh!

jonathanhefner commented Dec 19, 2025

Uh oh!

jonathanhefner Dec 19, 2025

Uh oh!

ochafik Dec 19, 2025

Uh oh!

jonathanhefner Dec 19, 2025

Uh oh!

jonathanhefner Dec 19, 2025

Uh oh!

ochafik Dec 19, 2025

Uh oh!

ochafik commented Dec 19, 2025

Uh oh!

jonathanhefner commented Dec 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

jerome3o-anthropic commented Dec 19, 2025 • edited by ochafik Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

pkg-pr-new bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

jonathanhefner commented Dec 19, 2025

Uh oh!

jonathanhefner Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

jonathanhefner Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

jonathanhefner Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik commented Dec 19, 2025

Uh oh!

jonathanhefner commented Dec 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jerome3o-anthropic commented Dec 19, 2025 •

edited by ochafik

Loading

pkg-pr-new bot commented Dec 19, 2025 •

edited

Loading