wormclaude 1.0.119 → 1.0.121

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

@@ -1,164 +0,0 @@
-# Server capabilities — the rest of the spec
-
-The features that sit beyond the three core primitives. Most are optional, and a few are practically free wins.
-
----
-
-## `instructions` — system prompt injection
-
-A single line of config that goes straight into WormClaude's system prompt. Use it for tool-use hints that don't belong in any one tool's description.
-
-```typescript
-const server = new McpServer(
-  { name: "my-server", version: "1.0.0" },
-  { instructions: "Always call search_items before get_item — IDs aren't guessable." },
-);
-```
-
-```python
-mcp = FastMCP("my-server", instructions="Always call search_items before get_item — IDs aren't guessable.")
-```
-
-This is the most leverage you'll get from a single line in the spec. When WormClaude keeps misusing your tools, this is where the fix goes.
-
----
-
-## Sampling — delegate LLM calls to the host
-
-When your tool logic needs LLM inference (summarize, classify, generate), don't bundle your own model client — ask the host to handle it.
-
-```typescript
-// Inside a tool handler
-const result = await extra.sendRequest({
-  method: "sampling/createMessage",
-  params: {
-    messages: [{ role: "user", content: { type: "text", text: `Summarize: ${doc}` } }],
-    maxTokens: 500,
-  },
-}, CreateMessageResultSchema);
-```
-
-```python
-# fastmcp
-response = await ctx.sample("Summarize this document", context=doc)
-```
-
-**Requires client support** — test `clientCapabilities.sampling` first. Model preference hints match by substring (`"claude-3-5"` matches any Claude 3.5 variant).
-
----
-
-## Roots — query workspace boundaries
-
-Rather than hardcoding a root directory, ask the host which directories the user has approved.
-
-```typescript
-const caps = server.getClientCapabilities();
-if (caps?.roots) {
-  const { roots } = await server.server.listRoots();
-  // roots: [{ uri: "file:///home/user/project", name: "My Project" }]
-}
-```
-
-```python
-roots = await ctx.list_roots()
-```
-
-Especially relevant for MCPB local servers — see `build-mcpb/references/local-security.md`.
-
----
-
-## Logging — structured, level-aware
-
-A better fit than stderr for remote servers, and the client can filter by level.
-
-```typescript
-// In a tool handler
-await extra.sendNotification({
-  method: "notifications/message",
-  params: { level: "info", logger: "my-tool", data: { msg: "Processing", count: 42 } },
-});
-```
-
-```python
-await ctx.info("Processing", count=42)   # also: ctx.debug, ctx.warning, ctx.error
-```
-
-Levels mirror syslog: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. The client picks the minimum via `logging/setLevel`.
-
----
-
-## Progress — for long-running tools
-
-The client sends a `progressToken` in the request `_meta`, and the server emits progress notifications against it.
-
-```typescript
-async (args, extra) => {
-  const token = extra._meta?.progressToken;
-  for (let i = 0; i < 100; i++) {
-    if (token !== undefined) {
-      await extra.sendNotification({
-        method: "notifications/progress",
-        params: { progressToken: token, progress: i, total: 100, message: `Step ${i}` },
-      });
-    }
-    await doStep(i);
-  }
-  return { content: [{ type: "text", text: "Done" }] };
-}
-```
-
-```python
-async def long_task(ctx: Context) -> str:
-    for i in range(100):
-        await ctx.report_progress(progress=i, total=100, message=f"Step {i}")
-        await do_step(i)
-    return "Done"
-```
-
----
-
-## Cancellation — honor the abort signal
-
-Long-running tools should watch the SDK-provided `AbortSignal`:
-
-```typescript
-async (args, extra) => {
-  for (const item of items) {
-    if (extra.signal.aborted) throw new Error("Cancelled");
-    await process(item);
-  }
-}
-```
-
-fastmcp manages this through asyncio cancellation — no explicit check is needed as long as your handler is properly async.
-
----
-
-## Completion — autocomplete for prompt args
-
-If you've registered prompts or resource templates that take arguments, you can also offer autocomplete:
-
-```typescript
-server.registerPrompt("query", {
-  argsSchema: {
-    table: completable(z.string(), async (partial) => tables.filter(t => t.startsWith(partial))),
-  },
-}, ...);
-```
-
-Low priority unless your prompts have a lot of valid values.
-
----
-
-## Which capabilities need client support?
-
-| Feature | Server declares | Client must support | Fallback if not |
-|---|---|---|---|
-| `instructions` | implicit | — | — (always works) |
-| Logging | `logging: {}` | — | stderr |
-| Progress | — | sends `progressToken` | silently skip |
-| Sampling | — | `sampling: {}` | bring your own LLM |
-| Elicitation | — | `elicitation: {}` | return text, ask WormClaude to relay |
-| Roots | — | `roots: {}` | config env var |
-
-Check client caps via `server.getClientCapabilities()` (TS) or `ctx.session.client_params.capabilities` (fastmcp) before using the bottom three.

package/skills/build-mcp-server/references/tool-design.md

@@ -1,189 +0,0 @@
-# Tool Design — Writing Tools WormClaude Uses Correctly
-
-Tool schemas and descriptions are a form of prompt engineering. They go straight into WormClaude's context and decide whether it reaches for the right tool with the right arguments. The majority of MCP integration bugs come back to vague descriptions or loose schemas.
-
-## WormClaude Directory hard requirements
-
-If you plan to submit this server to the WormClaude Directory, the items below are pass/fail review criteria (full list: https://claude.com/docs/connectors/building/review-criteria):
-
-- Every tool **must** carry `readOnlyHint`, `destructiveHint`, and `title` annotations — they drive auto-permissions in WormClaude.
-- Tool names **must** stay at or under 64 characters.
-- Reads and writes **must** live in separate tools. A single tool that accepts both GET and POST/PUT/PATCH/DELETE gets rejected — spelling out safe vs unsafe inside one tool's description is not enough.
-- Tool descriptions **must not** tell WormClaude how to behave (e.g. "always do X", "you must call Y first", overriding system instructions, pushing products) — reviewers treat this as prompt injection.
-- Tools that take freeform API endpoints or params **must** point to the target API's documentation in their description.
-
----
-
-## Descriptions
-
-**The description is the contract.** It's the only thing WormClaude looks at before deciding whether to call the tool. Write it like a one-line manpage entry, plus a few hints that disambiguate.
-
-### Good
-
-```
-search_issues — Search issues by keyword across title and body. Returns up
-to `limit` results ranked by recency. Does NOT search comments or PRs —
-use search_comments / search_prs for those.
-```
-
-- States what it does
-- States what it returns
-- States what it *won't* do (heads off wrong-tool calls)
-
-### Bad
-
-```
-search_issues — Searches for issues.
-```
-
-WormClaude will fire this off for anything vaguely search-shaped, including things it can't actually do.
-
-### Disambiguate siblings
-
-When two tools resemble each other, each description should point to when the *other* one is the right call:
-
-```
-get_user      — Fetch a user by ID. If you only have an email, use find_user_by_email.
-find_user_by_email — Look up a user by email address. Returns null if not found.
-```
-
----
-
-## Parameter schemas
-
-**Tight schemas head off bad calls.** Every constraint you bake into the schema is one less thing that can break at runtime.
-
-| Instead of | Use |
-|---|---|
-| `z.string()` for an ID | `z.string().regex(/^usr_[a-z0-9]{12}$/)` |
-| `z.number()` for a limit | `z.number().int().min(1).max(100).default(20)` |
-| `z.string()` for a choice | `z.enum(["open", "closed", "all"])` |
-| optional with no hint | `.optional().describe("Defaults to the caller's workspace")` |
-
-**Describe every parameter.** The `.describe()` text appears in the schema WormClaude sees. Skipping it is leaving value on the table.
-
-```typescript
-{
-  query: z.string().describe("Keywords to search for. Supports quoted phrases."),
-  status: z.enum(["open", "closed", "all"]).default("open")
-    .describe("Filter by status. Use 'all' to include closed items."),
-  limit: z.number().int().min(1).max(50).default(10)
-    .describe("Max results. Hard cap at 50."),
-}
-```
-
----
-
-## Return shapes
-
-WormClaude reads whatever lands in `content[].text`. Keep it parseable.
-
-**Do:**
-- Return JSON for structured data (`JSON.stringify(result, null, 2)`)
-- Return short confirmations for mutations (`"Created issue #123"`)
-- Include the IDs WormClaude will need for follow-up calls
-- Truncate oversized payloads and say so (`"Showing 10 of 847 results. Refine the query to narrow down."`)
-
-**Don't:**
-- Return raw HTML
-- Return megabytes of unfiltered API response
-- Return bare success with no identifier (`"ok"` after a create — WormClaude can't reference what it just made)
-
----
-
-## How many tools?
-
-| Tool count | Guidance |
-|---|---|
-| 1–15 | One tool per action. Sweet spot. |
-| 15–30 | Still workable. Audit for near-duplicates that could merge. |
-| 30+ | Switch to search + execute. Optionally promote the top 3–5 to dedicated tools. |
-
-The ceiling isn't a hard protocol limit — it's context-window economics. Every tool schema costs tokens that WormClaude pays *every turn*. Thirty tools with rich schemas can burn 3–5k tokens before the conversation has even begun.
-
----
-
-## Errors
-
-Return MCP tool errors rather than exceptions that take down the transport. Give enough detail for WormClaude to recover or retry a different way.
-
-```typescript
-if (!item) {
-  return {
-    isError: true,
-    content: [{
-      type: "text",
-      text: `Item ${id} not found. Use search_items to find valid IDs.`,
-    }],
-  };
-}
-```
-
-That hint ("use search_items…") turns a dead end into a next step.
-
----
-
-## Tool annotations
-
-Hints the host uses for UX — red confirm button for destructive, auto-approve for readonly. All default to unset (host assumes worst case).
-
-| Annotation | Meaning | Host behavior |
-|---|---|---|
-| `readOnlyHint: true` | No side effects | May auto-approve |
-| `destructiveHint: true` | Deletes/overwrites | Confirmation dialog |
-| `idempotentHint: true` | Safe to retry | May retry on transient error |
-| `openWorldHint: true` | Talks to external world (web, APIs) | May show network indicator |
-
-```typescript
-server.registerTool("delete_file", {
-  description: "Delete a file",
-  inputSchema: { path: z.string() },
-  annotations: { destructiveHint: true, idempotentHint: false },
-}, handler);
-```
-
-```python
-@mcp.tool(annotations={"destructiveHint": True, "idempotentHint": False})
-def delete_file(path: str) -> str:
-    ...
-```
-
-Pair with the read/write split advice in `build-mcpb/references/local-security.md` — mark every read tool `readOnlyHint: true`.
-
----
-
-## Structured output
-
-Dropping `JSON.stringify(result)` into a text block works, but the spec offers first-class typed output via `outputSchema` + `structuredContent`, which clients can validate against.
-
-```typescript
-server.registerTool("get_weather", {
-  description: "Get current weather",
-  inputSchema: { city: z.string() },
-  outputSchema: { temp: z.number(), conditions: z.string() },
-}, async ({ city }) => {
-  const data = await fetchWeather(city);
-  return {
-    content: [{ type: "text", text: JSON.stringify(data) }],  // backward compat
-    structuredContent: data,                                    // typed output
-  };
-});
-```
-
-Always keep the text fallback in place — not every host reads `structuredContent` yet.
-
----
-
-## Content types beyond text
-
-Tools can return more than strings:
-
-| Type | Shape | Use for |
-|---|---|---|
-| `text` | `{ type: "text", text: string }` | Default |
-| `image` | `{ type: "image", data: base64, mimeType }` | Screenshots, charts, diagrams |
-| `audio` | `{ type: "audio", data: base64, mimeType }` | TTS output, recordings |
-| `resource_link` | `{ type: "resource_link", uri, name?, description? }` | Pointer — client fetches later |
-| `resource` (embedded) | `{ type: "resource", resource: { uri, text\|blob, mimeType } }` | Inline the full content |
-
-**`resource_link` vs embedded:** link for large payloads or when the client might not need it (let them decide). Embed when it's small and always needed.

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

@@ -1,25 +0,0 @@
-# Version pins
-
-Every version-sensitive claim in this skill, in one place. When updating the skill, check these first.
-
-| Claim | Where stated | Last verified |
-|---|---|---|
-| `@modelcontextprotocol/ext-apps@1.2.2` CDN pin | `build-mcp-app/SKILL.md`, `build-mcp-app/references/widget-templates.md` (4×) | 2026-03 |
-| Claude Code ≥2.1.76 for elicitation | `elicitation.md:15`, `build-mcp-server/SKILL.md:43,76` | 2026-03 |
-| MCP spec 2025-11-25 CIMD/DCR status | `auth.md:20,24,41` | 2026-03 |
-| MCPB manifest schema v0.4 | `build-mcpb/references/manifest-schema.md` | 2026-03 |
-| CF `agents` SDK / `McpAgent` API | `deploy-cloudflare-workers.md` | 2026-03 |
-| CF template path `cloudflare/ai/demos/remote-mcp-authless` | `deploy-cloudflare-workers.md` | 2026-03 |
-
-## How to verify
-
-```bash
-# ext-apps latest
-npm view @modelcontextprotocol/ext-apps version
-
-# CF template still exists
-gh api repos/cloudflare/ai/contents/demos/remote-mcp-authless/src/index.ts --jq '.sha'
-
-# MCPB schema
-curl -sI https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json | head -1
-```

package/skills/build-mcpb/SKILL.md

@@ -1,200 +0,0 @@
----
-name: build-mcpb
-description: Reach for this skill when someone wants to "package an MCP server", "bundle an MCP", "make an MCPB", "ship a local MCP server", "distribute a local MCP", talks about ".mcpb files", mentions bundling a Node or Python runtime alongside their MCP server, or needs an MCP server that touches the local filesystem, desktop apps, or OS and has to install without the user having Node/Python set up.
-license: WormClaude
-version: 0.1.0
----
-
-# Build an MCPB (Bundled Local MCP Server)
-
-An MCPB is a local MCP server **shipped together with its runtime**. The user installs a single file and it runs without Node, Python, or any toolchain on their machine. It's the approved way to distribute local MCP servers.
-
-> MCPB is the **secondary** distribution path. WormClaude recommends remote MCP servers for directory listing — see https://claude.com/docs/connectors/building/what-to-build.
-
-**Use MCPB when the server genuinely has to run on the user's machine** — reading local files, driving a desktop app, talking to localhost services, OS-level APIs. If your server only calls cloud APIs, you almost certainly want a remote HTTP server instead (see `build-mcp-server`). Don't pay the MCPB packaging tax for something that could simply be a URL.
-
----
-
-## What an MCPB bundle contains
-
-```
-my-server.mcpb              (zip archive)
-├── manifest.json           ← identity, entry point, config schema, compatibility
-├── server/                 ← your MCP server code
-│   ├── index.js
-│   └── node_modules/       ← bundled dependencies (or vendored)
-└── icon.png
-```
-
-The host reads `manifest.json`, starts `server.mcp_config.command` as a **stdio** MCP server, and pipes messages back and forth. As far as your code is concerned it's exactly a local stdio server — the only thing that differs is the packaging.
-
----
-
-## Manifest
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
-  "manifest_version": "0.4",
-  "name": "local-files",
-  "version": "0.1.0",
-  "description": "Read, search, and watch files on the local filesystem.",
-  "author": { "name": "Your Name" },
-  "server": {
-    "type": "node",
-    "entry_point": "server/index.js",
-    "mcp_config": {
-      "command": "node",
-      "args": ["${__dirname}/server/index.js"],
-      "env": {
-        "ROOT_DIR": "${user_config.rootDir}"
-      }
-    }
-  },
-  "user_config": {
-    "rootDir": {
-      "type": "directory",
-      "title": "Root directory",
-      "description": "Directory to expose. Defaults to ~/Documents.",
-      "default": "${HOME}/Documents",
-      "required": true
-    }
-  },
-  "compatibility": {
-    "claude_desktop": ">=1.0.0",
-    "platforms": ["darwin", "win32", "linux"]
-  }
-}
-```
-
-**`server.type`** — `node`, `python`, or `binary`. Informational only; the actual launch is driven by `mcp_config`.
-
-**`server.mcp_config`** — the literal command/args/env used to spawn the process. Use `${__dirname}` for bundle-relative paths and `${user_config.<key>}` to drop in install-time config. **There's no auto-prefix** — the env var names your server reads are exactly the ones you write in `env`.
-
-**`user_config`** — install-time settings shown in the host's UI. `type: "directory"` draws a native folder picker; `sensitive: true` stashes the value in the OS keychain. See `references/manifest-schema.md` for the full field list.
-
----
-
-## Server code: same as local stdio
-
-The server itself is just a standard stdio MCP server — there's nothing MCPB-specific in the tool logic.
-
-```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-// ROOT_DIR comes from what you put in manifest's server.mcp_config.env — no auto-prefix
-const ROOT = (process.env.ROOT_DIR ?? join(homedir(), "Documents"));
-
-const server = new McpServer({ name: "local-files", version: "0.1.0" });
-
-server.registerTool(
-  "list_files",
-  {
-    description: "List files in a directory under the configured root.",
-    inputSchema: { path: z.string().default(".") },
-    annotations: { readOnlyHint: true },
-  },
-  async ({ path }) => {
-    const entries = await readdir(join(ROOT, path), { withFileTypes: true });
-    const list = entries.map(e => ({ name: e.name, dir: e.isDirectory() }));
-    return { content: [{ type: "text", text: JSON.stringify(list, null, 2) }] };
-  },
-);
-
-server.registerTool(
-  "read_file",
-  {
-    description: "Read a file's contents. Path is relative to the configured root.",
-    inputSchema: { path: z.string() },
-    annotations: { readOnlyHint: true },
-  },
-  async ({ path }) => {
-    const text = await readFile(join(ROOT, path), "utf8");
-    return { content: [{ type: "text", text }] };
-  },
-);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-```
-
-**Sandboxing is entirely on you.** There's no manifest-level sandbox — the process runs with full user privileges. Validate paths, refuse anything that escapes `ROOT`, and allowlist spawns. See `references/local-security.md`.
-
-Before you hardcode `ROOT` from a config env var, check whether the host supports `roots/list` — the spec-native way to obtain user-approved directories. See `references/local-security.md` for the pattern.
-
----
-
-## Build pipeline
-
-### Node
-
-```bash
-npm install
-npx esbuild src/index.ts --bundle --platform=node --outfile=server/index.js
-# or: copy node_modules wholesale if native deps resist bundling
-npx @anthropic-ai/mcpb pack
-```
-
-`mcpb pack` zips up the directory and checks `manifest.json` against the schema.
-
-### Python
-
-```bash
-pip install -t server/vendor -r requirements.txt
-npx @anthropic-ai/mcpb pack
-```
-
-Vendor your dependencies into a subdirectory and prepend it to `sys.path` in the entry script. Native extensions (numpy and friends) have to be built per target platform — steer clear of native deps where you can.
-
----
-
-## MCPB has no sandbox — security is on you
-
-Unlike mobile app stores, MCPB does NOT enforce permissions. The manifest has no `permissions` block — the server runs with full user privileges. `references/local-security.md` is required reading, not optional. Every path has to be validated and every spawn allowlisted, because nothing stops you at the platform level.
-
-If you arrived expecting the manifest to give you filesystem/network scoping: it doesn't exist. You build that yourself inside the tool handlers.
-
-If your server's only job is calling a cloud API, stop — that's a remote server in an MCPB costume. The user gains nothing from running it locally, and you've taken on the local-security burden for no reason.
-
----
-
-## MCPB + UI widgets
-
-MCPB servers can serve UI resources just like remote MCP apps — the widget mechanism doesn't care about the transport. Think a local file picker that browses the real disk, or a dialog that controls a native app.
-
-Widget authoring lives in the **`build-mcp-app`** skill and works identically here. The only thing that changes is where the server runs.
-
----
-
-## Testing
-
-```bash
-# Interactive manifest creation (first time)
-npx @anthropic-ai/mcpb init
-
-# Run the server directly over stdio, poke it with the inspector
-npx @modelcontextprotocol/inspector node server/index.js
-
-# Validate manifest against schema, then pack
-npx @anthropic-ai/mcpb validate
-npx @anthropic-ai/mcpb pack
-
-# Sign for distribution
-npx @anthropic-ai/mcpb sign dist/local-files.mcpb
-
-# Install: drag the .mcpb file onto Claude Desktop
-```
-
-Test on a machine that **lacks** your dev toolchain before you ship. "Works on my machine" failures in MCPB nearly always come down to a dependency that never actually got bundled.
-
----
-
-## Reference files
-
-- `references/manifest-schema.md` — full `manifest.json` field reference
-- `references/local-security.md` — path traversal, sandboxing, least privilege