@rsc-kit/mcp 0.14.0 → 0.15.0

package/guides/index.json

@@ -0,0 +1,162 @@
+[
+  {
+    "slug": "api-routes",
+    "title": "API routes",
+    "description": "Web-standard endpoints, colocated with your pages, with no configuration."
+  },
+  {
+    "slug": "authorization",
+    "title": "Authorization",
+    "description": "Protecting pages, server actions and API routes."
+  },
+  {
+    "slug": "caching",
+    "title": "Asking once per request",
+    "description": "cache() — one lookup, however many places need it."
+  },
+  {
+    "slug": "connection",
+    "title": "Rendering per request",
+    "description": "Marking work that belongs to the visitor, not to the build."
+  },
+  {
+    "slug": "edge-caching",
+    "title": "Serving shells from a CDN",
+    "description": "Putting build-time shells on the edge, and what rsc-kit does not do."
+  },
+  {
+    "slug": "errors",
+    "title": "Errors and 404s",
+    "description": "What a visitor sees when a page throws, or asks for a url nothing answers."
+  },
+  {
+    "slug": "file-uploads",
+    "title": "File uploads",
+    "description": "Sending files through a server action without encoding them."
+  },
+  {
+    "slug": "fonts",
+    "title": "Fonts",
+    "description": "Self-hosted fonts from npm, and what next/font was doing for you."
+  },
+  {
+    "slug": "forms",
+    "title": "Forms",
+    "description": "Progressive forms, pending state and validation errors."
+  },
+  {
+    "slug": "images",
+    "title": "Images",
+    "description": "Responsive images with no optimizer to run — unpic for a CDN, imagetools for files in the repo."
+  },
+  {
+    "slug": "mcp",
+    "title": "Working with an AI agent",
+    "description": "An MCP server that answers from your actual build, and the AGENTS.md written into every project."
+  },
+  {
+    "slug": "metadata",
+    "title": "Page metadata",
+    "description": "Titles, descriptions and Open Graph tags, exported from the page."
+  },
+  {
+    "slug": "navigation",
+    "title": "Navigation",
+    "description": "What happens when someone clicks a link, and why state survives it."
+  },
+  {
+    "slug": "no-javascript",
+    "title": "A page with no JavaScript",
+    "description": "Rendering a route to HTML and stopping there."
+  },
+  {
+    "slug": "offline",
+    "title": "Offline",
+    "description": "Knowing when the server cannot be reached, and carrying on without it."
+  },
+  {
+    "slug": "ppr",
+    "title": "Partial prerendering",
+    "description": "Storing what every visitor sees the same, and rendering the rest per request."
+  },
+  {
+    "slug": "pwa",
+    "title": "Progressive web apps",
+    "description": "Making the app installable, and adding push notifications and background sync."
+  },
+  {
+    "slug": "queries",
+    "title": "Queries",
+    "description": "Reading from the server over GET, and letting TanStack Query or SWR own everything above it."
+  },
+  {
+    "slug": "react-compiler",
+    "title": "React Compiler",
+    "description": "Enabling the compiler in the build."
+  },
+  {
+    "slug": "redirects",
+    "title": "Redirects",
+    "description": "Leaving a page from inside the render, and what that costs."
+  },
+  {
+    "slug": "response-headers",
+    "title": "Headers and cookies",
+    "description": "Setting response headers and cookies during a render."
+  },
+  {
+    "slug": "route-interception",
+    "title": "Route interception",
+    "description": "Opening a route as a modal over the page you were on."
+  },
+  {
+    "slug": "routing",
+    "title": "Routing",
+    "description": "File-based routes, layouts, loading states and parallel slots."
+  },
+  {
+    "slug": "sections",
+    "title": "Sections",
+    "description": "Refreshing one region of a page without re-rendering the rest."
+  },
+  {
+    "slug": "server-actions",
+    "title": "Server actions",
+    "description": "Calling the server from a client component, as an ordinary function."
+  },
+  {
+    "slug": "static-generation",
+    "title": "Static generation",
+    "description": "Rendering pages ahead of time, and exporting a site of files."
+  },
+  {
+    "slug": "testing",
+    "title": "Testing",
+    "description": "Three tiers, and the one thing that still needs a browser."
+  },
+  {
+    "slug": "third-party-scripts",
+    "title": "Third-party scripts",
+    "description": "Analytics, tag managers and widgets — and why there is no Script component."
+  },
+  {
+    "slug": "typed-routes",
+    "title": "Typed routes",
+    "description": "Links that fail the typecheck instead of the browser."
+  },
+  {
+    "slug": "url-validation",
+    "title": "Typed URLs",
+    "description": "Checking and typing params, query strings and request bodies with a schema you already write."
+  },
+  {
+    "slug": "validation",
+    "title": "Validation",
+    "description": "Surfacing server-side validation errors in a form."
+  },
+  {
+    "slug": "view-transitions",
+    "title": "View transitions",
+    "description": "What React's ViewTransition animates in an app built with this, and what it does not."
+  }
+]

package/guides/mcp.md

@@ -0,0 +1,113 @@
+# Working with an AI agent
+
+> An MCP server that answers from your actual build, and the AGENTS.md written into every project.
+
+Two things ship for this, and they do different jobs.
+
+`AGENTS.md` is written into your project by the scaffold. It is short on
+purpose — it sits in an agent's context on every turn, so it states the rules
+and nothing more.
+
+The **MCP server** is for everything that does not fit in that budget: what your
+build actually did, and the long-form answer to "how do I do X here".
+
+## Connecting it
+
+The scaffold already did. Every project gets a `.mcp.json` at its root:
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "rsc-kit": { "command": "npx", "args": ["-y", "@rsc-kit/mcp"] }
+  }
+}
+```
+
+Claude Code reads that as project-scoped configuration and asks you to approve
+it the first time it starts the server. Nothing is installed until then, and
+nothing about your build or dev server changes — it is a file an agent reads.
+Commit it; it is the same for everyone on the project.
+
+For a project that predates the file, `create-rsc-kit init` writes it (and
+leaves one that is already there alone), or add it by hand:
+
+```sh
+claude mcp add rsc-kit -- npx -y @rsc-kit/mcp
+```
+
+Any other MCP client takes the same entry — a stdio server, command `npx`,
+arguments `-y @rsc-kit/mcp` — in its own file: `.cursor/mcp.json` under
+`mcpServers`, `.vscode/mcp.json` under `servers`.
+
+## What it answers about your app
+
+Every build writes `build-report.json` — the same rows it printed, plus every
+server action and whether a client built it. These read
+it, so nothing runs a build or imports your code:
+
+| tool | answers |
+| --- | --- |
+| `list_routes` | every route, what happened to it, what it ships |
+| `explain_route` | why one url is stored or rendered per request |
+| `what_is_dynamic` | the routes that are not stored, with reasons |
+| `heaviest_routes` | what costs the browser most |
+
+The reason a page is dynamic is **recorded, not guessed**:
+
+```
+/locale — a stored shell, with the rest rendered per request (from the last build, 5 minutes ago)
+Rendered by app/locale/page.
+Ships 85 kB of javascript, gzipped.
+
+Why it is not stored whole: dynamic — called cookies(), headers()
+```
+
+That matters more than it sounds. Asked to "make this page faster", an agent
+without this guesses at a cause and edits something. With it, the call that did
+it is on the screen.
+
+## What it answers about the framework
+
+| tool | answers |
+| --- | --- |
+| `list_topics` | every topic it can explain |
+| `how_to` | the short answer: forms, prefetch, validation, the action client, data with TanStack Query or SWR, Suspense, offline, pwa, no-javascript, api routes, authorization, why a page is dynamic |
+| `list_guides` | every guide on this site, one line each |
+| `read_guide` | the full text of one, exactly as published here — bundled with the server, so it matches the version installed |
+| `search_guides` | every line in the guides mentioning a word, with the guide it is in |
+
+`how_to` is the opinionated summary an agent should read first; `read_guide`
+is for when the summary is not enough. Both come from the same source, and the
+guides are copied in at build time, so what an agent reads is what this site
+says for the version it has.
+
+These exist because the patterns here differ from Next and plain React **in
+ways that compile either way** — a check written in the component instead of the
+action, a hand-parsed query string, `"use server"` at the top of a page. An
+agent that has not been told writes those confidently.
+
+## Two things worth knowing
+
+**Every answer says how old it is.** It reports the last build, and your files
+may have changed since — so `(from the last build, 5 minutes ago)` is on every
+response. With no build at all it says to run one, rather than reporting that
+there are no routes.
+
+**It is read-only.** Nothing here edits, builds or deploys. Your agent already
+has a shell for those, and a server that can change a project is one that can
+change it while answering a question about it.
+
+## The docs are markdown too
+
+Every page on this site is also a markdown file at the same url with
+`index.md` added — `/guides/forms/index.md` — and
+[`/llms.txt`](/llms.txt) is an index of all of them, with
+[`/llms-full.txt`](/llms-full.txt) as one document. An agent without the MCP
+server, or one asked about a version other than the one installed, reads
+those. `read_guide` is the same text, offline, at the installed version.
+
+## Without an agent
+
+`build-report.json` is an ordinary file. A CI step can assert on it — that
+nothing stopped being prerendered, that no route crossed a size budget — which
+is the check most likely to catch a regression nobody would otherwise see.

package/guides/metadata.md

@@ -0,0 +1,289 @@
+# Page metadata
+
+> Titles, descriptions and Open Graph tags, exported from the page.
+
+Titles and meta tags are exported by the page that needs them. There is no
+document template to edit and nothing to register — React hoists the resulting
+elements into `<head>`, so they stream with the page rather than waiting for
+it.
+
+## Static metadata
+
+```tsx title="src/app/about/page.tsx"
+export const metadata: Metadata = {
+  title: 'About us',
+  description: 'Learn more about our team.',
+  keywords: ['about', 'team', 'company'],
+  openGraph: {
+    title: 'About us',
+    description: 'Learn more about our team.',
+  },
+};
+
+export default function AboutPage() {
+  return <h1>About us</h1>;
+}
+```
+
+`Metadata` is imported from the package:
+
+```tsx
+import type { Metadata } from '@rsc-kit/core/metadata';
+```
+
+It used to be ambient, written into your project by the build. An import
+resolves as soon as dependencies are installed, where a generated file does not
+exist until something has been built once — so a freshly cloned project no
+longer reports an error on every page it has not built yet.
+
+:::tip[Custom meta tags go under `other`]
+```tsx
+export const metadata: Metadata = {
+  title: 'Pricing',
+  other: { 'fb:app_id': '1234', 'theme-color': '#111' },
+};
+```
+
+The named keys are a closed set on purpose. When any key was legal, a typo like
+`titel` was accepted in silence — and your editor offered no completions at
+all.
+:::
+
+## Metadata from data
+
+When the values depend on what the page loaded, export `generateMetadata`. It
+receives the route params:
+
+```tsx title="src/app/posts/[slug]/page.tsx"
+import { findPost } from '../../../data';
+
+export const generateMetadata: GenerateMetadata<{ slug: string }> = async ({ params }) => {
+  const { slug } = await params;
+  const post = await findPost(slug);
+
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: { title: post.title, description: post.excerpt, images: post.cover },
+  };
+};
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await findPost(slug);
+
+  return <h1>{post.title}</h1>;
+}
+```
+
+It receives the same `params` and `searchParams` a page does, so there is one
+shape to learn rather than two. Unlike a page's, these always resolve — a
+`<title>` has no fallback, so there is nothing to suspend into.
+
+Metadata always resolves against the **full** layout chain, even when the
+render is partial. A navigation that replaces one segment still produces the
+same `<title>` a full load would, because the template on the outer layout is
+consulted either way.
+
+## Title templates
+
+A layout can define the shape every title beneath it takes. `%s` stands in for
+the page's own title:
+
+```tsx title="src/app/layout.tsx"
+export const metadata: Metadata = {
+  title: {
+    template: '%s | Acme',
+    default: 'Acme',
+  },
+  description: 'The Acme dashboard.',
+};
+```
+
+```tsx title="src/app/settings/page.tsx"
+export const metadata: Metadata = { title: 'Settings' };
+
+// <title>Settings | Acme</title>
+```
+
+The nearest layout with a template wins, so a nested layout can override the
+one above it. A page that exports no title gets the `default`.
+
+## Supported keys
+
+| Key | Becomes |
+| --- | --- |
+| `title` | `<title>` — a string on a page, a template on a layout |
+| `description` | `<meta name="description">` |
+| `keywords` | `<meta name="keywords">`, joined with commas if you pass an array |
+| `author` | `<meta name="author">` |
+| `robots` | `<meta name="robots">` |
+| `metadataBase` | nothing itself — it is what makes every relative url below absolute |
+| `openGraph` | `<meta property="og:…">`, one per field; each image brings its size and alt |
+| `twitter` | `<meta name="twitter:…">` |
+| `icons` | `<link rel="icon">`, `apple-touch-icon` and so on |
+| `other` | `<meta name="…">`, or `property=` for an `og:`/`fb:`/`article:` key |
+| anything else | `<meta name="…">` |
+
+`keywords` takes either form — `'react, rsc'` and `['react', 'rsc']` produce
+the same tag.
+
+The flat spellings — `'og:title'`, `'twitter:card'` — still work and render
+correctly, but the structured objects are the ones to write: they are typed,
+they take an image object with a width and height, and they are what a Next
+app already has.
+
+## The share card
+
+```tsx title="src/app/layout.tsx"
+export const metadata: Metadata = {
+  metadataBase: new URL('https://remorva.com'),
+  openGraph: {
+    siteName: 'Remorva',
+    type: 'website',
+  },
+  twitter: {
+    card: 'summary_large_image',
+    site: '@remorva',
+  },
+};
+```
+
+```tsx title="src/app/posts/[slug]/page.tsx"
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const post = await findPost((await params).slug);
+
+  return {
+    title: post.title,
+    openGraph: {
+      title: post.title,
+      description: post.excerpt,
+      url: `/posts/${post.slug}`,
+      images: [{ url: post.cover, width: 1200, height: 630, alt: post.title }],
+    },
+  };
+}
+```
+
+Layouts merge outward-in, so `metadataBase`, `siteName` and the card type are
+set once and every page gets them.
+
+:::caution[`metadataBase` is not optional in production]
+A share-card scraper needs an **absolute** image url. Facebook, Slack and
+LinkedIn all refuse a relative one, silently — the link unfurls with no image
+and nothing says why.
+
+Set `metadataBase` on the root layout and every relative `url`, image and icon
+below it is made absolute. Without it, an `opengraph-image.png` in `app/` goes
+out as `/_app/opengraph-image.png`, which works in a browser and nowhere else.
+
+It is the same name as Next's, so a port carries it across unchanged.
+:::
+
+`og:` tags render with `property=` and `twitter:` with `name=`, because that is
+what each scraper reads. It is worth stating because it is easy to get
+backwards, and a tag with the wrong attribute is not an error — it is a card
+that never shows.
+
+## Icons
+
+A string, a list, or a categorised object:
+
+```tsx
+// One favicon
+export const metadata: Metadata = { icons: '/favicon.ico' };
+
+// Several, with attributes
+export const metadata: Metadata = {
+  icons: [
+    { url: '/favicon.ico', sizes: '32x32' },
+    { url: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+  ],
+};
+
+// By role
+export const metadata: Metadata = {
+  icons: {
+    icon: '/favicon.ico',
+    apple: '/apple-touch-icon.png',
+    other: { rel: 'mask-icon', url: '/safari-pinned-tab.svg', color: '#5bbad5' },
+  },
+};
+```
+
+Each descriptor takes `url`, `type`, `sizes`, `color`, `rel`, `media` and
+`fetchPriority`.
+
+## How it reaches the document
+
+```text
+Build     the plugin finds the metadata exports and generates a resolver
+Render    the resolver runs alongside the page, against the full layout chain
+Load      React hoists <title> and <meta> into <head> as they are emitted
+Navigate  the resolved metadata rides on the X-RSC-Meta header, and the
+          client updates document.title and the tags in place
+```
+
+The last line is why a title is correct after an SPA navigation without the
+page having been re-rendered from the root.
+
+## Icons and share images
+
+Put them in `src/app/` and the build finds them. There is nothing to register
+and no layout to edit:
+
+| file | what it becomes |
+| --- | --- |
+| `favicon.ico` | served at `/favicon.ico` |
+| `icon.png`, `icon-192.png`, `icon-512.png` | `<link rel="icon">`, and the [manifest](/guides/offline/)'s icons |
+| `apple-icon.png` | `<link rel="apple-touch-icon">` |
+| `opengraph-image.png` | `<meta property="og:image">` |
+| `twitter-image.png` | `<meta name="twitter:image">`, with the large-card type |
+
+The names are Next's. There is nothing to gain from inventing different ones —
+an app moving between the two should not have to rename its favicon.
+
+**Sizes are read from the filename**, so `icon-192.png` needs no entry anywhere
+saying it is 192 pixels. Which is why a manifest usually lists no icons at all:
+
+```ts title="src/app/manifest.ts"
+export default {
+  name: 'Orders',
+  themeColor: '#0b0b0c',
+  // icons omitted — the build uses the icon-*.png beside this file
+} satisfies WebManifest
+```
+
+Listing them as well would be the same set written twice, and the copy that
+goes stale is the one nobody looks at.
+
+### Why `app/` and not `public/`
+
+`public/` means "serve this file unchanged". These are *read* as well as
+served: an icon's filename decides what goes in the manifest, and its presence
+decides what goes in the head. A file whose name the build interprets belongs
+with the other files whose names the build interprets.
+
+They are copied into the build output under `/_app/`, so they never collide
+with something you put in `public/` yourself. The favicon is the exception —
+it is served at `/favicon.ico`, because browsers ask for that url whatever the
+markup says.
+
+:::note[Set `metadataBase`]
+The image is emitted as `/_app/opengraph-image.png`, which a scraper will not
+fetch. With `metadataBase` on the root layout it goes out absolute — see [the
+share card](#the-share-card) above.
+:::
+
+### Not `opengraph-image.tsx`
+
+Next also accepts a *component* by that name and renders it to a PNG at build
+time. This package does not, on purpose. Rendering an image means bundling a
+layout engine and a rasteriser — a couple of megabytes of dependencies, and
+seconds added to every build for every image — for a picture that changes
+when the design does, which is to say rarely.
+
+Make the image once with whatever you like, and commit the file. If a page
+needs a *different* image per record — a card for each post — that is an
+[api route](/guides/api-routes/) that returns one, cached, and the
+`openGraph.images` url points at it. Neither touches the build.

package/guides/navigation.md

@@ -0,0 +1,84 @@
+# Navigation
+
+> What happens when someone clicks a link, and why state survives it.
+
+`Link` does not reload the page. It asks the server for the part of the tree
+that actually changed, and swaps it in.
+
+```tsx
+import Link from '@rsc-kit/core/Link'
+
+<Link href="/about">About</Link>
+```
+
+## What a navigation actually sends
+
+Going from `/posts/one` to `/posts/two`, the root layout and the posts layout
+are already mounted and identical. The client says which layouts it holds, the
+server compares that with the new route's chain, and answers with the deepest
+piece that differs — the page alone.
+
+You get this for free. There is nothing to configure and no `loading` prop to
+thread.
+
+Two things follow from it, and they are the reason it works this way:
+
+**State above the swap survives.** A sidebar's scroll position, an open menu, a
+half-typed form in a layout — none of it is touched, because none of it was
+re-rendered.
+
+**A page you return to is still there.** Recently visited pages are kept mounted
+and hidden rather than thrown away, so going back restores a half-filled form
+exactly as you left it. Only a handful are kept, ordered by last visit.
+
+## Programmatic navigation
+
+```tsx
+'use client'
+
+import { visit, prefetch } from '@rsc-kit/core/router'
+
+<button onClick={() => visit('/checkout')}>Checkout</button>
+```
+
+Links prefetch on hover already. `prefetch` is for when you know where someone
+is going before they hover:
+
+```tsx
+useEffect(() => { prefetch('/step-2') }, [])
+```
+
+## Showing progress
+
+```tsx
+'use client'
+
+import { useLinkStatus } from '@rsc-kit/core/useLinkStatus'
+
+function Spinner() {
+  const { pending } = useLinkStatus()
+
+  return pending ? <span>Loading…</span> : null
+}
+```
+
+A `loading.tsx` beside a page is shown while that page's data resolves:
+
+```tsx title="src/app/posts/loading.tsx"
+export default function Loading() {
+  return <p>Loading posts…</p>
+}
+```
+
+## Refreshing the current page
+
+```tsx
+'use client'
+
+import { refresh } from '@rsc-kit/core/router'
+
+<button onClick={() => refresh()}>Reload</button>
+```
+
+Scroll positions are restored afterwards — the window's and any element with
+its own overflow, such as a sidebar.

package/guides/no-javascript.md

@@ -0,0 +1,39 @@
+# A page with no JavaScript
+
+> Rendering a route to HTML and stopping there.
+
+Some pages have nothing to hydrate. A marketing page, a changelog, an article.
+For those, shipping React is paying about 70 kB gzipped for nothing.
+
+```tsx title="src/app/about/page.tsx"
+export const clientJs = false
+
+export default function AboutPage() {
+  return <h1>About</h1>
+}
+```
+
+That route now renders to HTML and stops. No bootstrap script, so no React, no
+Flight client, no router.
+
+## What stops working
+
+Links on that page are ordinary links — a full page load rather than a segment
+swap. Anything interactive stops working, which is why the build refuses the
+combination rather than shipping it:
+
+```
+app/about/page.tsx declares clientJs = false but renders client components:
+  src/components/Counter.tsx
+```
+
+That is a build failure, not a warning. A client component with no runtime is
+inert markup — a button that does nothing — and it is usually inherited from a
+shared layout rather than written on the page, so the message names the
+components responsible.
+
+## It cannot be a PPR route
+
+With no client runtime there is nothing to fill a Suspense hole after the
+shell arrives. A `clientJs = false` route should be fully static: fetch what it
+needs at build time and freeze the whole page.