/walkeros-mcp-actions

name: walkeros-mcp-actions
description:
  Use when an AI agent calls walkerOS MCP tools from code (code execution / Code
  Mode, a Worker, or an app sandbox) to validate, simulate, bundle, or inspect
  flows and packages, and wants to filter large results in code instead of
  issuing many separate tool calls.

Calling walkerOS MCP Tools from Code

When to Use This Skill

You are an AI agent running inside a **code-execution host**, not issuing tool calls one at a time through the model. Examples:

• Claude Code in code-execution / "Code Mode"
• a Cloudflare Worker or other serverless sandbox
• an app's server-side sandbox that binds the walkerOS MCP transport

The pattern: bind the MCP transport once, call only the tools you need from code, **filter the verbose `structuredContent` payload in code**, and return only the distilled answer to the model. This suppresses tokens that the model never needs to see (full catalogs, per-destination simulation dumps) and avoids a chain of one-by-one tool calls.

This is the "Code Execution with MCP" / "Code Mode" pattern: treat MCP tools as functions you call in a sandbox, not as round-trips through the model context.

The Seven Pure Tools

These tools of the local walkerOS MCP server (`@walkeros/mcp`) are pure and composable: same input, same output, no auth, no side effects in any account. Safe to call freely from code.

| Tool (fully-qualified) | Purpose | Verbose output worth filtering | | ------------------------------ | --------------------------------------------------- | ------------------------------- | | `walkeros-flow:flow_validate` | Validate a flow or step config; return issues | small | | `walkeros-flow:flow_simulate` | Run a flow against an event, mock destination calls | **yes** (per-destination calls) | | `walkeros-flow:flow_bundle` | Bundle a flow config to a JS artifact | medium (bundle/meta) | | `walkeros-flow:flow_examples` | Fetch canonical flow/step examples | **yes** (many examples) | | `walkeros-flow:flow_load` | Load a flow config, or start a new one | medium (the whole config) | | `walkeros-flow:package_search` | Find packages by type/platform/keyword | **yes** (catalog) | | `walkeros-flow:package_get` | Read a package's schemas, hints, examples | **yes** (full schemas) |

To test an event against a flow, use `walkeros-flow:flow_simulate`: it runs the event through the flow with destination calls **mocked**, so nothing leaves the sandbox. Do not use `walkeros-flow:flow_push` for this (see below).

Always use the **fully-qualified `<server>:<tool>`** name (Agent Skills best-practice) so the call is unambiguous when multiple MCP servers are bound. `walkeros-flow` is the name the walkerOS plugin and the documented MCP config give the local server; the hosted walkerOS MCP server is bound as `walkeros`.

Out of scope for this pattern

`walkeros-flow:flow_push` sends a **real event to real destinations** (real API calls to live endpoints), so calling it "freely" would produce real, duplicated sends; use `walkeros-flow:flow_simulate` to test without sending. The tools for what the walkerOS app stores (projects, saved flows, deployments, secrets, Observe) live on the hosted walkerOS MCP server and act with the person's authorization there. Do **not** drive these tools from this code-execution filtering pattern; they belong in an interactive, authorized session.

The Recommended Pattern

1. **Bind the transport once.** Connect to the walkerOS MCP server at the top of your script, reuse the client for every call. 2. **Call only the tools you need.** Don't enumerate; pick the minimal set. 3. **Read `structuredContent`.** Every tool returns an MCP envelope; the typed payload lives in `structuredContent` (the `content` text block is for humans). 4. **Filter in code.** Reduce verbose payloads to the few fields that answer the question. 5. **Return the distilled answer.** Hand the model one line, not the full dump.

// Pseudo-code in a code-execution host. `mcp` is the bound walkerOS client.
// (Typed `@walkeros/mcp-actions` wrappers are planned/forthcoming; until then
//  call the raw tools and read `structuredContent` yourself.)

const flow = await readFile('flow.json', 'utf8');

// 1. Validate first; bail with one line if the config is broken. Branch on
//    `code`, never on `message`. `strict: true` turns warnings and skipped
//    checks (`details.skipped`) into failures: `valid` is false, as CLI --strict.
const v = await mcp.call('walkeros-flow:flow_validate', {
  type: 'flow',
  input: flow,
  strict: true,
});
const { valid, errors, warnings, details } = v.structuredContent;
if (!valid) {
  const codes = [...errors, ...warnings].map((issue) => issue.code);
  const skipped = (details.skipped ?? []).map((skip) => skip.code);
  return `invalid flow: ${[...codes, ...skipped].join(', ')}`;
}

// 2. Simulate one event per destination: `step` names one target step
//    ("destination.<name>"), and each answer is verbose (every vendor call).
const destinations = Object.keys(
  JSON.parse(flow).flows.default.destinations ?? {},
);
const failed = [];
for (const name of destinations) {
  const sim = await mcp.call('walkeros-flow:flow_simulate', {
    configPath: 'flow.json',
    step: `destination.${name}`,
    event: 'product add',
  });
  // 3. Filter in code: keep only destinations that received nothing. The
  //    model never sees the per-destination call dump, only the verdict.
  const received = Object.values(sim.structuredContent.destinations ?? {}).some(
    (d) => d.received,
  );
  if (!received) failed.push(name);
}

// 4. Return one line.
return failed.length
  ? `simulate failed for: ${failed.join(', ')}`
  : 'simulate ok for all destinations';

The same shape applies to `