winter-super-cli 2026.6.22 → 2026.6.23

package/resources/local/claude/plugins/marketplaces/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-server/references/deploy-cloudflare-workers.md

@@ -0,0 +1,106 @@
+# Deploy to Cloudflare Workers
+
+Fastest path from zero to a live `https://` MCP URL. Free tier, no credit card to start, two commands to deploy.
+
+**Trade-off:** This is a Workers-native scaffold, not a deploy target for the Express scaffold in `remote-http-scaffold.md`. Different runtime. If you need portability across hosts, stick with Express. If you just want it live, start here.
+
+---
+
+## Bootstrap
+
+```bash
+npm create cloudflare@latest -- my-mcp-server \
+  --template=cloudflare/ai/demos/remote-mcp-authless
+cd my-mcp-server
+```
+
+This pulls a minimal template with the right deps (`agents`, `zod`) and a working `wrangler.jsonc`.
+
+---
+
+## `src/index.ts`
+
+Replace the template's calculator example with your tools. Use `registerTool()` (same API as the Express scaffold — the `McpServer` instance is identical):
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpAgent } from "agents/mcp";
+import { z } from "zod";
+
+export class MyMCP extends McpAgent {
+  server = new McpServer(
+    { name: "my-service", version: "0.1.0" },
+    { instructions: "Prefer search_items before get_item — IDs aren't guessable." },
+  );
+
+  async init() {
+    this.server.registerTool(
+      "search_items",
+      {
+        description: "Search items by keyword. Returns up to `limit` matches.",
+        inputSchema: {
+          query: z.string().describe("Search keywords"),
+          limit: z.number().int().min(1).max(50).default(10),
+        },
+        annotations: { readOnlyHint: true },
+      },
+      async ({ query, limit }) => {
+        const results = await upstreamApi.search(query, limit);
+        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+      },
+    );
+  }
+}
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const url = new URL(request.url);
+    if (url.pathname === "/mcp") {
+      return MyMCP.serve("/mcp").fetch(request, env, ctx);
+    }
+    return new Response("Not found", { status: 404 });
+  },
+};
+```
+
+`McpAgent` is Cloudflare's wrapper — it handles the streamable-HTTP transport, session routing, and Durable Object plumbing. Your code only touches `this.server`, which is the same `McpServer` class from the SDK. Everything in `tool-design.md` and `server-capabilities.md` applies unchanged.
+
+---
+
+## `wrangler.jsonc`
+
+The template ships this. The Durable Objects block is **boilerplate** — `McpAgent` uses DO for session state. You don't interact with it directly.
+
+```jsonc
+{
+  "name": "my-mcp-server",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-03-10",
+  "compatibility_flags": ["nodejs_compat"],
+  "migrations": [{ "new_sqlite_classes": ["MyMCP"], "tag": "v1" }],
+  "durable_objects": {
+    "bindings": [{ "class_name": "MyMCP", "name": "MCP_OBJECT" }]
+  }
+}
+```
+
+If you rename the `MyMCP` class, update both `new_sqlite_classes` and `class_name` to match.
+
+---
+
+## Run and deploy
+
+```bash
+npx wrangler dev     # → http://localhost:8787/mcp
+npx wrangler deploy  # → https://my-mcp-server.<account>.workers.dev/mcp
+```
+
+`wrangler deploy` prints the live URL. That's the URL users paste into Claude.
+
+Secrets (upstream API keys): `npx wrangler secret put UPSTREAM_API_KEY`, then read `env.UPSTREAM_API_KEY` inside `init()`.
+
+---
+
+## OAuth
+
+Cloudflare ships `@cloudflare/workers-oauth-provider` — a drop-in that handles the authorization server side (CIMD/DCR endpoints, token issuance, consent UI). It wraps your `McpAgent` and gates `/mcp` behind a token check. See `auth.md` for the protocol details; the CF template `cloudflare/ai/demos/remote-mcp-github-oauth` shows the wiring.

package/resources/local/claude/plugins/marketplaces/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-server/references/elicitation.md

@@ -0,0 +1,129 @@
+# Elicitation — spec-native user input
+
+Elicitation lets a server pause mid-tool-call and ask the user for structured input. The client renders a native form (no iframe, no HTML). User fills it, server continues.
+
+**This is the right answer for simple input.** Widgets (`build-mcp-app`) are for when you need rich UI — charts, searchable lists, visual previews. If you just need a confirmation, a picked option, or a few form fields, elicitation is simpler, spec-native, and works in any compliant host.
+
+---
+
+## ⚠️ Check capability first — support is new
+
+Host support is very recent:
+
+| Host | Status |
+|---|---|
+| Claude Code | ✅ since v2.1.76 (both `form` and `url` modes) |
+| Claude Desktop | Unconfirmed — likely not yet or very recent |
+| claude.ai | Unknown |
+
+**The SDK throws `CapabilityNotSupported` if the client doesn't advertise elicitation.** There is no graceful degradation built in. You MUST check and have a fallback.
+
+### The canonical pattern
+
+```typescript
+server.registerTool("delete_all", {
+  description: "Delete all items after confirmation",
+  inputSchema: {},
+}, async ({}, extra) => {
+  const caps = server.getClientCapabilities();
+  if (caps?.elicitation) {
+    const r = await server.elicitInput({
+      mode: "form",
+      message: "Delete all items? This cannot be undone.",
+      requestedSchema: {
+        type: "object",
+        properties: { confirm: { type: "boolean", title: "Confirm deletion" } },
+        required: ["confirm"],
+      },
+    });
+    if (r.action === "accept" && r.content?.confirm) {
+      await deleteAll();
+      return { content: [{ type: "text", text: "Deleted." }] };
+    }
+    return { content: [{ type: "text", text: "Cancelled." }] };
+  }
+  // Fallback: return text asking Claude to relay the question
+  return { content: [{ type: "text", text: "Confirmation required. Please ask the user: 'Delete all items? This cannot be undone.' Then call this tool again with their answer." }] };
+});
+```
+
+```python
+# fastmcp
+from fastmcp import Context
+from fastmcp.exceptions import CapabilityNotSupported
+
+@mcp.tool
+async def delete_all(ctx: Context) -> str:
+    try:
+        result = await ctx.elicit("Delete all items? This cannot be undone.", response_type=bool)
+        if result.action == "accept" and result.data:
+            await do_delete()
+            return "Deleted."
+        return "Cancelled."
+    except CapabilityNotSupported:
+        return "Confirmation required. Ask the user to confirm deletion, then retry."
+```
+
+---
+
+## Schema constraints
+
+Elicitation schemas are deliberately limited — keep forms simple:
+
+- **Flat objects only** — no nesting, no arrays of objects
+- **Primitives only** — `string`, `number`, `integer`, `boolean`, `enum`
+- String formats limited to: `email`, `uri`, `date`, `date-time`
+- Use `title` and `description` on each property — they become form labels
+
+If your data doesn't fit these constraints, that's the signal to escalate to a widget.
+
+---
+
+## Three-state response
+
+| Action | Meaning | `content` present? |
+|---|---|---|
+| `accept` | User submitted the form | ✅ validated against your schema |
+| `decline` | User explicitly said no | ❌ |
+| `cancel` | User dismissed (escape, clicked away) | ❌ |
+
+Treat `decline` and `cancel` differently if it matters — `decline` is intentional, `cancel` might be accidental.
+
+The TS SDK's `server.elicitInput()` auto-validates `accept` responses against your schema via Ajv. fastmcp's `ctx.elicit()` returns a typed discriminated union (`AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation`).
+
+---
+
+## fastmcp response_type shorthand
+
+```python
+await ctx.elicit("Pick a color", response_type=["red", "green", "blue"])  # enum
+await ctx.elicit("Enter email", response_type=str)                         # string
+await ctx.elicit("Confirm?", response_type=bool)                           # boolean
+
+@dataclass
+class ContactInfo:
+    name: str
+    email: str
+await ctx.elicit("Contact details", response_type=ContactInfo)             # flat dataclass
+```
+
+Accepts: primitives, `list[str]` (becomes enum), dataclass, TypedDict, Pydantic BaseModel. All must be flat.
+
+---
+
+## Security
+
+**MUST NOT request passwords, API keys, or tokens via elicitation** — spec requirement. Those go through OAuth or `user_config` with `sensitive: true` (MCPB), not runtime forms.
+
+---
+
+## When to escalate to widgets
+
+Elicitation handles: confirm dialogs, enum pickers, short flat forms.
+
+Reach for `build-mcp-app` widgets when you need:
+- Nested or complex data structures
+- Scrollable/searchable lists (100+ items)
+- Visual preview before choosing (image thumbnails, file tree)
+- Live-updating progress or streaming content
+- Custom layouts, charts, maps

package/resources/local/claude/plugins/marketplaces/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-server/references/remote-http-scaffold.md

@@ -0,0 +1,211 @@
+# Remote Streamable-HTTP MCP Server — Scaffold
+
+Minimal working servers in both recommended frameworks. Start here, then add tools.
+
+---
+
+## TypeScript SDK (`@modelcontextprotocol/sdk`)
+
+```bash
+npm init -y
+npm install @modelcontextprotocol/sdk zod express
+npm install -D typescript @types/express @types/node tsx
+```
+
+**`src/server.ts`**
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { z } from "zod";
+
+const server = new McpServer(
+  { name: "my-service", version: "0.1.0" },
+  { instructions: "Prefer search_items before calling get_item directly — IDs aren't guessable." },
+);
+
+// Pattern A: one tool per action
+server.registerTool(
+  "search_items",
+  {
+    description: "Search items by keyword. Returns up to `limit` matches ranked by relevance.",
+    inputSchema: {
+      query: z.string().describe("Search keywords"),
+      limit: z.number().int().min(1).max(50).default(10),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ query, limit }, extra) => {
+    // extra.signal is an AbortSignal — check it in long loops for cancellation
+    const results = await upstreamApi.search(query, limit);
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_item",
+  {
+    description: "Fetch a single item by its ID.",
+    inputSchema: { id: z.string() },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ id }) => {
+    const item = await upstreamApi.get(id);
+    return { content: [{ type: "text", text: JSON.stringify(item) }] };
+  },
+);
+
+// Streamable HTTP transport (stateless mode — simplest)
+const app = express();
+app.use(express.json());
+
+app.post("/mcp", async (req, res) => {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined, // stateless
+  });
+  res.on("close", () => transport.close());
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+
+app.listen(process.env.PORT ?? 3000);
+```
+
+**Stateless vs stateful:** The snippet above creates a fresh transport per request (stateless). Fine for most API-wrapping servers. If tools need to share state across calls in a session (rare), use a session-keyed transport map — see the SDK's `examples/server/simpleStreamableHttp.ts`.
+
+---
+
+## FastMCP 3.x (Python)
+
+```bash
+pip install fastmcp
+```
+
+**`server.py`**
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="my-service",
+    instructions="Prefer search_items before calling get_item directly — IDs aren't guessable.",
+)
+
+@mcp.tool(annotations={"readOnlyHint": True})
+def search_items(query: str, limit: int = 10) -> list[dict]:
+    """Search items by keyword. Returns up to `limit` matches ranked by relevance."""
+    return upstream_api.search(query, limit)
+
+@mcp.tool(annotations={"readOnlyHint": True})
+def get_item(id: str) -> dict:
+    """Fetch a single item by its ID."""
+    return upstream_api.get(id)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", host="0.0.0.0", port=3000)
+```
+
+FastMCP derives the JSON schema from type hints and the docstring becomes the tool description. Keep docstrings terse and action-oriented — they land in Claude's context window verbatim.
+
+---
+
+## Search + execute pattern (large API surface)
+
+When wrapping 50+ endpoints, don't register them all. Two tools:
+
+```typescript
+const CATALOG = loadActionCatalog(); // { id, description, paramSchema }[]
+
+server.registerTool(
+  "search_actions",
+  {
+    description: "Find available actions matching an intent. Call this first to discover what's possible. Returns action IDs, descriptions, and parameter schemas.",
+    inputSchema: { intent: z.string().describe("What you want to do, in plain English") },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ intent }) => {
+    const matches = rankActions(CATALOG, intent).slice(0, 10);
+    return { content: [{ type: "text", text: JSON.stringify(matches, null, 2) }] };
+  },
+);
+
+server.registerTool(
+  "execute_action",
+  {
+    description: "Execute an action by ID. Get the ID and params schema from search_actions first.",
+    inputSchema: {
+      action_id: z.string(),
+      params: z.record(z.unknown()),
+    },
+  },
+  async ({ action_id, params }) => {
+    const action = CATALOG.find(a => a.id === action_id);
+    if (!action) throw new Error(`Unknown action: ${action_id}`);
+    validate(params, action.paramSchema);
+    const result = await dispatch(action, params);
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  },
+);
+```
+
+`rankActions` can be simple keyword matching to start. Upgrade to embeddings if precision matters.
+
+---
+
+## Test it
+
+The MCP Inspector connects to any transport and lets you poke tools interactively.
+
+```bash
+# Interactive — opens a UI on localhost:6274
+npx @modelcontextprotocol/inspector
+# → select "Streamable HTTP", paste http://localhost:3000/mcp, Connect
+```
+
+For scripted checks (CI, smoke tests):
+
+```bash
+npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp \
+  --transport http --method tools/list
+
+npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp \
+  --transport http --method tools/call --tool-name search_items --tool-arg query=test
+```
+
+---
+
+## Connect users
+
+Once deployed, users add the URL directly — no install step.
+
+| Surface | How |
+|---|---|
+| **Claude Code** | `claude mcp add --transport http <name> <url>` (add `--scope user` for global, `--header "Authorization: Bearer ..."` for auth) |
+| **Claude Desktop / Claude.ai** | Settings → Connectors → Add custom connector. **Not** `claude_desktop_config.json` — remote servers configured there are ignored. |
+| **Connector directory** | Anthropic maintains a submission guide for listing in the public connector directory. |
+
+---
+
+## Deploy
+
+**Fastest path:** Cloudflare Workers — two commands from zero to a live `https://` URL on the free tier. Uses a Workers-native scaffold (not Express). → `deploy-cloudflare-workers.md`
+
+**This Express scaffold** runs on any Node host — Render, Railway, Fly.io, a VPS. Containerize it (`node:20-slim`, copy, `npm ci`, `node dist/server.js`) and ship. FastMCP is the same story with a Python base image.
+
+---
+
+## Deployment checklist
+
+- [ ] `POST /mcp` responds to `initialize` with server capabilities
+- [ ] `tools/list` returns your tools with complete schemas
+- [ ] Errors return structured MCP errors, not HTTP 500s with HTML bodies
+- [ ] CORS headers set if browser clients will connect
+- [ ] `Origin` header validated on `/mcp` (spec MUST — DNS rebinding prevention)
+- [ ] `MCP-Protocol-Version` header honored (return 400 for unsupported versions)
+- [ ] `instructions` field set if tool-use needs hints
+- [ ] Health check endpoint separate from `/mcp` (hosts poll it)
+- [ ] Secrets from env vars, never hardcoded
+- [ ] If OAuth: CIMD or DCR endpoint implemented — see `auth.md`

package/resources/local/claude/plugins/marketplaces/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-server/references/resources-and-prompts.md

@@ -0,0 +1,122 @@
+# Resources & Prompts — the other two primitives
+
+MCP defines three server-side primitives. Tools are model-controlled (Claude decides when to call them). The other two are different:
+
+- **Resources** are application-controlled — the host decides what to pull into context
+- **Prompts** are user-controlled — surfaced as slash commands or menu items
+
+Most servers only need tools. Reach for these when the shape of your integration doesn't fit "Claude calls a function."
+
+---
+
+## Resources
+
+A resource is data identified by a URI. Unlike a tool, it's not *called* — it's *read*. The host browses available resources and decides which to load into context.
+
+**When a resource beats a tool:**
+- Large reference data (docs, schemas, configs) that Claude should be able to browse
+- Content that changes independently of conversation (log files, live data)
+- Anything where "Claude decides to fetch" is the wrong mental model
+
+**When a tool is better:**
+- The operation has side effects
+- The result depends on parameters Claude chooses
+- You want Claude (not the host UI) to decide when to pull it in
+
+### Static resources
+
+```typescript
+// TypeScript SDK
+server.registerResource(
+  "config",
+  "config://app/settings",
+  { name: "App Settings", description: "Current configuration", mimeType: "application/json" },
+  async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(config) }],
+  }),
+);
+```
+
+```python
+# fastmcp
+@mcp.resource("config://app/settings")
+def get_settings() -> str:
+    """Current application configuration."""
+    return json.dumps(config)
+```
+
+### Dynamic resources (URI templates)
+
+RFC 6570 templates let one registration serve many URIs:
+
+```typescript
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+server.registerResource(
+  "file",
+  new ResourceTemplate("file:///{path}", { list: undefined }),
+  { name: "File", description: "Read a file from the workspace" },
+  async (uri, { path }) => ({
+    contents: [{ uri: uri.href, text: await fs.readFile(path, "utf8") }],
+  }),
+);
+```
+
+```python
+@mcp.resource("file:///{path}")
+def read_file(path: str) -> str:
+    return Path(path).read_text()
+```
+
+### Subscriptions
+
+Resources can notify the client when they change. Declare `subscribe: true` in capabilities, then emit `notifications/resources/updated`. The host re-reads. Useful for log tails, live dashboards, watched files.
+
+---
+
+## Prompts
+
+A prompt is a parameterized message template. The host surfaces it as a slash command or menu item. The user picks it, fills in arguments, and the resulting messages land in the conversation.
+
+**When to use:** canned workflows users run repeatedly — `/summarize-thread`, `/draft-reply`, `/explain-error`. Near-zero code, high UX leverage.
+
+```typescript
+server.registerPrompt(
+  "summarize",
+  {
+    title: "Summarize document",
+    description: "Generate a concise summary of the given text",
+    argsSchema: { text: z.string(), max_words: z.string().optional() },
+  },
+  ({ text, max_words }) => ({
+    messages: [{
+      role: "user",
+      content: { type: "text", text: `Summarize in ${max_words ?? "100"} words:\n\n${text}` },
+    }],
+  }),
+);
+```
+
+```python
+@mcp.prompt
+def summarize(text: str, max_words: str = "100") -> str:
+    """Generate a concise summary of the given text."""
+    return f"Summarize in {max_words} words:\n\n{text}"
+```
+
+**Constraints:**
+- Arguments are **string-only** (no numbers, booleans, objects) — convert inside the handler
+- Returns a `messages[]` array — can include embedded resources/images, not just text
+- No side effects — the handler just builds a message, it doesn't *do* anything
+
+---
+
+## Quick decision table
+
+| You want to... | Use |
+|---|---|
+| Let Claude fetch something on demand, with parameters | **Tool** |
+| Expose browsable context (files, docs, schemas) | **Resource** |
+| Expose a dynamic family of things (`db://{table}`) | **Resource template** |
+| Give users a one-click workflow | **Prompt** |
+| Ask the user something mid-tool | **Elicitation** (see `elicitation.md`) |