winter-super-cli 2026.5.25 → 2026.5.27

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

@@ -1,106 +0,0 @@
-# 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

@@ -1,129 +0,0 @@
-# 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

@@ -1,211 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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`) |