shmakk 1.1.0 → 1.2.0

package/skills/backend-build-mcp-app.md

@@ -0,0 +1,393 @@
+---
+name: build-mcp-app
+description: This skill should be used when the user wants to build an "MCP app", add "interactive UI" or "widgets" to an MCP server, "render components in chat", build "MCP UI resources", make a tool that shows a "form", "picker", "dashboard" or "confirmation dialog" inline in the conversation, or mentions "apps SDK" in the context of MCP. Use AFTER the build-mcp-server skill has settled the deployment model, or when the user already knows they want UI widgets.
+version: 0.1.0
+category: backend
+---
+
+# Build an MCP App (Interactive UI Widgets)
+
+An MCP app is a standard MCP server that **also serves UI resources** — interactive components rendered inline in the chat surface. Build once, runs in Claude *and* ChatGPT and any other host that implements the apps surface.
+
+The UI layer is **additive**. Under the hood it's still tools, resources, and the same wire protocol. If you haven't built a plain MCP server before, the `build-mcp-server` skill covers the base layer. This skill adds widgets on top.
+
+> **Testing in Claude:** Add the server as a custom connector in claude.ai (via a Cloudflare tunnel for local dev) — this exercises the real iframe sandbox and `hostContext`. See https://claude.com/docs/connectors/building/testing.
+
+## Claude host specifics
+
+| `_meta.ui.*` key | Where | Effect |
+|---|---|---|
+| `resourceUri` | tool | Which `ui://` resource the host renders for this tool's results. |
+| `visibility: ["app"]` | tool | Hide a widget-only helper tool (e.g. geometry/image fetcher called via `callServerTool`) from Claude's tool list. |
+| `prefersBorder: false` | resource | Drop the host's outer card border (mobile). |
+| `csp.{connectDomains, resourceDomains, baseUriDomains}` | resource | Declare external origins; default is block-all. `frameDomains` is currently restricted in Claude. |
+
+- `hostContext.safeAreaInsets: {top, right, bottom, left}` (px) — honor these for notches and the composer overlay.
+- Directory submission requires OAuth or **authless** (`none`) — static bearer is private-deploy only and blocks listing — plus tool `annotations` and 3–5 PNG screenshots; see `references/directory-checklist.md`.
+
+---
+
+## When a widget beats plain text
+
+Don't add UI for its own sake — most tools are fine returning text or JSON. Add a widget when one of these is true:
+
+| Signal | Widget type |
+|---|---|
+| Tool needs structured input Claude can't reliably infer | Form |
+| User must pick from a list Claude can't rank (files, contacts, records) | Picker / table |
+| Destructive or billable action needs explicit confirmation | Confirm dialog |
+| Output is spatial or visual (charts, maps, diffs, previews) | Display widget |
+| Long-running job the user wants to watch | Progress / live status |
+
+If none apply, skip the widget. Text is faster to build and faster for the user.
+
+---
+
+## Widgets vs Elicitation — route correctly
+
+Before building a widget, check if **elicitation** covers it. Elicitation is spec-native, zero UI code, works in any compliant host.
+
+| Need | Elicitation | Widget |
+|---|---|---|
+| Confirm yes/no | ✅ | overkill |
+| Pick from short enum | ✅ | overkill |
+| Fill a flat form (name, email, date) | ✅ | overkill |
+| Pick from a large/searchable list | ❌ (no scroll/search) | ✅ |
+| Visual preview before choosing | ❌ | ✅ |
+| Chart / map / diff view | ❌ | ✅ |
+| Live-updating progress | ❌ | ✅ |
+
+If elicitation covers it, use it. See `../build-mcp-server/references/elicitation.md`.
+
+---
+
+## Architecture: two deployment shapes
+
+### Remote MCP app (most common)
+
+Hosted streamable-HTTP server. Widget templates are served as **resources**; tool results reference them. The host fetches the resource, renders it in an iframe sandbox, and brokers messages between the widget and Claude.
+
+```
+┌──────────┐  tools/call   ┌────────────┐
+│  Claude  │─────────────> │ MCP server │
+│   host   │<── result ────│  (remote)  │
+│          │  + widget ref │            │
+│          │               │            │
+│          │ resources/read│            │
+│          │─────────────> │  widget    │
+│ ┌──────┐ │<── template ──│  HTML/JS   │
+│ │iframe│ │               └────────────┘
+│ │widget│ │
+│ └──────┘ │
+└──────────┘
+```
+
+### MCPB-packaged MCP app (local + UI)
+
+Same widget mechanism, but the server runs locally inside an MCPB bundle. Use this when the widget needs to drive a **local** application — e.g., a file picker that browses the actual local disk, a dialog that controls a desktop app.
+
+For MCPB packaging mechanics, defer to the **`build-mcpb`** skill. Everything below applies to both shapes.
+
+---
+
+## How widgets attach to tools
+
+A widget-enabled tool has **two separate registrations**:
+
+1. **The tool** declares a UI resource via `_meta.ui.resourceUri`. Its handler returns plain text/JSON — NOT the HTML.
+2. **The resource** is registered separately and serves the HTML.
+
+When Claude calls the tool, the host sees `_meta.ui.resourceUri`, fetches that resource, renders it in an iframe, and pipes the tool's return value into the iframe via the `ontoolresult` event.
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE }
+  from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+
+const server = new McpServer({ name: "contacts", version: "1.0.0" });
+
+// 1. The tool — returns DATA, declares which UI to show
+registerAppTool(server, "pick_contact", {
+  description: "Open an interactive contact picker",
+  annotations: { title: "Pick Contact", readOnlyHint: true },
+  inputSchema: { filter: z.string().optional() },
+  _meta: { ui: { resourceUri: "ui://widgets/contact-picker.html" } },
+}, async ({ filter }) => {
+  const contacts = await db.contacts.search(filter);
+  // Plain JSON — the widget receives this via ontoolresult
+  return { content: [{ type: "text", text: JSON.stringify(contacts) }] };
+});
+
+// 2. The resource — serves the HTML
+registerAppResource(
+  server,
+  "Contact Picker",
+  "ui://widgets/contact-picker.html",
+  {},
+  async () => ({
+    contents: [{
+      uri: "ui://widgets/contact-picker.html",
+      mimeType: RESOURCE_MIME_TYPE,
+      text: pickerHtml,  // your HTML string
+    }],
+  }),
+);
+```
+
+The URI scheme `ui://` is convention. The mime type MUST be `RESOURCE_MIME_TYPE` (`"text/html;profile=mcp-app"`) — this is how the host knows to render it as an interactive iframe, not just display the source.
+
+---
+
+## Widget runtime — the `App` class
+
+Inside the iframe, your script talks to the host via the `App` class from `@modelcontextprotocol/ext-apps`. This is a **persistent bidirectional connection** — the widget stays alive as long as the conversation is active, receiving new tool results and sending user actions.
+
+```html
+<script type="module">
+  /* ext-apps bundle inlined at build time → globalThis.ExtApps */
+  /*__EXT_APPS_BUNDLE__*/
+  const { App } = globalThis.ExtApps;
+
+  const app = new App({ name: "ContactPicker", version: "1.0.0" }, {});
+
+  // Set handlers BEFORE connecting
+  app.ontoolresult = ({ content }) => {
+    const contacts = JSON.parse(content[0].text);
+    render(contacts);
+  };
+
+  await app.connect();
+
+  // Later, when the user clicks something:
+  function onPick(contact) {
+    app.sendMessage({
+      role: "user",
+      content: [{ type: "text", text: `Selected contact: ${contact.id}` }],
+    });
+  }
+</script>
+```
+
+The `/*__EXT_APPS_BUNDLE__*/` placeholder gets replaced by the server at startup with the contents of `@modelcontextprotocol/ext-apps/app-with-deps` — see `references/iframe-sandbox.md` for why this is necessary and the rewrite snippet. **Do not** `import { App } from "https://esm.sh/..."`; the iframe's CSP blocks the transitive dependency fetches and the widget renders blank.
+
+| Method | Direction | Use for |
+|---|---|---|
+| `app.ontoolresult = fn` | Host → widget | Receive the tool's return value |
+| `app.ontoolinput = fn` | Host → widget | Receive the tool's input args (what Claude passed) |
+| `app.sendMessage({...})` | Widget → host | Inject a message into the conversation |
+| `app.updateModelContext({...})` | Widget → host | Update context silently (no visible message) |
+| `app.callServerTool({name, arguments})` | Widget → server | Call another tool on your server |
+| `app.openLink({url})` | Widget → host | Open a URL in a new tab (sandbox blocks `window.open`) |
+| `app.getHostContext()` / `app.onhostcontextchanged` | Host → widget | Theme, host CSS vars, `containerDimensions`, `displayMode`, `deviceCapabilities` |
+| `app.requestDisplayMode({mode})` | Widget → host | Ask for `inline` / `pip` / `fullscreen` |
+| `app.downloadFile({name, mimeType, content})` | Widget → host | Host-mediated download (base64 content) |
+| `new App(info, caps, {autoResize: true})` | — | Iframe height tracks rendered content |
+
+`sendMessage` is the typical "user picked something, tell Claude" path. `updateModelContext` is for state that Claude should know about but shouldn't clutter the chat. `openLink` is **required** for any outbound navigation — `window.open` and `<a target="_blank">` are blocked by the sandbox attribute.
+
+**What widgets cannot do:**
+- Access the host page's DOM, cookies, or storage
+- Make network calls to arbitrary origins (CSP-restricted — route through `callServerTool`)
+- Open popups or navigate directly — use `app.openLink({url})`
+- Load remote images reliably — inline as `data:` URLs server-side
+
+Keep widgets **small and single-purpose**. A picker picks. A chart displays. Don't build a whole sub-app inside the iframe — split it into multiple tools with focused widgets.
+
+---
+
+## Scaffold: minimal picker widget
+
+**Install:**
+
+```bash
+npm install @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod express
+```
+
+**Server (`src/server.ts`):**
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE }
+  from "@modelcontextprotocol/ext-apps/server";
+import express from "express";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { z } from "zod";
+
+const require = createRequire(import.meta.url);
+const server = new McpServer({ name: "contact-picker", version: "1.0.0" });
+
+// Inline the ext-apps browser bundle into the widget HTML.
+// The iframe CSP blocks CDN script fetches — bundling is mandatory.
+const bundle = readFileSync(
+  require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"), "utf8",
+).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
+  "globalThis.ExtApps={" +
+  body.split(",").map((p) => {
+    const [local, exported] = p.split(" as ").map((s) => s.trim());
+    return `${exported ?? local}:${local}`;
+  }).join(",") + "};",
+);
+const pickerHtml = readFileSync("./widgets/picker.html", "utf8")
+  .replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);
+
+registerAppTool(server, "pick_contact", {
+  description: "Open an interactive contact picker. User selects one contact.",
+  annotations: { title: "Pick Contact", readOnlyHint: true },
+  inputSchema: { filter: z.string().optional().describe("Name/email prefix filter") },
+  _meta: { ui: { resourceUri: "ui://widgets/picker.html" } },
+}, async ({ filter }) => {
+  const contacts = await db.contacts.search(filter ?? "");
+  return { content: [{ type: "text", text: JSON.stringify(contacts) }] };
+});
+
+registerAppResource(server, "Contact Picker", "ui://widgets/picker.html", {},
+  async () => ({
+    contents: [{ uri: "ui://widgets/picker.html", mimeType: RESOURCE_MIME_TYPE, text: pickerHtml }],
+  }),
+);
+
+const app = express();
+app.use(express.json());
+app.post("/mcp", async (req, res) => {
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  res.on("close", () => transport.close());
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+app.listen(process.env.PORT ?? 3000);
+```
+
+For local-only widget apps (driving a desktop app, reading local files), swap the transport to `StdioServerTransport` and package via the `build-mcpb` skill.
+
+**Widget (`widgets/picker.html`):**
+
+```html
+<!doctype html>
+<meta charset="utf-8" />
+<style>
+  body { font: 14px system-ui; margin: 0; }
+  ul { list-style: none; padding: 0; margin: 0; max-height: 300px; overflow-y: auto; }
+  li { padding: 10px 14px; cursor: pointer; border-bottom: 1px solid #eee; }
+  li:hover { background: #f5f5f5; }
+  .sub { color: #666; font-size: 12px; }
+</style>
+<ul id="list"></ul>
+<script type="module">
+/*__EXT_APPS_BUNDLE__*/
+const { App } = globalThis.ExtApps;
+(async () => {
+  const app = new App({ name: "ContactPicker", version: "1.0.0" }, {});
+  const ul = document.getElementById("list");
+
+  app.ontoolresult = ({ content }) => {
+    const contacts = JSON.parse(content[0].text);
+    ul.innerHTML = "";
+    for (const c of contacts) {
+      const li = document.createElement("li");
+      li.innerHTML = `<div>${c.name}</div><div class="sub">${c.email}</div>`;
+      li.addEventListener("click", () => {
+        app.sendMessage({
+          role: "user",
+          content: [{ type: "text", text: `Selected contact: ${c.id} (${c.name})` }],
+        });
+      });
+      ul.append(li);
+    }
+  };
+
+  await app.connect();
+})();
+</script>
+```
+
+See `references/widget-templates.md` for more widget shapes.
+
+---
+
+## Design notes that save you a rewrite
+
+**One widget per tool.** Resist the urge to build one mega-widget that does everything. One tool → one focused widget → one clear result shape. Claude reasons about these far better.
+
+**Tool description must mention the widget.** Claude only sees the tool description when deciding what to call. "Opens an interactive picker" in the description is what makes Claude reach for it instead of guessing an ID.
+
+**Widgets are optional at runtime.** Hosts that don't support the apps surface simply ignore `_meta.ui` and render the tool's text content normally. Since your tool handler already returns meaningful text/JSON (the widget's data), degradation is automatic — Claude sees the data directly instead of via the widget.
+
+**Don't block on widget results for read-only tools.** A widget that just *displays* data (chart, preview) shouldn't require a user action to complete. Return the display widget *and* a text summary in the same result so Claude can continue reasoning without waiting.
+
+**Layout-fork by item count, not by tool count.** If one use case is "show one result in detail" and another is "show many results side-by-side", don't make two tools — make one tool that accepts `items[]`, and let the widget pick a layout: `items.length === 1` → detail view, `> 1` → carousel. Keeps the server schema simple and lets Claude decide count naturally.
+
+**Put Claude's reasoning in the payload.** A short `note` field on each item (why Claude picked it) rendered as a callout on the card gives users the reasoning inline with the choice. Mention this field in the tool description so Claude populates it.
+
+**Normalize image shapes server-side.** If your data source returns images with wildly varying aspect ratios, rewrite to a predictable variant (e.g. square-bounded) *before* fetching for the data-URL inline. Then give the widget's image container a fixed `aspect-ratio` + `object-fit: contain` so everything sits centered.
+
+**Follow host theme.** `app.getHostContext()?.theme` (after `connect()`) plus `app.onhostcontextchanged` for live updates. Toggle a `.dark` class on `<html>`, keep colors in CSS custom props with a `:root.dark {}` override block, set `color-scheme`. Disable `mix-blend-mode: multiply` in dark — it makes images vanish.
+
+---
+
+## Testing
+
+**Claude Desktop** — current builds still require the `command`/`args` config shape (no native `"type": "http"`). Wrap with `mcp-remote` and force `http-only` transport so the SSE probe doesn't swallow widget-capability negotiation:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp",
+               "--allow-http", "--transport", "http-only"]
+    }
+  }
+}
+```
+
+Desktop caches UI resources aggressively. After editing widget HTML, **fully quit** (⌘Q / Alt+F4, not window-close) and relaunch to force a cold resource re-fetch.
+
+**Headless JSON-RPC loop** — fast iteration without clicking through Desktop:
+
+```bash
+# test.jsonl — one JSON-RPC message per line
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}
+{"jsonrpc":"2.0","method":"notifications/initialized"}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"your_tool","arguments":{...}}}
+
+(cat test.jsonl; sleep 10) | npx mcp-remote http://localhost:3000/mcp --allow-http
+```
+
+The `sleep` keeps stdin open long enough to collect all responses. Parse the jsonl output with `jq` or a Python one-liner.
+
+**Widget dev loop** — avoid the ⌘Q-relaunch cycle entirely by serving the inlined widget HTML at a plain GET route with a fake `ExtApps` shim that fires `ontoolresult` from a query param:
+
+```ts
+app.get("/widget-preview", (_req, res) => {
+  const shim = `globalThis.ExtApps={applyHostStyleVariables:()=>{},App:class{
+    constructor(){this.h={}} ontoolresult;onhostcontextchanged;
+    async connect(){const p=new URLSearchParams(location.search).get("payload");
+      if(p)this.ontoolresult?.({content:[{type:"text",text:p}]});}
+    getHostContext(){return{theme:"light"}}
+    sendMessage(m){console.log("sendMessage",m)} updateModelContext(){}
+    callServerTool(){return Promise.resolve({content:[]})} openLink(){} downloadFile(){}
+  }};`;
+  res.type("html").send(widgetHtml.replace("/*__EXT_APPS_BUNDLE__*/", shim));
+});
+```
+
+Open `http://localhost:3000/widget-preview?payload={"rows":[...]}` in a normal browser tab and iterate with ordinary devtools.
+
+**Host fallback** — use a host without the apps surface (or MCP Inspector) and confirm the tool's text content degrades gracefully.
+
+**CSP debugging** — open the iframe's own devtools console. CSP violations are the #1 reason widgets silently fail (blank rectangle, no error in the main console). See `references/iframe-sandbox.md`.
+
+---
+
+## Reference files
+
+- `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling, host theming
+- `references/widget-templates.md` — reusable HTML scaffolds for picker / confirm / progress / display
+- `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging, lifecycle & supersession
+- `references/payload-budgeting.md` — host tool-result size caps, prune-then-truncate, heavy assets via `callServerTool`
+- `references/abuse-protection.md` — Anthropic egress CIDRs, tiered rate limiting, `trust proxy`, response caching
+- `references/directory-checklist.md` — pre-flight for connector-directory submission

package/skills/backend-build-mcp-server.md

@@ -0,0 +1,222 @@
+---
+name: build-mcp-server
+description: This skill should be used when the user asks to "build an MCP server", "create an MCP", "make an MCP integration", "wrap an API for Claude", "expose tools to Claude", "make an MCP app", or discusses building something with the Model Context Protocol. It is the entry point for MCP server development — it interrogates the user about their use case, determines the right deployment model (remote HTTP, MCPB, local stdio), picks a tool-design pattern, and hands off to specialized skills.
+version: 0.1.0
+category: backend
+---
+
+# Build an MCP Server
+
+You are guiding a developer through designing and building an MCP server that works seamlessly with Claude. MCP servers come in many forms — picking the wrong shape early causes painful rewrites later. Your first job is **discovery, not code**.
+
+**Load Claude-specific context first.** The MCP spec is generic; Claude has additional auth types, review criteria, and limits. Before answering questions or scaffolding, fetch `https://claude.com/docs/llms-full.txt` (the full export of the Claude connector docs) so your guidance reflects Claude's actual constraints.
+
+Do not start scaffolding until you have answers to the questions in Phase 1. If the user's opening message already answers them, acknowledge that and skip straight to the recommendation.
+
+---
+
+## Phase 1 — Interrogate the use case
+
+Ask these questions conversationally (batch them into one message, don't interrogate one-at-a-time). Adapt wording to what the user has already told you.
+
+### 1. What does it connect to?
+
+| If it connects to… | Likely direction |
+|---|---|
+| A cloud API (SaaS, REST, GraphQL) | Remote HTTP server |
+| A local process, filesystem, or desktop app | MCPB or local stdio |
+| Hardware, OS-level APIs, or user-specific state | MCPB |
+| Nothing external — pure logic / computation | Either — default to remote |
+
+### 2. Who will use it?
+
+- **Just me / my team, on our machines** → Local stdio is acceptable (easiest to prototype)
+- **Anyone who installs it** → Remote HTTP (strongly preferred) or MCPB (if it *must* be local)
+- **Users of Claude desktop who want UI widgets** → MCP app (remote or MCPB)
+
+### 3. How many distinct actions does it expose?
+
+This determines the tool-design pattern — see Phase 3.
+
+- **Under ~15 actions** → one tool per action
+- **Dozens to hundreds of actions** (e.g. wrapping a large API surface) → search + execute pattern
+
+### 4. Does a tool need mid-call user input or rich display?
+
+- **Simple structured input** (pick from list, enter a value, confirm) → **Elicitation** — spec-native, zero UI code. *Host support is rolling out* (Claude Code ≥2.1.76) — always pair with a capability check and fallback. See `references/elicitation.md`.
+- **Rich/visual UI** (charts, custom pickers with search, live dashboards) → **MCP app widgets** — iframe-based, needs `@modelcontextprotocol/ext-apps`. See `build-mcp-app` skill.
+- **Neither** → plain tool returning text/JSON.
+
+### 5. What auth does the upstream service use?
+
+- None / API key → straightforward
+- OAuth 2.0 → you'll need a remote server with CIMD (preferred) or DCR support; see `references/auth.md`
+
+---
+
+## Phase 2 — Recommend a deployment model
+
+Based on the answers, recommend **one** path. Be opinionated. The ranked options:
+
+### ⭐ Remote streamable-HTTP MCP server (default recommendation)
+
+A hosted service speaking MCP over streamable HTTP. This is the **recommended path** for anything wrapping a cloud API.
+
+**Why it wins:**
+- Zero install friction — users add a URL, done
+- One deployment serves all users; you control upgrades
+- OAuth flows work properly (the server can handle redirects, DCR, token storage)
+- Works across Claude desktop, Claude Code, Claude.ai, and third-party MCP hosts
+
+**Choose this unless** the server *must* touch the user's local machine.
+
+→ **Fastest deploy:** Cloudflare Workers — `references/deploy-cloudflare-workers.md` (zero to live URL in two commands)
+→ **Portable Node/Python:** `references/remote-http-scaffold.md` (Express or FastMCP, runs on any host)
+
+### Elicitation (structured input, no UI build)
+
+If a tool just needs the user to confirm, pick an option, or fill a short form, **elicitation** does it with zero UI code. The server sends a flat JSON schema; the host renders a native form. Spec-native, no extra packages.
+
+**Caveat:** Host support is new (Claude Code shipped it in v2.1.76; Desktop unconfirmed). The SDK throws if the client doesn't advertise the capability. Always check `clientCapabilities.elicitation` first and have a fallback — see `references/elicitation.md` for the canonical pattern. This is the right spec-correct approach; host coverage will catch up.
+
+Escalate to `build-mcp-app` widgets when you need: nested/complex data, scrollable/searchable lists, visual previews, live updates.
+
+### MCP app (remote HTTP + interactive UI)
+
+Same as above, plus **UI resources** — interactive widgets rendered in chat. Rich pickers with search, charts, live dashboards, visual previews. Built once, renders in Claude *and* ChatGPT.
+
+**Choose this when** elicitation's flat-form constraints don't fit — you need custom layout, large searchable lists, visual content, or live updates.
+
+Usually remote, but can be shipped as MCPB if the UI needs to drive a local app.
+
+→ Hand off to the **`build-mcp-app`** skill.
+
+### MCPB (bundled local server)
+
+A local MCP server **packaged with its runtime** so users don't need Node/Python installed. The sanctioned way to ship local servers.
+
+**Choose this when** the server *must* run on the user's machine — it reads local files, drives a desktop app, talks to localhost services, or needs OS-level access.
+
+→ Hand off to the **`build-mcpb`** skill.
+
+### Local stdio (npx / uvx) — *not recommended for distribution*
+
+A script launched via `npx` / `uvx` on the user's machine. Fine for **personal tools and prototypes**. Painful to distribute: users need the right runtime, you can't push updates, and the only distribution channel is Claude Code plugins.
+
+Recommend this only as a stepping stone. If the user insists, scaffold it but note the MCPB upgrade path.
+
+---
+
+## Phase 3 — Pick a tool-design pattern
+
+Every MCP server exposes tools. How you carve them matters more than most people expect — tool schemas land directly in Claude's context window.
+
+### Pattern A: One tool per action (small surface)
+
+When the action space is small (< ~15 operations), give each a dedicated tool with a tight description and schema.
+
+```
+create_issue    — Create a new issue. Params: title, body, labels[]
+update_issue    — Update an existing issue. Params: id, title?, body?, state?
+search_issues   — Search issues by query string. Params: query, limit?
+add_comment     — Add a comment to an issue. Params: issue_id, body
+```
+
+**Why it works:** Claude reads the tool list once and knows exactly what's possible. No discovery round-trips. Each tool's schema validates inputs precisely.
+
+**Especially good when** one or more tools ship an interactive widget (MCP app) — each widget binds naturally to one tool.
+
+### Pattern B: Search + execute (large surface)
+
+When wrapping a large API (dozens to hundreds of endpoints), listing every operation as a tool floods the context window and degrades model performance. Instead, expose **two** tools:
+
+```
+search_actions  — Given a natural-language intent, return matching actions
+                  with their IDs, descriptions, and parameter schemas.
+execute_action  — Run an action by ID with a params object.
+```
+
+The server holds the full catalog internally. Claude searches, picks, executes. Context stays lean.
+
+**Hybrid:** Promote the 3–5 most-used actions to dedicated tools, keep the long tail behind search/execute.
+
+→ See `references/tool-design.md` for schema examples and description-writing guidance.
+
+---
+
+## Phase 4 — Pick a framework
+
+Recommend one of these two. Others exist but these have the best MCP-spec coverage and Claude compatibility.
+
+| Framework | Language | Use when |
+|---|---|---|
+| **Official TypeScript SDK** (`@modelcontextprotocol/sdk`) | TS/JS | Default choice. Best spec coverage, first to get new features. |
+| **FastMCP 3.x** (`fastmcp` on PyPI) | Python | User prefers Python, or wrapping a Python library. Decorator-based, very low boilerplate. This is jlowin's package — not the frozen FastMCP 1.0 bundled in the official `mcp` SDK. |
+
+If the user already has a language/stack in mind, go with it — both produce identical wire protocol.
+
+---
+
+## Phase 5 — Scaffold and hand off
+
+Once you've settled the four decisions (deployment model, tool pattern, framework, auth), do **one** of:
+
+1. **Remote HTTP, no UI** → Scaffold inline using `references/remote-http-scaffold.md` (portable) or `references/deploy-cloudflare-workers.md` (fastest deploy). This skill can finish the job.
+2. **MCP app (UI widgets)** → Summarize the decisions so far, then load the **`build-mcp-app`** skill.
+3. **MCPB (bundled local)** → Summarize the decisions so far, then load the **`build-mcpb`** skill.
+4. **Local stdio prototype** → Scaffold inline (simplest case), flag the MCPB upgrade path.
+
+When handing off, restate the design brief in one paragraph so the next skill doesn't re-ask.
+
+---
+
+## Beyond tools — the other primitives
+
+Tools are one of three server primitives. Most servers start with tools and never need the others, but knowing they exist prevents reinventing wheels:
+
+| Primitive | Who triggers it | Use when |
+|---|---|---|
+| **Resources** | Host app (not Claude) | Exposing docs/files/data as browsable context |
+| **Prompts** | User (slash command) | Canned workflows ("/summarize-thread") |
+| **Elicitation** | Server, mid-tool | Asking user for input without building UI |
+| **Sampling** | Server, mid-tool | Need LLM inference in your tool logic |
+
+→ `references/resources-and-prompts.md`, `references/elicitation.md`, `references/server-capabilities.md`
+
+---
+
+## Phase 6 — Test in Claude and publish
+
+Once the server runs:
+
+1. **Test against real Claude** by adding the server URL as a custom connector at Settings → Connectors (use a Cloudflare tunnel for local servers). Claude identifies itself with `clientInfo.name: "claude-ai"` on initialize. → https://claude.com/docs/connectors/building/testing
+2. **Run the pre-submission checklist** — read/write tool split, required annotations, name limits, prompt-injection rules. → https://claude.com/docs/connectors/building/review-criteria
+3. **Submit to the Anthropic Directory.** → https://claude.com/docs/connectors/building/submission
+4. **Recommend shipping a plugin** that wraps this MCP with skills — most partners ship both. → https://claude.com/docs/connectors/building/what-to-build
+
+---
+
+## Quick reference: decision matrix
+
+| Scenario | Deployment | Tool pattern |
+|---|---|---|
+| Wrap a small SaaS API | Remote HTTP | One-per-action |
+| Wrap a large SaaS API (50+ endpoints) | Remote HTTP | Search + execute |
+| SaaS API with rich forms / pickers | MCP app (remote) | One-per-action |
+| Drive a local desktop app | MCPB | One-per-action |
+| Local desktop app with in-chat UI | MCP app (MCPB) | One-per-action |
+| Read/write local filesystem | MCPB | Depends on surface |
+| Personal prototype | Local stdio | Whatever's fastest |
+
+---
+
+## Reference files
+
+- `references/remote-http-scaffold.md` — minimal remote server in TS SDK and FastMCP
+- `references/deploy-cloudflare-workers.md` — fastest deploy path (Workers-native scaffold)
+- `references/tool-design.md` — writing tool descriptions and schemas Claude understands well
+- `references/auth.md` — OAuth, CIMD, DCR, token storage patterns
+- `references/resources-and-prompts.md` — the two non-tool primitives
+- `references/elicitation.md` — spec-native user input mid-tool (capability check + fallback)
+- `references/server-capabilities.md` — instructions, sampling, roots, logging, progress, cancellation
+- `references/versions.md` — version-sensitive claims ledger (check when updating)