@cyanheads/mcp-ts-core 0.8.0 → 0.8.2

package/dist/mcp-server/transports/http/landing-page/sections/tools.js

@@ -1,40 +1,73 @@
 /**
- * @fileoverview Tools section — responsive 2-column card grid, optionally
- * prefix-grouped when ≥2 tools share a common `snake_case` prefix. Each card
- * carries annotation pills (read-only / destructive / open-world / task /
- * app), auth scope chips, a JSON-RPC invocation snippet, and a collapsible
- * input-schema preview.
+ * @fileoverview Tools section — responsive card grid grouped by safety
+ * mutability (read / write / destructive). Each card carries annotation
+ * pills, a scope chip, a JSON-RPC invocation snippet, and a collapsible
+ * input-schema preview. A filter bar above the grid wires chip + search
+ * filtering through `data-mutability` / `data-name` attributes consumed
+ * by the inline filter script.
  *
  * @module src/mcp-server/transports/http/landing-page/sections/tools
  */
 import { html } from '../../../../../utils/formatting/html.js';
 import { renderPill, renderSectionHeading, renderSnippet } from '../primitives.js';
+/**
+ * Mutability bucket order — safe defaults first, deliberate engagement last.
+ * Filter chips render in this order too.
+ */
+const MUTABILITY_ORDER = ['read', 'write', 'destructive'];
 export function renderToolsSection(tools) {
     if (tools.length === 0)
         return html ``;
-    const groups = groupToolsByPrefix(tools);
-    // A single group — whether labeled or not — would render as redundant with
-    // the section header. Skip the sub-heading; render a flat grid.
-    const showHeadings = groups.length > 1;
-    const body = groups.map((group) => {
-        const heading = showHeadings && group.label ? html `<h4 class="group-heading">${group.label}</h4>` : html ``;
-        return html `${heading}<div class="card-grid">${group.tools.map(renderToolCard)}</div>`;
+    const buckets = bucketByMutability(tools);
+    const populatedBuckets = MUTABILITY_ORDER.filter((m) => buckets[m].length > 0);
+    // A single bucket is redundant with the section header — skip per-group
+    // labels in that case but keep `data-mutability` on cards so the filter
+    // chips still work.
+    const showHeadings = populatedBuckets.length > 1;
+    const groups = populatedBuckets.map((mutability) => {
+        const bucketTools = buckets[mutability];
+        const heading = showHeadings
+            ? html `<h4 class="group-heading" data-group="${mutability}">${mutability} <span class="group-count">${String(bucketTools.length)}</span></h4>`
+            : html ``;
+        return html `${heading}<div class="card-grid" data-grid="${mutability}">${bucketTools.map((t) => renderToolCard(t, mutability))}</div>`;
     });
     return html `
-    <section aria-labelledby="section-tools">
+    <section aria-labelledby="section-tools" data-tools-section>
       ${renderSectionHeading('section-tools', 'Tools', tools.length)}
-      ${body}
+      ${renderToolFilterBar(populatedBuckets)}
+      <div class="tools-body">${groups}</div>
+      <p class="tools-empty" hidden>No tools match the current filter.</p>
     </section>
   `;
 }
-function renderToolCard(tool) {
+function renderToolFilterBar(populatedBuckets) {
+    const chips = [
+        html `<button type="button" class="tool-chip" data-filter-mutability="all" aria-pressed="true">all</button>`,
+    ];
+    for (const m of populatedBuckets) {
+        chips.push(html `<button type="button" class="tool-chip tool-chip--${m}" data-filter-mutability="${m}" aria-pressed="false">${m}</button>`);
+    }
+    return html `
+    <div class="tool-filter-bar" role="search" aria-label="Filter tools">
+      <div class="tool-chips" role="group" aria-label="Filter by mutability">${chips}</div>
+      <label class="tool-search">
+        <span class="visually-hidden">Search tools</span>
+        <input
+          type="search"
+          data-tool-search
+          placeholder="Search tools…"
+          autocomplete="off"
+          spellcheck="false"
+        />
+      </label>
+    </div>
+  `;
+}
+function renderToolCard(tool, mutability) {
     const anchor = `tool-${tool.name}`;
     const annotations = tool.annotations;
-    const pills = [];
-    if (annotations?.readOnlyHint)
-        pills.push(renderPill('read-only', 'readonly'));
-    if (annotations?.destructiveHint === true)
-        pills.push(renderPill('destructive', 'destructive'));
+    // Mutability badge first — the safety signal readers track at a glance.
+    const pills = [renderPill(mutability, mutability)];
     if (annotations?.openWorldHint)
         pills.push(renderPill('open-world', 'openworld'));
     if (tool.isTask)
@@ -42,75 +75,87 @@ function renderToolCard(tool) {
     if (tool.isApp)
         pills.push(renderPill('app', 'app'));
     const source = tool.sourceUrl
-        ? html `<a class="source-link" href="${tool.sourceUrl}" rel="noopener">view source ↗</a>`
+        ? html `<a class="source-link" href="${tool.sourceUrl}" rel="noopener" aria-label="View source for ${tool.name}">view source ↗</a>`
+        : html ``;
+    const scopeChips = tool.auth && tool.auth.length > 0
+        ? html `<span class="card-scope" title="${tool.auth.join(', ')}"><span class="card-meta-label">scope</span>${tool.auth.map((scope) => html ` <code class="scope-chip">${scopeAccessLevel(scope)}</code>`)}</span>`
         : html ``;
     const schemaPreview = tool.inputSchema
         ? html `
-        <details>
-          <summary>Input schema</summary>
+        <details class="card-detail">
+          <summary>schema</summary>
           <pre><code>${JSON.stringify(tool.inputSchema, null, 2)}</code></pre>
         </details>
       `
         : html ``;
     const invocation = html `
-    <details>
-      <summary>Invocation</summary>
+    <details class="card-detail">
+      <summary>invocation</summary>
       ${renderSnippet(`tool-${tool.name}`, buildInvocationSnippet(tool))}
     </details>
   `;
-    const authBadges = tool.auth && tool.auth.length > 0
-        ? html `<div class="card-meta"><span class="card-meta-label">scopes</span>${tool.auth.map((scope) => html ` <span class="pill pill-auth">${scope}</span>`)}</div>`
-        : html ``;
+    // Search target: name + description as a single lowercase string. Hidden
+    // attribute (not visible) so the filter script can match without parsing
+    // DOM text repeatedly. Description gets normalized whitespace so multi-line
+    // entries don't waste haystack length.
+    const searchTarget = `${tool.name} ${tool.description}`.replace(/\s+/g, ' ').toLowerCase();
     return html `
-    <article class="card" id="${anchor}">
-      <div class="card-head">
+    <article
+      class="card tool-card"
+      id="${anchor}"
+      data-tool-card
+      data-mutability="${mutability}"
+      data-name="${tool.name}"
+      data-search="${searchTarget}"
+    >
+      <header class="card-head">
         <h3 class="card-title"><a href="#${anchor}">${tool.name}</a></h3>
         <div class="pill-row" role="list">${pills}</div>
         ${source}
-      </div>
+      </header>
       <p class="card-desc">${tool.description}</p>
-      ${authBadges}
-      ${invocation}
-      ${schemaPreview}
+      <footer class="card-foot">
+        ${scopeChips}
+        <div class="card-actions">
+          ${invocation}
+          ${schemaPreview}
+        </div>
+      </footer>
     </article>
   `;
 }
-function groupToolsByPrefix(tools) {
-    if (tools.length < 3)
-        return [{ label: null, tools }];
-    const prefixCounts = new Map();
-    for (const tool of tools) {
-        const prefix = tool.name.split('_', 1)[0];
-        if (!prefix)
-            continue;
-        prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1);
-    }
-    const groupablePrefixes = new Set([...prefixCounts.entries()].filter(([, count]) => count >= 2).map(([p]) => p));
-    if (groupablePrefixes.size === 0)
-        return [{ label: null, tools }];
-    const groups = new Map();
-    const other = [];
-    for (const tool of tools) {
-        const prefix = tool.name.split('_', 1)[0];
-        if (prefix && groupablePrefixes.has(prefix)) {
-            const list = groups.get(prefix) ?? [];
-            list.push(tool);
-            groups.set(prefix, list);
-        }
-        else {
-            other.push(tool);
-        }
-    }
-    const out = [];
-    for (const [prefix, list] of groups) {
-        out.push({ label: titleCase(prefix), tools: list });
-    }
-    if (other.length > 0)
-        out.push({ label: 'Other', tools: other });
-    return out;
+/**
+ * Map a tool to a mutability bucket using its annotations. The MCP spec
+ * defaults `destructiveHint` to `true`, but treating annotation-less tools
+ * as "destructive" surprises readers — bucket as `write` unless the
+ * destructive hint is explicitly set. Mirrors how the annotation pills
+ * render today (`pill-destructive` requires `=== true`).
+ */
+function classifyMutability(tool) {
+    const a = tool.annotations;
+    if (a?.readOnlyHint === true)
+        return 'read';
+    if (a?.destructiveHint === true)
+        return 'destructive';
+    return 'write';
+}
+function bucketByMutability(tools) {
+    const buckets = { read: [], write: [], destructive: [] };
+    for (const tool of tools)
+        buckets[classifyMutability(tool)].push(tool);
+    return buckets;
 }
-function titleCase(s) {
-    return s.charAt(0).toUpperCase() + s.slice(1);
+/**
+ * Reduce a colon-delimited scope (`tool:foo:read`) to its trailing access
+ * level (`read`). Scopes that don't match the convention render verbatim —
+ * the linter doesn't enforce shape, so falling back is friendlier than
+ * eating the value.
+ */
+function scopeAccessLevel(scope) {
+    const idx = scope.lastIndexOf(':');
+    if (idx < 0 || idx === scope.length - 1)
+        return scope;
+    return scope.slice(idx + 1);
 }
 function buildInvocationSnippet(tool) {
     const args = {};

package/dist/mcp-server/transports/http/landing-page/sections/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../../../src/mcp-server/transports/http/landing-page/sections/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../../../src/mcp-server/transports/http/landing-page/sections/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,IAAI,EAAiB,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAInF;;;GAGG;AACH,MAAM,gBAAgB,GAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AAEjF,MAAM,UAAU,kBAAkB,CAAC,KAAqB;IACtD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA,EAAE,CAAC;IAEtC,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/E,wEAAwE;IACxE,wEAAwE;IACxE,oBAAoB;IACpB,MAAM,YAAY,GAAG,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC;IAEjD,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QACjD,MAAM,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,YAAY;YAC1B,CAAC,CAAC,IAAI,CAAA,yCAAyC,UAAU,KAAK,UAAU,8BAA8B,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc;YAC9I,CAAC,CAAC,IAAI,CAAA,EAAE,CAAC;QACX,OAAO,IAAI,CAAA,GAAG,OAAO,qCAAqC,UAAU,KAAK,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;IACzI,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAA;;QAEL,oBAAoB,CAAC,eAAe,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC;QAC5D,mBAAmB,CAAC,gBAAgB,CAAC;gCACb,MAAM;;;GAGnC,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,gBAAuC;IAClE,MAAM,KAAK,GAAe;QACxB,IAAI,CAAA,uGAAuG;KAC5G,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CACR,IAAI,CAAA,qDAAqD,CAAC,6BAA6B,CAAC,0BAA0B,CAAC,WAAW,CAC/H,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAA;;+EAEkE,KAAK;;;;;;;;;;;;GAYjF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,IAAkB,EAAE,UAAsB;IAChE,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAsD,CAAC;IAEhF,wEAAwE;IACxE,MAAM,KAAK,GAAe,CAAC,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAC/D,IAAI,WAAW,EAAE,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;IAClF,IAAI,IAAI,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAErD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS;QAC3B,CAAC,CAAC,IAAI,CAAA,gCAAgC,IAAI,CAAC,SAAS,gDAAgD,IAAI,CAAC,IAAI,qBAAqB;QAClI,CAAC,CAAC,IAAI,CAAA,EAAE,CAAC;IAEX,MAAM,UAAU,GACd,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAC/B,CAAC,CAAC,IAAI,CAAA,mCAAmC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,+CAA+C,IAAI,CAAC,IAAI,CAAC,GAAG,CACrH,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAA,6BAA6B,gBAAgB,CAAC,KAAK,CAAC,SAAS,CAC7E,SAAS;QACZ,CAAC,CAAC,IAAI,CAAA,EAAE,CAAC;IAEb,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW;QACpC,CAAC,CAAC,IAAI,CAAA;;;uBAGa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;;OAEzD;QACH,CAAC,CAAC,IAAI,CAAA,EAAE,CAAC;IAEX,MAAM,UAAU,GAAG,IAAI,CAAA;;;QAGjB,aAAa,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,EAAE,sBAAsB,CAAC,IAAI,CAAC,CAAC;;GAErE,CAAC;IAEF,yEAAyE;IACzE,yEAAyE;IACzE,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAE3F,OAAO,IAAI,CAAA;;;YAGD,MAAM;;yBAEO,UAAU;mBAChB,IAAI,CAAC,IAAI;qBACP,YAAY;;;2CAGU,MAAM,KAAK,IAAI,CAAC,IAAI;4CACnB,KAAK;UACvC,MAAM;;6BAEa,IAAI,CAAC,WAAW;;UAEnC,UAAU;;YAER,UAAU;YACV,aAAa;;;;GAItB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,IAAkB;IAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,WAAgF,CAAC;IAChG,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,CAAC,EAAE,eAAe,KAAK,IAAI;QAAE,OAAO,aAAa,CAAC;IACtD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAqB;IAC/C,MAAM,OAAO,GAAuC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC7F,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,sBAAsB,CAAC,IAAkB;IAChD,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,KAAK,GAAG,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,OAAO,EAAE,KAAK;QACd,EAAE,EAAE,CAAC;QACL,MAAM,EAAE,YAAY;QACpB,MAAM,EAAE;YACN,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI;SAChB;KACF,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",

package/skills/add-app-tool/SKILL.md

@@ -108,8 +108,10 @@ const APP_HTML = `<!DOCTYPE html>
   <!-- your UI markup -->
 
   <script type="module">
-    // Prefer a bundled or inlined SDK for the final shipped HTML. Leaving a live
-    // CDN import in the served ui:// resource is not the recommended default.
+    // PROTOTYPING ONLY — replace before shipping. Bundle via Vite +
+    // vite-plugin-singlefile or inline the SDK. Live CDN imports require
+    // CSP whitelisting, add supply-chain risk, and break offline use.
+    // See UI Notes below.
     import {
       App,
       applyDocumentTheme,
@@ -186,13 +188,27 @@ export const {{RESOURCE_EXPORT}} = appResource('ui://{{tool-name}}/app.html', {
 });
 ```
 
-## UI Design Notes
+## UI Notes
 
-- **Bundling:** Prefer Vite + `vite-plugin-singlefile` for any UI that uses `@modelcontextprotocol/ext-apps`. The served `ui://` HTML should ideally be self-contained. The inline template literal pattern is fine for zero-dependency UIs or when you inline the SDK yourself.
-- **Client-side SDK:** Author against `@modelcontextprotocol/ext-apps`, but ship a bundled or inlined artifact when possible. Avoid relying on a live CDN import as the default final pattern for portable host compatibility.
-- **CSP:** MCP Apps iframes run under deny-by-default CSP. With `appResource()`, put `_meta.ui.csp.resourceDomains` on the definition and the builder will mirror it into returned `resources/read` content items. With plain `resource()`, you still need to attach `_meta.ui` yourself in `format()`.
-- **App resource `format()`:** `appResource()` already preserves raw HTML for the default app MIME type and mirrors definition `_meta.ui` into content items. Add a custom `format()` only when you need extra per-read metadata or non-default content shaping.
-- **format() for app tools:** The first `text` content block is typically JSON that the UI parses via `ontoolresult`. Additional blocks provide a human-readable fallback that non-app hosts and LLMs consume. Do not rely on the JSON block alone for model-visible detail; the fallback blocks still need to render the fields the LLM must reason about.
+- **Ship self-contained HTML.** Author with Vite + `vite-plugin-singlefile` or inline the SDK. Live CDN imports in a `ui://` resource are a CSP footgun (every domain has to be whitelisted on `_meta.ui.csp.resourceDomains`), a supply-chain footgun (third-party JS executes inside the host's iframe), and a runtime footgun (every render needs network). The `unpkg` line in the template is for prototyping only.
+- **CSP.** MCP Apps iframes run under deny-by-default CSP. With `appResource()`, put `_meta.ui.csp.resourceDomains` on the definition; the builder mirrors it into returned `resources/read` content items. With plain `resource()`, attach `_meta.ui` yourself in `format()`.
+- **Adopt the host's visual identity, don't impose your own.** App UIs render inside the host's iframe alongside its native UI. Three host hooks layer on top of your CSS:
+  - `applyDocumentTheme(hostContext.theme)` — sets `color-scheme` and a `data-theme` attribute on `<html>`
+  - `applyHostStyleVariables(hostContext.styles.variables)` — installs host CSS custom properties on `:root` (host decides the names, e.g. `--mcp-color-bg-primary`)
+  - `applyHostFonts(hostContext.styles.css.fonts)` — installs `@font-face` rules for the host's font stack
+
+  Author CSS to *consume* these via `var(--mcp-color-bg-primary, /* fallback */ #fff)`. Don't hardcode brand colors that fight the host.
+- **Pre-connect baseline.** `app.connect()` is async — host context arrives a frame or two after first paint. Without a baseline, the UI flashes unstyled or wrong-themed on light hosts. Ship a `prefers-color-scheme`-aware default so the first frame is sensible:
+
+  ```css
+  :root { color-scheme: light dark; --bg: #fff; --fg: #111; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0c0d12; --fg: #ededef; } }
+  body { background: var(--bg); color: var(--fg); }
+  ```
+
+  Host vars override these once `onhostcontextchanged` fires.
+- **`format()` for app tools.** The first `text` content block is typically JSON that the UI parses via `ontoolresult`. Additional blocks are the human-readable fallback that non-app hosts and LLMs consume — they must render every field the LLM needs to reason about. JSON-only payloads leave model-visible context blind.
+- **App resource `format()`.** `appResource()` already preserves raw HTML for the default app MIME type and mirrors definition `_meta.ui` into content items. Add a custom `format()` only when you need extra per-read metadata or non-default content shaping.
 
 ## Registration
 

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -234,6 +234,12 @@ Services don't declare `errors: [...]` contracts and don't have `ctx.fail` — t
   ```
 
 - **Tool/resource handlers bubble service errors unchanged** — the contract advertises the *advertised* failure surface, and any code thrown from a service still reaches the client correctly via the auto-classifier. The conformance lint scans handler source text only, so service-thrown codes aren't flagged.
+- **Carry contract `reason` via `data: { reason }`** when the calling tool declares an `errors[]` contract entry for this failure mode. Services can't call `ctx.fail`, but passing the reason in `data` flows through the auto-classifier untouched, so clients see the same `error.data.reason` they'd see from `ctx.fail` — no handler-side catch-and-rethrow needed:
+
+  ```ts
+  // tool declares: errors: [{ reason: 'empty_expression', code: JsonRpcErrorCode.ValidationError, when: '…' }]
+  throw validationError('Expression cannot be empty.', { reason: 'empty_expression' });
+  ```
 
 ## API Efficiency
 

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -269,6 +269,8 @@ export const fetchArticles = tool('fetch_articles', {
 
 `ctx.fail` accepts an optional 4th `options` argument for ES2022 cause chaining: `throw ctx.fail('upstream_error', 'Upstream returned 500', { url }, { cause: e })`.
 
+**Service-thrown contract reasons.** When the throw happens in a called service rather than the handler itself, `ctx.fail` isn't reachable — services don't have `ctx`. Pass `data: { reason: 'X' }` to the factory in the service; the framework's auto-classifier preserves `data` on the wire, so the contract reason rides through unchanged. The handler bubbles the error without catching. See `add-service` for the pattern.
+
 **Fallback: error factories.** Use when no contract entry fits — ad-hoc throws, prototype tools, or service-layer code. The framework also auto-classifies plain `throw new Error()` from message patterns as a last resort.
 
 ```typescript

package/skills/api-errors/SKILL.md

@@ -4,7 +4,7 @@ description: >
   McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
@@ -69,6 +69,26 @@ export const fetchTool = tool('fetch_articles', {
 
 > **Limits of the conformance lint.** The conformance and prefer-fail rules scan the handler's source text for `throw` statements. Errors thrown from called services (e.g. `await myService.fetch()` raising `RateLimited` internally) are invisible — the lint only sees what's lexically in the handler. Treat the contract as the *advertised* failure surface; bubbled-up codes still reach the client correctly via the auto-classifier, just without lint enforcement.
 
+### Carrying contract `reason` from services
+
+Services don't have `ctx`, so they can't call `ctx.fail`. To make a service-thrown failure carry the contract's `reason` on the wire, **pass `data: { reason: 'X' }` to the factory**. The framework's auto-classifier preserves `data` unchanged, so clients see the same `error.data.reason` they'd see from `ctx.fail`:
+
+```ts
+// my-service.ts
+throw validationError('Expression cannot be empty.',  { reason: 'empty_expression' });
+throw serviceUnavailable('Upstream timeout',          { reason: 'evaluation_timeout' });
+```
+
+```ts
+// my-tool.tool.ts
+errors: [
+  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,    when: 'Input is empty.' },
+  { reason: 'evaluation_timeout', code: JsonRpcErrorCode.ServiceUnavailable, when: 'Upstream exceeded the configured timeout.' },
+]
+```
+
+The handler doesn't catch and re-throw — letting service errors bubble unchanged keeps "logic throws, framework catches" intact. The contract still publishes in `tools/list`, the wire payload still carries `code` + `data.reason`, and clients can switch on reason without parsing message text. What's lost is lint-time enforcement that every reason is reachable; compensate with one wire-shape test per reason.
+
 ---
 
 ## Error Factories (fallback)

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.1"
   audience: external
   type: debug
 ---
@@ -27,14 +27,20 @@ Write the helper to `/tmp/mcp-field-test.sh` once, then source it in every subse
 cat > /tmp/mcp-field-test.sh <<'HELPER_EOF'
 #!/bin/bash
 # Field-test helper: manage an MCP HTTP server + JSON-RPC session across shell calls.
+# Surfaces failures aggressively — field test is for finding things that fail,
+# so the helper auto-tails logs and prints HTTP status/body on errors instead
+# of swallowing them.
 STATE_FILE="/tmp/mcp-field-test.env"
 [ -f "$STATE_FILE" ] && . "$STATE_FILE"
 
 mcp_start() {
   local dir="${1:-$PWD}"
   echo "building $dir ..."
-  (cd "$dir" && bun run rebuild) >/tmp/mcp-build.log 2>&1 \
-    || { echo "BUILD FAILED — see /tmp/mcp-build.log"; return 1; }
+  if ! (cd "$dir" && bun run rebuild) >/tmp/mcp-build.log 2>&1; then
+    echo "BUILD FAILED — last 30 lines of /tmp/mcp-build.log:"
+    tail -30 /tmp/mcp-build.log
+    return 1
+  fi
   echo "starting server ..."
   (cd "$dir" && bun run start:http) >/tmp/mcp-server.log 2>&1 &
   local pid=$!
@@ -45,7 +51,8 @@ mcp_start() {
     sleep 0.25
   done
   if [ -z "$line" ]; then
-    echo "server failed to start — see /tmp/mcp-server.log"
+    echo "server failed to start within 10s — last 30 lines of /tmp/mcp-server.log:"
+    tail -30 /tmp/mcp-server.log
     kill "$pid" 2>/dev/null
     return 1
   fi
@@ -63,12 +70,21 @@ EOF
 mcp_init() {
   [ -z "$MCP_URL" ] && { echo "run mcp_start first"; return 1; }
   local hdr="/tmp/mcp-init-headers.txt"
-  curl -sS -D "$hdr" -X POST "$MCP_URL" \
+  local body_file="/tmp/mcp-init-body.txt"
+  local status
+  status=$(curl -sS -D "$hdr" -o "$body_file" -w '%{http_code}' -X POST "$MCP_URL" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
-    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.0"}}}' >/dev/null
+    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.1"}}}')
   local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
-  [ -z "$sid" ] && { echo "no session id returned"; return 1; }
+  if [ -z "$sid" ]; then
+    echo "init failed — HTTP $status, no Mcp-Session-Id header returned"
+    echo "--- response body ---"
+    cat "$body_file"
+    echo "--- response headers ---"
+    cat "$hdr"
+    return 1
+  fi
   cat > "$STATE_FILE" <<EOF
 export MCP_PID=$MCP_PID
 export MCP_URL=$MCP_URL
@@ -81,11 +97,13 @@ EOF
     -H "Accept: application/json, text/event-stream" \
     -H "Mcp-Session-Id: $sid" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
-  echo "session=$sid"
+  echo "session=$sid (HTTP $status)"
 }
 
 # Usage: mcp_call METHOD [JSON_PARAMS]
-# Prints the JSON-RPC response (SSE framing stripped). Pipe to `jq`.
+# Prints the JSON-RPC response. SSE framing is stripped when present; on
+# non-SSE responses the raw body is printed instead so plain-JSON error
+# replies (HTTP 4xx/5xx) still surface. Pipe to `jq`.
 mcp_call() {
   [ -z "$MCP_SID" ] && { echo "run mcp_init first"; return 1; }
   local method="$1"; local params="${2:-}"
@@ -95,17 +113,57 @@ mcp_call() {
   else
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s","params":%s}' "$RANDOM" "$method" "$params")
   fi
-  curl -sS -X POST "$MCP_URL" \
+  local resp_file="/tmp/mcp-call-body.txt"
+  local status
+  status=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$MCP_URL" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Mcp-Session-Id: $MCP_SID" \
-    -d "$body" | sed -n 's/^data: //p'
+    -d "$body")
+  if [ "$status" -ge 400 ]; then
+    echo "HTTP $status from $method — response:" >&2
+    cat "$resp_file" >&2
+    return 1
+  fi
+  local sse; sse=$(sed -n 's/^data: //p' "$resp_file")
+  if [ -n "$sse" ]; then
+    printf '%s\n' "$sse"
+  else
+    cat "$resp_file"
+  fi
+}
+
+# Tail the server log. Useful when a call surprises you — pino startup banner,
+# definition lint diagnostics, request handler errors, upstream calls, and
+# rate-limit warnings live in /tmp/mcp-server.log.
+# Usage: mcp_log [N]   (default: 50 lines)
+mcp_log() {
+  local n="${1:-50}"
+  tail -n "$n" /tmp/mcp-server.log
 }
 
 mcp_stop() {
-  [ -n "$MCP_PID" ] && kill "$MCP_PID" 2>/dev/null
+  if [ -z "$MCP_PID" ]; then
+    rm -f "$STATE_FILE"
+    echo "no PID to stop"
+    return 0
+  fi
+  kill "$MCP_PID" 2>/dev/null
+  for _ in $(seq 1 12); do
+    kill -0 "$MCP_PID" 2>/dev/null || break
+    sleep 0.25
+  done
+  if kill -0 "$MCP_PID" 2>/dev/null; then
+    echo "PID $MCP_PID didn't exit on SIGTERM — sending SIGKILL"
+    kill -9 "$MCP_PID" 2>/dev/null
+    sleep 0.5
+  fi
+  if kill -0 "$MCP_PID" 2>/dev/null; then
+    echo "WARNING: PID $MCP_PID still alive after SIGKILL"
+  else
+    echo "stopped pid=$MCP_PID"
+  fi
   rm -f "$STATE_FILE"
-  echo "stopped"
 }
 HELPER_EOF
 
@@ -190,6 +248,8 @@ Use `TaskCreate` — one task per definition. Mark complete as you go. Don't bat
 
 For each call, capture: input sent, response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
 
+When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/mcp-field-test.sh && mcp_log` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in `/tmp/mcp-server.log` rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone.
+
 **Interpreting responses**
 
 - Tool domain errors return `{result: {content: [...], isError: true}}` — they live in `result`, not `error`. Check `isError`, not the JSON-RPC error field.