React MCP SPA

하나의 HTML 블롭으로 번들링되어 MCP Apps 서버에 의해 제공되는 최소한의 React 단일 페이지 앱입니다. 이 SPA는 URL 경로 라우팅을 사용하지 않으며, MCP 호스트 컨텍스트에서 현재 도구 이름을 읽어 렌더링할 페이지를 선택합니다.

레이아웃

• packages/ui/ — React + Vite SPA, vite-plugin-singlefile을 통해 단일 파일 HTML 블롭으로 빌드됨.

• packages/mcp/ — @modelcontextprotocol/ext-apps/server를 사용하는 MCP 서버. 모두 동일한 ui:// 리소스를 가리키는 도구(show-home, show-counter, show-profile)를 등록함.

• packages/playground/ — hostContext 및 toolResult에 대한 JSON 입력을 포함하는 모의 채팅 UI 내에서 SPA를 렌더링하는 개발 전용 하네스. MCP 호스트 없이도 페이지를 테스트할 수 있음.

설치

Node.js ≥ 20 및 pnpm ≥ 9이 필요합니다.

pnpm install

UI 격리 개발

pnpm run dev:ui

출력된 URL(예: http://localhost:5173)을 엽니다. SPA는 MCP 호스트가 없음을 감지하고 각 페이지를 미리 볼 수 있도록 경로 선택기를 표시합니다.

Playground — MCP 없이 렌더링 테스트

pnpm run dev:playground

http://localhost:5174에서 열립니다. Playground는 SPA의 실제 경로 렌더러(packages/ui/src/Router.tsx의 RouteRenderer)를 재사용하고 이를 모의 채팅 UI로 감쌉니다. 헤더에는 두 개의 JSON 텍스트 영역이 있습니다. 하나는 hostContext(toolInfo.tool.name을 통해 렌더링할 페이지를 결정)용이고, 다른 하나는 페이지에 전달되는 toolResult용입니다. 사전 설정 버튼은 등록된 각 도구에 대해 미리 만들어진 컨텍스트+결과 쌍을 로드하며, 텍스트 영역을 수정하면 어시스턴트의 도구 출력 버블이 실시간으로 다시 렌더링됩니다.

MCP 서버 빌드 및 실행

pnpm run build       # builds packages/ui → dist/index.html, then packages/mcp
pnpm run serve:mcp   # starts Streamable HTTP server on http://localhost:3001/mcp

stdio 전송의 경우:

pnpm --filter @react-mcp-spa/mcp run serve:stdio

cloudflared로 서버 노출

일부 MCP 클라이언트(호스팅된 클라이언트 포함)는 localhost에 도달할 수 없습니다. cloudflared를 사용하여 공개 HTTPS URL을 할당하는 빠른 터널을 엽니다.

OS 패키지 관리자를 통해 cloudflared를 설치하세요:

# macOS (Homebrew)
brew install cloudflared

# Linux (Debian/Ubuntu)
# See https://pkg.cloudflare.com/ for the apt repo, or grab the .deb from
# https://github.com/cloudflare/cloudflared/releases

# Windows (winget)
winget install --id Cloudflare.cloudflared

로컬에서 서버를 시작하세요:

pnpm run serve:mcp

다른 터미널에서 다음을 실행하세요:

cloudflared tunnel --url http://localhost:3001
# or: pnpm run tunnel

cloudflared는 https://<random>.trycloudflare.com과 같은 URL을 출력합니다. /mcp를 추가하고 이를 MCP 서버 URL로 사용하세요:

https://<random>.trycloudflare.com/mcp

터널은 cloudflared를 종료할 때까지 유지됩니다. 안정적인 호스트 이름을 원하면 빠른 터널 대신 명명된 Cloudflare 터널을 구성하세요.

Claude Desktop 확장 프로그램(.mcpb)으로 패키징

이 저장소는 Claude Desktop용 설치 가능한 MCP 번들을 생성하는 패커를 제공합니다. 확장 프로그램은 stdio를 통해 서버를 실행하므로 터널이 필요하지 않습니다.

pnpm run pack:mcpb

이 명령은 두 패키지를 모두 빌드하고, 컴파일된 서버 + UI HTML + 프로덕션 node_modules를 build/mcpb-staging/ 아래에 스테이징하며, mcpb pack을 호출하여 다음을 생성합니다:

build/react-mcp-spa.mcpb

설치하려면 Finder/Explorer에서 .mcpb를 더블 클릭하거나(또는 Claude Desktop으로 드래그) 하세요. Claude는 매니페스트를 검증하고 서버를 등록합니다. 설치 후 세 가지 도구(show-home, show-counter, show-profile)를 사용할 수 있으며 각 도구는 해당 페이지를 인라인 React UI로 렌더링합니다.

번들 매니페스트는 mcpb/manifest.json에 있습니다. 새 확장 프로그램을 릴리스할 때 여기(및 packages/mcp/package.json)에서 version을 업데이트하세요.

라우팅 작동 방식

SPA는 window.location을 읽지 않습니다. 대신 packages/ui/src/App.tsx는 @modelcontextprotocol/ext-apps/react의 useApp()을 사용하며 다음을 수행합니다:

1. app.getHostContext().toolInfo.tool.name을 읽어 호스트가 호출한 도구(즉, "경로")를 파악합니다.

2. app.ontoolresult를 구독하여 서버로부터 CallToolResult를 수신하고 이를 데이터로 페이지에 전달합니다.

3. app.onhostcontextchanged를 감시하여 테마 / 안전 영역 / 로케일 업데이트가 올바르게 다시 렌더링되도록 합니다.

새 페이지를 추가하는 것은 두 단계로 이루어집니다:

1. packages/mcp/src/server.ts에 _meta.ui.resourceUri가 공유 ui://react-mcp-spa/app.html 리소스를 가리키도록 도구를 등록합니다.

2. packages/ui/src/App.tsx 내의 renderRoute()에 도구 이름에 대한 case를 추가합니다.