next-webmcp

next-webmcp is an experimental helper library for building WebMCP-powered Next.js App Router applications. It has not been proven in production environments yet, and the API is expected to change while the patterns mature. It wraps @mcp-b/react-webmcp with server-safe provider wiring, typed Server Action integration, navigation and search helpers, and an optional route metadata generator.

The package is designed around the awkward parts of WebMCP in App Router apps: tools that span server actions, client hooks, provider setup, and shared validation contracts. It provides a WebMCPProvider, defineTool and executeTool server helpers, App Router hooks such as useServerTool, useNavigationTool, and useSearchParamsTool, plus an experimental withWebMCP plugin for route generation.

Why It Was Made

WebMCP and the Next.js App Router can become awkward when a tool needs client registration, server execution, validation, and provider setup at the same time. next-webmcp was made to collect those patterns into a small library with one consistent integration path.

Features

• Server-safe WebMCPProvider for App Router layouts.
• Typed server tool definitions with defineTool.
• Validated server execution with executeTool.
• useServerTool, useNavigationTool, and useSearchParamsTool hooks.
• Optional withWebMCP route metadata generator.
• Duplicate provider guardrails for embedded agent setup.

Tech Stack

• TypeScript package built with tsup.
• Next.js App Router integration.
• React hooks over @mcp-b/react-webmcp.
• Zod-compatible schema validation for tool contracts.
• Vitest coverage for provider, hook, server tool, and route-generator behavior.