@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/building-mcp-server-on-cloudflare/references/tool-patterns.md

@@ -0,0 +1,29 @@
+# Tool Patterns for Cloudflare MCP Servers
+
+Use these patterns when defining tools in a Worker-based MCP server.
+
+## 1) Read-only lookup tool
+- Purpose: fetch status/info without side effects.
+- Input schema: strict object with required identifiers.
+- Output: typed payload + stable error shape.
+
+## 2) Mutating action tool
+- Purpose: create/update/delete with explicit confirmation rules.
+- Input schema: include idempotency key when possible.
+- Output: operation result with `changed: true|false`.
+
+## 3) Search/list tool
+- Purpose: paginated retrieval.
+- Input schema: `limit`, `cursor` (opaque token), optional filters.
+- Output: `items`, `next_cursor`, `has_more`.
+
+## 4) Long-running task launcher
+- Purpose: start async work and return tracking handle.
+- Input schema: task definition + options.
+- Output: `task_id`, `status_url` or poll key.
+
+## Guardrails
+- Validate all tool inputs before processing.
+- Return deterministic errors with machine-readable codes.
+- Avoid leaking secrets in logs or output.
+- Keep tool names stable once published.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/building-mcp-server-on-cloudflare/references/troubleshooting.md

@@ -0,0 +1,317 @@
+# MCP Server Troubleshooting
+
+Common errors and solutions for MCP servers on Cloudflare.
+
+## Connection Issues
+
+### "Failed to connect to MCP server"
+
+**Symptoms:** Client cannot establish connection to deployed server.
+
+**Causes & Solutions:**
+
+1. **Wrong URL path**
+   ```
+   # Wrong
+   https://my-server.workers.dev/
+
+   # Correct
+   https://my-server.workers.dev/mcp
+   ```
+
+2. **Worker not deployed**
+   ```bash
+   wrangler deployments list
+   # If empty, deploy first:
+   wrangler deploy
+   ```
+
+3. **Worker crashed on startup**
+   ```bash
+   wrangler tail
+   # Check for initialization errors
+   ```
+
+### "WebSocket connection failed"
+
+MCP uses SSE (Server-Sent Events), not WebSockets. Ensure your client is configured for SSE transport:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://my-server.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+### CORS Errors in Browser
+
+If calling from browser-based client:
+
+```typescript
+// Add CORS headers to your worker
+export default {
+  async fetch(request: Request, env: Env) {
+    // Handle preflight
+    if (request.method === "OPTIONS") {
+      return new Response(null, {
+        headers: {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type",
+        },
+      });
+    }
+
+    const response = await handleRequest(request, env);
+
+    // Add CORS headers to response
+    const headers = new Headers(response.headers);
+    headers.set("Access-Control-Allow-Origin", "*");
+
+    return new Response(response.body, {
+      status: response.status,
+      headers,
+    });
+  },
+};
+```
+
+## Tool Errors
+
+### "Tool not found: [tool_name]"
+
+**Causes:**
+
+1. Tool not registered in `init()`
+2. Tool name mismatch (case-sensitive)
+3. `init()` threw an error before registering tool
+
+**Debug:**
+
+```typescript
+async init() {
+  console.log("Registering tools...");
+
+  this.server.tool("my_tool", { ... }, async () => { ... });
+
+  console.log("Tools registered:", this.server.listTools());
+}
+```
+
+Check logs: `wrangler tail`
+
+### "Invalid parameters for tool"
+
+Zod validation failed. Check parameter schema:
+
+```typescript
+// Schema expects number, client sent string
+this.server.tool(
+  "calculate",
+  { value: z.number() },  // Client must send number, not "123"
+  async ({ value }) => { ... }
+);
+
+// Fix: Coerce string to number
+this.server.tool(
+  "calculate",
+  { value: z.coerce.number() },  // "123" → 123
+  async ({ value }) => { ... }
+);
+```
+
+### Tool Timeout
+
+Workers have CPU time limits (10-30ms for free, longer for paid). For long operations:
+
+```typescript
+this.server.tool(
+  "long_operation",
+  { ... },
+  async (params) => {
+    // Break into smaller chunks
+    // Or use Queues/Durable Objects for background work
+
+    // Don't do this:
+    // await sleep(5000);  // Will timeout
+
+    return { content: [{ type: "text", text: "Queued for processing" }] };
+  }
+);
+```
+
+## Authentication Errors
+
+### "401 Unauthorized"
+
+OAuth token missing or expired.
+
+1. **Check client is handling OAuth flow**
+2. **Verify secrets are set:**
+   ```bash
+   wrangler secret list
+   # Should show GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
+   ```
+
+3. **Check KV namespace exists:**
+   ```bash
+   wrangler kv namespace list
+   # Should show OAUTH_KV
+   ```
+
+### "Invalid redirect_uri"
+
+OAuth callback URL doesn't match app configuration.
+
+**Local development:**
+- OAuth app callback: `http://localhost:8788/callback`
+
+**Production:**
+- OAuth app callback: `https://[worker-name].[account].workers.dev/callback`
+
+Must match EXACTLY (including trailing slash or lack thereof).
+
+### "State mismatch" / CSRF Error
+
+State parameter validation failed.
+
+1. **Clear browser cookies and retry**
+2. **Check KV is storing state:**
+   ```typescript
+   // In your auth handler
+   console.log("Storing state:", state);
+   await env.OAUTH_KV.put(`state:${state}`, "1", { expirationTtl: 600 });
+   ```
+
+3. **Verify same domain for all requests**
+
+## Binding Errors
+
+### "Binding not found: [BINDING_NAME]"
+
+Binding not in `wrangler.toml` or not deployed.
+
+```toml
+# wrangler.toml
+[[d1_databases]]
+binding = "DB"           # Must match env.DB in code
+database_name = "mydb"
+database_id = "xxx-xxx"
+```
+
+After adding bindings: `wrangler deploy`
+
+### "D1_ERROR: no such table"
+
+Migrations not applied.
+
+```bash
+# Local
+wrangler d1 migrations apply DB_NAME --local
+
+# Production
+wrangler d1 migrations apply DB_NAME
+```
+
+### Durable Object Not Found
+
+```toml
+# wrangler.toml must have:
+[durable_objects]
+bindings = [{ name = "MCP", class_name = "MyMCP" }]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["MyMCP"]
+```
+
+And class must be exported:
+
+```typescript
+export { MyMCP };  // Don't forget this!
+```
+
+## Deployment Errors
+
+### "Class MyMCP is not exported"
+
+```typescript
+// src/index.ts - Must export the class
+export { MyMCP } from "./mcp";
+
+// OR in same file
+export class MyMCP extends McpAgent { ... }
+```
+
+### "Migration required"
+
+New Durable Object class needs migration:
+
+```toml
+# Add to wrangler.toml
+[[migrations]]
+tag = "v2"  # Increment version
+new_classes = ["NewClassName"]
+# Or for renames:
+# renamed_classes = [{ from = "OldName", to = "NewName" }]
+```
+
+### Build Errors
+
+```bash
+# Clear cache and rebuild
+rm -rf node_modules .wrangler
+npm install
+wrangler deploy
+```
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+```typescript
+export class MyMCP extends McpAgent {
+  async init() {
+    console.log("MCP Server initializing...");
+    console.log("Environment:", Object.keys(this.env));
+
+    this.server.tool("test", {}, async () => {
+      console.log("Test tool called");
+      return { content: [{ type: "text", text: "OK" }] };
+    });
+
+    console.log("Tools registered");
+  }
+}
+```
+
+View logs:
+```bash
+wrangler tail --format pretty
+```
+
+### Test Locally First
+
+```bash
+npm start
+npx @modelcontextprotocol/inspector@latest
+```
+
+Always verify tools work locally before deploying.
+
+### Check Worker Health
+
+```bash
+# List deployments
+wrangler deployments list
+
+# View recent logs
+wrangler tail
+
+# Check worker status
+curl -I https://your-worker.workers.dev/mcp
+```

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/cli-developer/POWER.md

@@ -0,0 +1,116 @@
+---
+name: "cli-developer"
+displayName: "CLI Developer"
+description: "Build intuitive, cross-platform CLI tools with argument parsing, interactive prompts, progress indicators, and shell completions across Node.js, Python, and Go"
+keywords:
+  [
+    "cli",
+    "command-line",
+    "terminal",
+    "argument parsing",
+    "shell completion",
+    "interactive prompt",
+    "progress bar",
+    "commander",
+    "click",
+    "typer",
+    "cobra",
+  ]
+---
+
+# CLI Developer
+
+## Overview
+
+Senior CLI developer expertise for building fast, intuitive command-line tools across Node.js, Python, and Go ecosystems. Focus on <50ms startup time, comprehensive shell completions, and delightful developer UX.
+
+## When to Use
+
+- Building CLI tools and terminal applications
+- Implementing argument parsing and subcommands
+- Creating interactive prompts and forms
+- Adding progress bars and spinners
+- Implementing shell completions (bash, zsh, fish)
+- Optimizing CLI performance and startup time
+- Designing command hierarchies and flag conventions
+
+## Core Workflow
+
+1. Analyze UX — identify user workflows, command hierarchy, common tasks
+2. Design commands — plan subcommands, flags, arguments, configuration
+3. Implement — build with appropriate CLI framework for the language
+4. Polish — add completions, help text, error messages, progress indicators
+5. Test — cross-platform testing, performance benchmarks
+
+## Quick Reference
+
+### Framework Selection
+
+| Language | Recommended   | Alternative     |
+| -------- | ------------- | --------------- |
+| Node.js  | Commander.js  | Yargs, oclif    |
+| Python   | Typer         | Click, argparse |
+| Go       | Cobra + Viper | urfave/cli      |
+
+### Command Structure
+
+```
+mycli                           # Root command
+├── init [options]              # Simple command
+├── config
+│   ├── get <key>              # Nested subcommand
+│   ├── set <key> <value>
+│   └── list
+├── deploy [environment]        # Command with args
+│   ├── --dry-run              # Flag
+│   ├── --force
+│   └── --config <file>        # Option with value
+└── plugins
+    ├── install <name>
+    ├── list
+    └── remove <name>
+```
+
+### Exit Codes
+
+| Code | Meaning           |
+| ---- | ----------------- |
+| 0    | Success           |
+| 1    | General error     |
+| 2    | Invalid arguments |
+| 77   | Permission denied |
+| 127  | Not found         |
+| 130  | Ctrl+C (SIGINT)   |
+
+## Constraints
+
+### MUST DO
+
+- Keep startup time under 50ms
+- Provide clear, actionable error messages
+- Support `--help` and `--version` flags
+- Use consistent flag naming conventions
+- Handle SIGINT (Ctrl+C) gracefully
+- Validate user input early
+- Support both interactive and non-interactive modes
+- Test on Windows, macOS, and Linux
+
+### MUST NOT DO
+
+- Block on synchronous I/O unnecessarily
+- Print to stdout if output will be piped
+- Use colors when output is not a TTY
+- Break existing command signatures (breaking changes)
+- Require interactive input in CI/CD environments
+- Hardcode paths or platform-specific logic
+- Ship without shell completions
+
+## Steering Files
+
+| File                 | Load When                                                    |
+| -------------------- | ------------------------------------------------------------ |
+| `design-patterns.md` | Command hierarchy, flags, config layers, plugin architecture |
+| `node-cli.md`        | Commander, Yargs, Inquirer, Chalk, Ora                       |
+| `python-cli.md`      | Typer, Click, argparse, Rich, questionary                    |
+| `go-cli.md`          | Cobra, Viper, Bubble Tea, progress bars                      |
+| `ux-patterns.md`     | Progress indicators, colors, help text, error messages       |

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/cli-developer/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: "cli-developer"
+displayName: "CLI Developer"
+description: "Build intuitive, cross-platform CLI tools with argument parsing, interactive prompts, progress indicators, and shell completions across Node.js, Python, and Go"
+keywords:
+  [
+    "cli",
+    "command-line",
+    "terminal",
+    "argument parsing",
+    "shell completion",
+    "interactive prompt",
+    "progress bar",
+    "commander",
+    "click",
+    "typer",
+    "cobra",
+  ]
+---
+
+# CLI Developer
+
+## Overview
+
+Senior CLI developer expertise for building fast, intuitive command-line tools across Node.js, Python, and Go ecosystems. Focus on <50ms startup time, comprehensive shell completions, and delightful developer UX.
+
+## When to Use
+
+- Building CLI tools and terminal applications
+- Implementing argument parsing and subcommands
+- Creating interactive prompts and forms
+- Adding progress bars and spinners
+- Implementing shell completions (bash, zsh, fish)
+- Optimizing CLI performance and startup time
+- Designing command hierarchies and flag conventions
+
+## Core Workflow
+
+1. Analyze UX — identify user workflows, command hierarchy, common tasks
+2. Design commands — plan subcommands, flags, arguments, configuration
+3. Implement — build with appropriate CLI framework for the language
+4. Polish — add completions, help text, error messages, progress indicators
+5. Test — cross-platform testing, performance benchmarks
+
+## Quick Reference
+
+### Framework Selection
+
+| Language | Recommended   | Alternative     |
+| -------- | ------------- | --------------- |
+| Node.js  | Commander.js  | Yargs, oclif    |
+| Python   | Typer         | Click, argparse |
+| Go       | Cobra + Viper | urfave/cli      |
+
+### Command Structure
+
+```
+mycli                           # Root command
+├── init [options]              # Simple command
+├── config
+│   ├── get <key>              # Nested subcommand
+│   ├── set <key> <value>
+│   └── list
+├── deploy [environment]        # Command with args
+│   ├── --dry-run              # Flag
+│   ├── --force
+│   └── --config <file>        # Option with value
+└── plugins
+    ├── install <name>
+    ├── list
+    └── remove <name>
+```
+
+### Exit Codes
+
+| Code | Meaning           |
+| ---- | ----------------- |
+| 0    | Success           |
+| 1    | General error     |
+| 2    | Invalid arguments |
+| 77   | Permission denied |
+| 127  | Not found         |
+| 130  | Ctrl+C (SIGINT)   |
+
+## Constraints
+
+### MUST DO
+
+- Keep startup time under 50ms
+- Provide clear, actionable error messages
+- Support `--help` and `--version` flags
+- Use consistent flag naming conventions
+- Handle SIGINT (Ctrl+C) gracefully
+- Validate user input early
+- Support both interactive and non-interactive modes
+- Test on Windows, macOS, and Linux
+
+### MUST NOT DO
+
+- Block on synchronous I/O unnecessarily
+- Print to stdout if output will be piped
+- Use colors when output is not a TTY
+- Break existing command signatures (breaking changes)
+- Require interactive input in CI/CD environments
+- Hardcode paths or platform-specific logic
+- Ship without shell completions
+
+## Steering Files
+
+| File                 | Load When                                                    |
+| -------------------- | ------------------------------------------------------------ |
+| `design-patterns.md` | Command hierarchy, flags, config layers, plugin architecture |
+| `node-cli.md`        | Commander, Yargs, Inquirer, Chalk, Ora                       |
+| `python-cli.md`      | Typer, Click, argparse, Rich, questionary                    |
+| `go-cli.md`          | Cobra, Viper, Bubble Tea, progress bars                      |
+| `ux-patterns.md`     | Progress indicators, colors, help text, error messages       |