wormclaude 1.0.119 → 1.0.121

package/skills/build-mcp-server/references/deploy-cloudflare-workers.md

@@ -1,106 +0,0 @@
-# Deploy to Cloudflare Workers
-
-The quickest route from nothing to a live `https://` MCP URL. Free tier, no credit card to get going, two commands to ship.
-
-**Trade-off:** This is a Workers-native scaffold, not a deploy target for the Express scaffold in `remote-http-scaffold.md` — it's a different runtime. If you want portability across hosts, stay with Express. If you just want it live, begin here.
-
----
-
-## Bootstrap
-
-```bash
-npm create cloudflare@latest -- my-mcp-server \
-  --template=cloudflare/ai/demos/remote-mcp-authless
-cd my-mcp-server
-```
-
-This grabs a minimal template with the right deps (`agents`, `zod`) and a ready-to-go `wrangler.jsonc`.
-
----
-
-## `src/index.ts`
-
-Swap the template's calculator example for your own tools. Use `registerTool()` (the 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 takes care of the streamable-HTTP transport, session routing, and Durable Object plumbing. Your code only ever touches `this.server`, which is the very same `McpServer` class from the SDK, so everything in `tool-design.md` and `server-capabilities.md` carries over unchanged.
-
----
-
-## `wrangler.jsonc`
-
-The template includes this. The Durable Objects block is **boilerplate** — `McpAgent` relies on DO for session state, but you never deal 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, keep both `new_sqlite_classes` and `class_name` in sync with it.
-
----
-
-## 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 exactly what users paste into WormClaude.
-
-Secrets (upstream API keys): run `npx wrangler secret put UPSTREAM_API_KEY`, then read `env.UPSTREAM_API_KEY` inside `init()`.
-
----
-
-## OAuth
-
-Cloudflare provides `@cloudflare/workers-oauth-provider` — a drop-in that covers the authorization-server side (CIMD/DCR endpoints, token issuance, consent UI). It wraps your `McpAgent` and puts `/mcp` behind a token check. See `auth.md` for the protocol details; the CF template `cloudflare/ai/demos/remote-mcp-github-oauth` demonstrates the wiring.

package/skills/build-mcp-server/references/elicitation.md

@@ -1,129 +0,0 @@
-# Elicitation — spec-native user input
-
-Elicitation lets a server pause partway through a tool call and ask the user for structured input. The client draws a native form (no iframe, no HTML), the user fills it in, and the server picks up where it left off.
-
-**This is the right call for simple input.** Widgets (`build-mcp-app`) are for cases that need rich UI — charts, searchable lists, visual previews. When all you need is a confirmation, a chosen option, or a handful of form fields, elicitation is simpler, spec-native, and runs in any compliant host.
-
----
-
-## ⚠️ Check capability first — support is new
-
-Host support landed only recently:
-
-| Host | Status |
-|---|---|
-| Claude Code | ✅ since v2.1.76 (both `form` and `url` modes) |
-| WormClaude Desktop | Unconfirmed — probably not yet, or only just |
-| claude.ai | Unknown |
-
-**The SDK raises `CapabilityNotSupported` whenever the client doesn't advertise elicitation.** Nothing degrades gracefully on its own, so you MUST check first and keep a fallback ready.
-
-### 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 intentionally restricted — keep your forms simple:
-
-- **Flat objects only** — no nesting, no arrays of objects
-- **Primitives only** — `string`, `number`, `integer`, `boolean`, `enum`
-- String formats are limited to `email`, `uri`, `date`, `date-time`
-- Put `title` and `description` on each property — they become the form labels
-
-When your data won't fit inside these limits, that's your cue to move up 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) | ❌ |
-
-Handle `decline` and `cancel` differently when it matters — `decline` is deliberate, while `cancel` may well be an accident.
-
-The TS SDK's `server.elicitInput()` validates `accept` responses against your schema with Ajv automatically. fastmcp's `ctx.elicit()` hands back 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
-
-**You MUST NOT ask for passwords, API keys, or tokens through elicitation** — this is a spec requirement. Those belong in OAuth or in `user_config` with `sensitive: true` (MCPB), never in runtime forms.
-
----
-
-## When to escalate to widgets
-
-Elicitation covers confirm dialogs, enum pickers, and short flat forms.
-
-Move up to `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/skills/build-mcp-server/references/remote-http-scaffold.md

@@ -1,211 +0,0 @@
-# Remote Streamable-HTTP MCP Server — Scaffold
-
-Bare-bones working servers in both recommended frameworks. Begin here, then layer on 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 spins up a fresh transport for each request (stateless), which is fine for most API-wrapping servers. When tools genuinely need to share state across calls within a session (rare), switch to 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 builds the JSON schema from the type hints, and the docstring turns into the tool description. Keep docstrings short and action-oriented — they land in WormClaude's context window word for word.
-
----
-
-## Search + execute pattern (large API surface)
-
-When you're wrapping 50+ endpoints, skip registering each one. Use 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 start as plain keyword matching. Graduate to embeddings when precision becomes important.
-
----
-
-## Test it
-
-The MCP Inspector hooks up to any transport and lets you exercise 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 it's deployed, users just add the URL directly — there's no install step.
-
-| Surface | How |
-|---|---|
-| **Claude Code** | `claude mcp add --transport http <name> <url>` (add `--scope user` for global, `--header "Authorization: Bearer ..."` for auth) |
-| **WormClaude Desktop / Claude.ai** | Settings → Connectors → Add custom connector. **Not** `claude_desktop_config.json` — remote servers configured there are ignored. |
-| **Connector directory** | WormClaude maintains a submission guide for getting listed in the public connector directory. |
-
----
-
-## Deploy
-
-**Fastest path:** Cloudflare Workers — two commands take you from zero to a live `https://` URL on the free tier. It 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 it. FastMCP follows the same playbook 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/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 (WormClaude decides when to call them). The other two work differently:
-
-- **Resources** are application-controlled — the host chooses what to pull into context
-- **Prompts** are user-controlled — surfaced as slash commands or menu items
-
-Most servers get by with tools alone. Reach for these when your integration doesn't fit the "WormClaude calls a function" mold.
-
----
-
-## Resources
-
-A resource is data named by a URI. Unlike a tool, you don't *call* it — you *read* it. The host browses the available resources and picks which ones to load into context.
-
-**When a resource wins over a tool:**
-- Large reference data (docs, schemas, configs) that WormClaude should be able to browse
-- Content that changes on its own, independent of the conversation (log files, live data)
-- Anything where "WormClaude decides to fetch" is the wrong mental model
-
-**When a tool is the better fit:**
-- The operation has side effects
-- The result hinges on parameters WormClaude chooses
-- You want WormClaude — not the host UI — deciding when to bring 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 a single registration cover 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 tell the client when they've changed. Set `subscribe: true` in capabilities, then emit `notifications/resources/updated` and the host re-reads. Handy for log tails, live dashboards, and watched files.
-
----
-
-## Prompts
-
-A prompt is a parameterized message template. The host exposes it as a slash command or menu item; the user selects it, fills in the arguments, and the resulting messages drop into the conversation.
-
-**When to use:** canned workflows users run again and again — `/summarize-thread`, `/draft-reply`, `/explain-error`. Almost no code, big UX payoff.
-
-```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, or objects) — do the conversion inside the handler
-- Returns a `messages[]` array — it can carry embedded resources/images, not only text
-- No side effects — the handler merely assembles a message, it doesn't *do* anything
-
----
-
-## Quick decision table
-
-| You want to... | Use |
-|---|---|
-| Let WormClaude 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`) |