shmakk 1.1.0 → 1.2.0

package/skills/backend-build-mcpb.md

@@ -0,0 +1,200 @@
+---
+name: build-mcpb
+description: This skill should be used when the user wants to "package an MCP server", "bundle an MCP", "make an MCPB", "ship a local MCP server", "distribute a local MCP", discusses ".mcpb files", mentions bundling a Node or Python runtime with their MCP server, or needs an MCP server that interacts with the local filesystem, desktop apps, or OS and must be installable without the user having Node/Python set up.
+version: 0.1.0
+category: backend
+---
+
+# Build an MCPB (Bundled Local MCP Server)
+
+MCPB is a local MCP server **packaged with its runtime**. The user installs one file; it runs without needing Node, Python, or any toolchain on their machine. It's the sanctioned way to distribute local MCP servers.
+
+> MCPB is the **secondary** distribution path. Anthropic recommends remote MCP servers for directory listing — see https://claude.com/docs/connectors/building/what-to-build.
+
+**Use MCPB when the server must run on the user's machine** — reading local files, driving a desktop app, talking to localhost services, OS-level APIs. If your server only hits 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 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`, launches `server.mcp_config.command` as a **stdio** MCP server, and pipes messages. From your code's perspective it's identical to a local stdio server — the only difference is 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; the actual launch comes from `mcp_config`.
+
+**`server.mcp_config`** — the literal command/args/env to spawn. Use `${__dirname}` for bundle-relative paths and `${user_config.<key>}` to substitute install-time config. **There's no auto-prefix** — the env var names your server reads are exactly what you put in `env`.
+
+**`user_config`** — install-time settings surfaced in the host's UI. `type: "directory"` renders a native folder picker. `sensitive: true` stores in OS keychain. See `references/manifest-schema.md` for all fields.
+
+---
+
+## Server code: same as local stdio
+
+The server itself is a standard stdio MCP server. 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 your job.** There is no manifest-level sandbox — the process runs with full user privileges. Validate paths, refuse to escape `ROOT`, allowlist spawns. See `references/local-security.md`.
+
+Before hardcoding `ROOT` from a config env var, check if the host supports `roots/list` — the spec-native way to get 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 the directory and validates `manifest.json` against the schema.
+
+### Python
+
+```bash
+pip install -t server/vendor -r requirements.txt
+npx @anthropic-ai/mcpb pack
+```
+
+Vendor dependencies into a subdirectory and prepend it to `sys.path` in your entry script. Native extensions (numpy, etc.) must be built for each target platform — avoid native deps if 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 mandatory reading, not optional. Every path must be validated, every spawn must be allowlisted, because nothing stops you at the platform level.
+
+If you came here expecting filesystem/network scoping from the manifest: it doesn't exist. Build it yourself in tool handlers.
+
+If your server's only job is hitting a cloud API, stop — that's a remote server wearing an MCPB costume. The user gains nothing from running it locally, and you're taking on local-security burden for no reason.
+
+---
+
+## MCPB + UI widgets
+
+MCPB servers can serve UI resources exactly like remote MCP apps — the widget mechanism is transport-agnostic. A local file picker that browses the actual disk, a dialog that controls a native app, etc.
+
+Widget authoring is covered in the **`build-mcp-app`** skill; it works the same here. The only difference 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 **without** your dev toolchain before shipping. "Works on my machine" failures in MCPB almost always trace to a dependency that wasn't actually bundled.
+
+---
+
+## Reference files
+
+- `references/manifest-schema.md` — full `manifest.json` field reference
+- `references/local-security.md` — path traversal, sandboxing, least privilege

package/skills/backend-building-ai-agent-on-cloudflare.md

@@ -0,0 +1,401 @@
+---
+name: building-ai-agent-on-cloudflare
+description: |
+  Builds AI agents on Cloudflare using the Agents SDK with state management,
+  real-time WebSockets, scheduled tasks, tool integration, and chat capabilities.
+  Generates production-ready agent code deployed to Workers.
+
+  Use when: user wants to "build an agent", "AI agent", "chat agent", "stateful
+  agent", mentions "Agents SDK", needs "real-time AI", "WebSocket AI", or asks
+  about agent "state management", "scheduled tasks", or "tool calling".
+  Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+category: backend
+---
+
+# Building Cloudflare Agents
+
+Your knowledge of the Agents SDK may be outdated. **Prefer retrieval over pre-training** for any agent-building task.
+
+## Retrieval Sources
+
+| Source | How to retrieve | Use for |
+|--------|----------------|---------|
+| Agents SDK docs | `https://github.com/cloudflare/agents/tree/main/docs` | SDK API, state, routing, scheduling |
+| Cloudflare Agents docs | `https://developers.cloudflare.com/agents/` | Platform integration, deployment |
+| Workers docs | Search tool or `https://developers.cloudflare.com/workers/` | Runtime APIs, bindings, config |
+
+## When to Use
+
+- User wants to build an AI agent or chatbot
+- User needs stateful, real-time AI interactions
+- User asks about the Cloudflare Agents SDK
+- User wants scheduled tasks or background AI work
+- User needs WebSocket-based AI communication
+
+## Prerequisites
+
+- Cloudflare account with Workers enabled
+- Node.js 18+ and npm/pnpm/yarn
+- Wrangler CLI (`npm install -g wrangler`)
+
+## Quick Start
+
+```bash
+npm create cloudflare@latest -- my-agent --template=cloudflare/agents-starter
+cd my-agent
+npm start
+```
+
+Agent runs at `http://localhost:8787`
+
+## Core Concepts
+
+### What is an Agent?
+
+An Agent is a stateful, persistent AI service that:
+- Maintains state across requests and reconnections
+- Communicates via WebSockets or HTTP
+- Runs on Cloudflare's edge via Durable Objects
+- Can schedule tasks and call tools
+- Scales horizontally (each user/session gets own instance)
+
+### Agent Lifecycle
+
+```
+Client connects → Agent.onConnect() → Agent processes messages
+                                    → Agent.onMessage()
+                                    → Agent.setState() (persists + syncs)
+Client disconnects → State persists → Client reconnects → State restored
+```
+
+## Basic Agent Structure
+
+```typescript
+import { Agent, Connection } from "agents";
+
+interface Env {
+  AI: Ai;  // Workers AI binding
+}
+
+interface State {
+  messages: Array<{ role: string; content: string }>;
+  preferences: Record<string, string>;
+}
+
+export class MyAgent extends Agent<Env, State> {
+  // Initial state for new instances
+  initialState: State = {
+    messages: [],
+    preferences: {},
+  };
+
+  // Called when agent starts or resumes
+  async onStart() {
+    console.log("Agent started with state:", this.state);
+  }
+
+  // Handle WebSocket connections
+  async onConnect(connection: Connection) {
+    connection.send(JSON.stringify({
+      type: "welcome",
+      history: this.state.messages,
+    }));
+  }
+
+  // Handle incoming messages
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "chat") {
+      await this.handleChat(connection, data.content);
+    }
+  }
+
+  // Handle disconnections
+  async onClose(connection: Connection) {
+    console.log("Client disconnected");
+  }
+
+  // React to state changes
+  onStateUpdate(state: State, source: string) {
+    console.log("State updated by:", source);
+  }
+
+  private async handleChat(connection: Connection, userMessage: string) {
+    // Add user message to history
+    const messages = [
+      ...this.state.messages,
+      { role: "user", content: userMessage },
+    ];
+
+    // Call AI
+    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+      messages,
+    });
+
+    // Update state (persists and syncs to all clients)
+    this.setState({
+      ...this.state,
+      messages: [
+        ...messages,
+        { role: "assistant", content: response.response },
+      ],
+    });
+
+    // Send response
+    connection.send(JSON.stringify({
+      type: "response",
+      content: response.response,
+    }));
+  }
+}
+```
+
+## Entry Point Configuration
+
+```typescript
+// src/index.ts
+import { routeAgentRequest } from "agents";
+import { MyAgent } from "./agent";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // routeAgentRequest handles routing to /agents/:class/:name
+    return (
+      (await routeAgentRequest(request, env)) ||
+      new Response("Not found", { status: 404 })
+    );
+  },
+};
+
+export { MyAgent };
+```
+
+Clients connect via: `wss://my-agent.workers.dev/agents/MyAgent/session-id`
+
+## Wrangler Configuration
+
+```toml
+name = "my-agent"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+
+[ai]
+binding = "AI"
+
+[durable_objects]
+bindings = [{ name = "AGENT", class_name = "MyAgent" }]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["MyAgent"]
+```
+
+## State Management
+
+### Reading State
+
+```typescript
+// Current state is always available
+const currentMessages = this.state.messages;
+const userPrefs = this.state.preferences;
+```
+
+### Updating State
+
+```typescript
+// setState persists AND syncs to all connected clients
+this.setState({
+  ...this.state,
+  messages: [...this.state.messages, newMessage],
+});
+
+// Partial updates work too
+this.setState({
+  preferences: { ...this.state.preferences, theme: "dark" },
+});
+```
+
+### SQL Storage
+
+For complex queries, use the embedded SQLite database:
+
+```typescript
+// Create tables
+await this.sql`
+  CREATE TABLE IF NOT EXISTS documents (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    content TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )
+`;
+
+// Insert
+await this.sql`
+  INSERT INTO documents (title, content)
+  VALUES (${title}, ${content})
+`;
+
+// Query
+const docs = await this.sql`
+  SELECT * FROM documents WHERE title LIKE ${`%${search}%`}
+`;
+```
+
+## Scheduled Tasks
+
+Agents can schedule future work:
+
+```typescript
+async onMessage(connection: Connection, message: string) {
+  const data = JSON.parse(message);
+
+  if (data.type === "schedule_reminder") {
+    // Schedule task for 1 hour from now
+    const { id } = await this.schedule(3600, "sendReminder", {
+      message: data.reminderText,
+      userId: data.userId,
+    });
+
+    connection.send(JSON.stringify({ type: "scheduled", taskId: id }));
+  }
+}
+
+// Called when scheduled task fires
+async sendReminder(data: { message: string; userId: string }) {
+  // Send notification, email, etc.
+  console.log(`Reminder for ${data.userId}: ${data.message}`);
+
+  // Can also update state
+  this.setState({
+    ...this.state,
+    lastReminder: new Date().toISOString(),
+  });
+}
+```
+
+### Schedule Options
+
+```typescript
+// Delay in seconds
+await this.schedule(60, "taskMethod", { data });
+
+// Specific date
+await this.schedule(new Date("2025-01-01T00:00:00Z"), "taskMethod", { data });
+
+// Cron expression (recurring)
+await this.schedule("0 9 * * *", "dailyTask", {});  // 9 AM daily
+await this.schedule("*/5 * * * *", "everyFiveMinutes", {});  // Every 5 min
+
+// Manage schedules
+const schedules = await this.getSchedules();
+await this.cancelSchedule(taskId);
+```
+
+## Chat Agent (AI-Powered)
+
+For chat-focused agents, extend `AIChatAgent`:
+
+```typescript
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+export class ChatBot extends AIChatAgent<Env> {
+  // Called for each user message
+  async onChatMessage(message: string) {
+    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+      messages: [
+        { role: "system", content: "You are a helpful assistant." },
+        ...this.messages,  // Automatic history management
+        { role: "user", content: message },
+      ],
+      stream: true,
+    });
+
+    // Stream response back to client
+    return response;
+  }
+}
+```
+
+Features included:
+- Automatic message history
+- Resumable streaming (survives disconnects)
+- Built-in `saveMessages()` for persistence
+
+## Client Integration
+
+### React Hook
+
+```tsx
+import { useAgent } from "agents/react";
+
+function Chat() {
+  const { state, send, connected } = useAgent({
+    agent: "my-agent",
+    name: userId,  // Agent instance ID
+  });
+
+  const sendMessage = (text: string) => {
+    send(JSON.stringify({ type: "chat", content: text }));
+  };
+
+  return (
+    <div>
+      {state.messages.map((msg, i) => (
+        <div key={i}>{msg.role}: {msg.content}</div>
+      ))}
+      <input onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)} />
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```javascript
+const ws = new WebSocket("wss://my-agent.workers.dev/agents/MyAgent/user123");
+
+ws.onopen = () => {
+  console.log("Connected to agent");
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log("Received:", data);
+};
+
+ws.send(JSON.stringify({ type: "chat", content: "Hello!" }));
+```
+
+## Common Patterns
+
+See [references/agent-patterns.md](references/agent-patterns.md) for:
+- Tool calling and function execution
+- Multi-agent orchestration
+- RAG (Retrieval Augmented Generation)
+- Human-in-the-loop workflows
+
+## Deployment
+
+```bash
+# Deploy
+npx wrangler deploy
+
+# View logs
+wrangler tail
+
+# Test endpoint
+curl https://my-agent.workers.dev/agents/MyAgent/test-user
+```
+
+## Troubleshooting
+
+See [references/troubleshooting.md](references/troubleshooting.md) for common issues.
+
+## References
+
+- [references/examples.md](references/examples.md) — Official templates and production examples
+- [references/agent-patterns.md](references/agent-patterns.md) — Advanced patterns
+- [references/state-patterns.md](references/state-patterns.md) — State management strategies
+- [references/troubleshooting.md](references/troubleshooting.md) — Error solutions