MCP Hello World App

A minimal MCP App boilerplate: a single Node/TypeScript MCP server that exposes one tool (say_hello) and serves a tiny Angular UI as an MCP App resource.

It mirrors the architecture of the parent invoice-preview-mcp-app project, stripped down to a "Hello World".

Architecture

MCP Host (e.g. Cursor)
  │  calls tool  say_hello
  ▼
Express server (:8080)
  ├─ POST/GET/DELETE /mcp   → MCP Streamable HTTP transport
  ├─ MCP resource           → ui://hello-world/app   (inlined Angular HTML)
  ├─ GET /ui/*              → HTTP fallback for assets
  └─ GET /healthz
        ▲
        │ build pipeline
  ng build → scripts/inline-bundle.mjs  (CSS + JS inlined into one HTML)

When the agent calls say_hello, the tool result carries _meta.ui.resourceUri = "ui://hello-world/app", which tells the host to open the Angular UI in an iframe. Inside the iframe the UI calls say_hello again through the MCP bridge (postMessage, with an HTTP fallback to /mcp).

Project layout

├── package.json              # npm workspaces: server + ui
├── tsconfig.base.json
├── scripts/inline-bundle.mjs # inlines the Angular build for MCP iframes
├── .cursor/mcp.json          # points Cursor at http://127.0.0.1:8080/mcp
├── server/                   # MCP + Express server (TypeScript)
│   └── src/
│       ├── index.ts                      # entry point
│       ├── core/
│       │   ├── config/server-env.ts      # env parsing
│       │   ├── http/                     # Express app + CORS
│       │   ├── infrastructure/           # base-url / CSP helpers
│       │   └── mcp/                       # server factory, transport, tool registry
│       ├── tools/                        # one folder per MCP tool
│       │   └── say-hello/                 #   register-say-hello.ts + schemas
│       └── ui/                            # MCP App resource + HTTP fallback
└── ui/                       # Angular Hello World UI

Adding a new tool

1. Create server/src/tools/<your-tool>/register-<your-tool>.ts (plus a *.schemas.ts if it takes input).
2. Add its registrar to the array in server/src/core/mcp/tool-registry.ts.

Getting started

npm install
npm run build      # builds the server (tsc) and the UI (ng build + inline)
npm start          # node server/dist/index.js  → http://localhost:8080

Then add .cursor/mcp.json to your Cursor MCP config (or copy the hello-world-local entry), and ask the agent to run the say_hello tool.

Key conventions

Convention	Why
MIME text/html;profile=mcp-app	Required by the MCP Apps spec
outputHashing: "none" (Angular)	Stable asset filenames for resource serving
baseHref: "./"	Relative paths inside the iframe
inline-bundle script	MCP iframes often block external script fetches
_meta.ui.resourceUri on the tool	Tells the host which UI to open
CORS on /mcp	The iframe has a null/opaque origin
<meta name="mcp-server-url"> injection	Enables the HTTP tool-call fallback