mcp-scripting

MCP scripting

For multi-call MCP work, write ordinary JavaScript with loops, filtering, chaining, fan-out, or other logic between calls. Run that source with mcpScript; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use mcp instead.

Write the source naturally, then pass it as mcpScript's code argument:

const { items } = await tools.search({ query: "search issues", server: "github" });
const candidate = items[0];
if (!candidate) return { error: "No matching tool" };

const details = await tools.describe({ path: candidate.path });
if (details.error) return details;

const result = await tools.call(details.path, { query: "is:open label:bug" });
if (!result.ok) return result;
emit({ tool: details.path, completed: true });
return result.data;

Workflow

1. Find candidate tools with await tools.search({ query, server?, limit?, offset? }).
2. Inspect the exact returned path with await tools.describe({ path }).
3. Call it with tools.call(path, args).

Descriptors include inputTypeScript (a compact parameter shape, or formatted schema fallback). When a compact shape would omit documented fields, inputGuidance preserves their descriptions, including formats and units. Undocumented inputs stay compact.

When advertised by the server, outputSchema is the original JSON Schema and outputSchemaTarget is "data.structuredContent": it describes structured output inside the successful { ok: true, data } call envelope, not the envelope itself. Inspect this schema for result fields and constraints; unsupported constructs remain intact rather than being presented as an approximate TypeScript type. Both output fields are absent when no output schema is advertised. Discovery and cache refresh preserve these optional schemas; old cache entries gain them on the next server metadata refresh. Ordinary search results do not include schemas.

Calls resolve to { ok: true, data } or { ok: false, error }; handle failed calls instead of expecting them to stop the script. emit(value) adds user-visible output before the final return value. console output is captured too.