feat(mcp): answer with Markdown and compact typed data

docs/runbooks/agent-app-directories.md

@@ -16,7 +16,7 @@ Both portals scan the tools from the live server. Every tool must keep these pro
 - A description that says what the tool does. It must not tell the model how to behave, call other apps, or fetch instructions from a URL.
 - Output that holds only what the request needs. Do not add request IDs, trace IDs, or debug fields.
 
-`layers/mcp/shared/mcp-tools.ts` holds the tools. The toolkit answers 403 to a request whose `Origin` header is not in `mcp.security.allowedOrigins` in `nuxt.config.ts`.
+`layers/mcp/shared/mcp-tools.ts` holds the tools. `layers/mcp/shared/mcp-presenters.ts` shapes each answer: Markdown in `content` for the model, and a compact copy in `structuredContent` that the MCP SDK checks against the tool's `outputSchema`. The public API answers stay complete for the CLI and the SDK. The toolkit answers 403 to a request whose `Origin` header is not in `mcp.security.allowedOrigins` in `nuxt.config.ts`.
 
 ## Change a tool
 

layers/mcp/server/mcp/index.ts

@@ -26,6 +26,7 @@ export default defineMcpHandler({
       title: tool.title,
       description: tool.description,
       inputSchema: tool.inputSchema,
+      outputSchema: tool.outputSchema.shape,
       // Claude's directory reads the title from the annotations as well.
       annotations: { title: tool.title, ...tool.annotations },
       handler: (args, extra) => tool.run(deps, args, extra.signal),

test/fixtures/mcp/repository-vercel-agent-skills.json

@@ -0,0 +1 @@
+{"owner":"vercel-labs","repository":"agent-skills","description":"Vercel's official collection of agent skills","stars":32017,"pushedAt":"2026-08-28T13:36:31.000Z","repositoryUrl":"https://github.com/vercel-labs/agent-skills","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills","installCommand":"npx skilld add vercel-labs/agent-skills --all","skills":[{"owner":"vercel-labs","repository":"agent-skills","name":"react-view-transitions","displayName":"vercel-react-view-transitions","description":"Guide for implementing smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries.","stars":32017,"likes":0,"updatedAt":"2026-08-28T07:42:19.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/react-view-transitions","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/react-view-transitions/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/react-view-transitions","installCommand":"npx skilld install vercel-labs/agent-skills/react-view-transitions"},{"owner":"vercel-labs","repository":"agent-skills","name":"vercel-optimize","displayName":"vercel-optimize","description":"Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests.","stars":32017,"likes":0,"updatedAt":"2026-05-26T22:53:17.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/vercel-optimize","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/vercel-optimize","installCommand":"npx skilld install vercel-labs/agent-skills/vercel-optimize"},{"owner":"vercel-labs","repository":"agent-skills","name":"writing-guidelines","displayName":"writing-guidelines","description":"Review docs/prose for Writing Guidelines compliance. Use when asked to \"review my docs\", \"check writing style\", \"audit prose\", \"review docs voice and tone\", or \"check this page against the writing handbook\".","stars":32017,"likes":0,"updatedAt":"2026-05-26T00:50:54.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/writing-guidelines","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/writing-guidelines/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/writing-guidelines","installCommand":"npx skilld install vercel-labs/agent-skills/writing-guidelines"},{"owner":"vercel-labs","repository":"agent-skills","name":"vercel-cli-with-tokens","displayName":"vercel-cli-with-tokens","description":"Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. \"deploy to vercel\", \"set up vercel\", \"add environment variables to vercel\".","stars":32017,"likes":0,"updatedAt":"2026-04-16T23:35:50.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/vercel-cli-with-tokens","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-cli-with-tokens/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/vercel-cli-with-tokens","installCommand":"npx skilld install vercel-labs/agent-skills/vercel-cli-with-tokens"},{"owner":"vercel-labs","repository":"agent-skills","name":"react-best-practices","displayName":"vercel-react-best-practices","description":"React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.","stars":32017,"likes":0,"updatedAt":"2026-04-14T11:00:18.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/react-best-practices","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/react-best-practices","installCommand":"npx skilld install vercel-labs/agent-skills/react-best-practices"},{"owner":"vercel-labs","repository":"agent-skills","name":"deploy-to-vercel","displayName":"deploy-to-vercel","description":"Deploy applications and websites to Vercel. Use when the user requests deployment actions like \"deploy my app\", \"deploy and give me the link\", \"push this live\", or \"create a preview deployment\".","stars":32017,"likes":0,"updatedAt":"2026-03-06T14:32:23.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/deploy-to-vercel","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/deploy-to-vercel/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/deploy-to-vercel","installCommand":"npx skilld install vercel-labs/agent-skills/deploy-to-vercel"},{"owner":"vercel-labs","repository":"agent-skills","name":"composition-patterns","displayName":"vercel-composition-patterns","description":"React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.","stars":32017,"likes":0,"updatedAt":"2026-01-28T16:23:54.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/composition-patterns","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/composition-patterns/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/composition-patterns","installCommand":"npx skilld install vercel-labs/agent-skills/composition-patterns"},{"owner":"vercel-labs","repository":"agent-skills","name":"react-native-skills","displayName":"vercel-react-native-skills","description":"React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.","stars":32017,"likes":0,"updatedAt":"2026-01-27T00:48:33.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/react-native-skills","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/react-native-skills/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/react-native-skills","installCommand":"npx skilld install vercel-labs/agent-skills/react-native-skills"},{"owner":"vercel-labs","repository":"agent-skills","name":"web-design-guidelines","displayName":"web-design-guidelines","description":"Review UI code for Web Interface Guidelines compliance. Use when asked to \"review my UI\", \"check accessibility\", \"audit design\", \"review UX\", or \"check my site against best practices\".","stars":32017,"likes":0,"updatedAt":"2026-01-16T23:47:11.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/web-design-guidelines","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/web-design-guidelines","installCommand":"npx skilld install vercel-labs/agent-skills/web-design-guidelines"}]}

test/fixtures/mcp/search-tailwind.json

@@ -0,0 +1 @@
+{"items":[{"name":"tailwind","description":"Tailwind CSS v4 styling and configuration.","source":{"provider":"github","owner":"pymodel","repository":"react-frontend-skills","selector":{"type":"named-skill","name":"tailwind"}},"stargazerCount":31},{"name":"tailwind-css","description":"Use for Tailwind v4 styling: add/fix classes, configure or migrate Tailwind, use tailwind-variants, or tw-animate-css.","source":{"provider":"github","owner":"paulrberg","repository":"agent-skills","selector":{"type":"named-skill","name":"tailwind-css"}},"stargazerCount":97},{"name":"frontend-tailwind-best-practices","description":"Tailwind CSS patterns and conventions for frontend apps. Use when writing component styles, layouts, or working with CSS classes.","source":{"provider":"github","owner":"sergiodxa","repository":"agent-skills","selector":{"type":"named-skill","name":"frontend-tailwind-best-practices"}},"stargazerCount":90},{"name":"design-tokens","description":"Generate type scales, color palettes, spacing systems, WCAG contrast checks, and dark mode derivations with math. Use when setting up a design system, creating tokens, or building a Tailwind/CSS theme. Outputs CSS custom properties, Tailwind config, or JSON tokens.","source":{"provider":"github","owner":"dylanfeltus","repository":"skills","selector":{"type":"named-skill","name":"design-tokens"}},"stargazerCount":179},{"name":"shadcn-svelte","description":"Use when working with shadcn-svelte components, TanStack Table in Svelte 5, or Tailwind v4.1. Covers non-obvious reactivity bugs, library selection trade-offs, and migration pitfalls not in the official docs. Keywords: shadcn-svelte, TanStack Table, Tailwind v4.1, Svelte 5 runes, bits-ui, superforms, data table, svelte-check. Triggers on \"use shadcn-svelte\" or \"build Svelte data table\".","source":{"provider":"github","owner":"acedergren","repository":"agentic-tools","selector":{"type":"named-skill","name":"shadcn-svelte"}},"stargazerCount":26}],"total":92}

test/fixtures/mcp/skill-web-design-guidelines.json

@@ -0,0 +1 @@
+{"owner":"vercel-labs","repository":"agent-skills","name":"web-design-guidelines","displayName":"web-design-guidelines","description":"Review UI code for Web Interface Guidelines compliance. Use when asked to \"review my UI\", \"check accessibility\", \"audit design\", \"review UX\", or \"check my site against best practices\".","stars":32017,"likes":0,"updatedAt":"2026-01-16T23:47:11.000Z","pageUrl":"https://skilld.dev/gh/vercel-labs/agent-skills/web-design-guidelines","sourceUrl":"https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md","runCommand":"npx skilld run vercel-labs/agent-skills/web-design-guidelines","installCommand":"npx skilld install vercel-labs/agent-skills/web-design-guidelines","authorName":"Vercel Labs","license":null,"repositoryUrl":"https://github.com/vercel-labs/agent-skills","skillPath":"skills/web-design-guidelines/SKILL.md","sourceCommit":"ba46938889d4e58635362fb8f618e1178ac3ec46","sourceGone":false,"pushedAt":"2026-08-28T13:36:31.000Z","tags":[],"allowedTools":[],"files":[],"generatedSummary":"Audits UI code against Vercel's Web Interface Guidelines by fetching the latest ruleset and reporting compliance issues in a terse format. Use this to review HTML, CSS, or component files for accessibility, design system adherence, and UX best practices.","markdown":"---\nname: web-design-guidelines\ndescription: Review UI code for Web Interface Guidelines compliance. Use when asked to \"review my UI\", \"check accessibility\", \"audit design\", \"review UX\", or \"check my site against best practices\".\nmetadata:\n  author: vercel\n  version: \"1.0.0\"\n  argument-hint: <file-or-pattern>\n---\n\n# Web Interface Guidelines\n\nReview files for compliance with Web Interface Guidelines.\n\n## How It Works\n\n1. Fetch the latest guidelines from the source URL below\n2. Read the specified files (or prompt user for files/pattern)\n3. Check against all rules in the fetched guidelines\n4. Output findings in the terse `file:line` format\n\n## Guidelines Source\n\nFetch fresh guidelines before each review:\n\n```\nhttps://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md\n```\n\nUse WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.\n\n## Usage\n\nWhen a user provides a file or pattern argument:\n1. Fetch guidelines from the source URL above\n2. Read the specified files\n3. Apply all rules from the fetched guidelines\n4. Output findings using the format specified in the guidelines\n\nIf no files specified, ask the user which files to review.\n","behaviors":[]}