MCP + CLI Dual Starter: One Zod Schema, MCP Server and CLI Tools

A 40-tool MCP server can cost an agent about 12,000 tokens of definitions before it does anything, which is why "just use the CLI" keeps winning arguments. Most real tools need both, and two hand-kept definitions drift. The MCP + CLI Dual Starter writes each command once, as a Zod schema plus a run function, and ships it as a stdio MCP server for Claude Code, Codex and Cursor, a remote MCP server on Cloudflare Workers behind OAuth 2.1, and a CLI. wowcli json-diff --json and the MCP tool json-diff return the same bytes; the smoke test checks it on every case.

It is the build-it-both-ways version of the WOWHOW guide MCP vs CLI vs Skills, sized to the quotas in Personal AI Agent on Cloudflare Free Tier 2026. TypeScript, Node 22.12+, every version pinned.

What You Get

• packages/schema: defineCommand() with Zod 4 input and output schemas and named outcomes mapped to exit codes, and four real commands. One execute() serves both surfaces.
• packages/cli: wowcli on commander 15, with flags, ranges, defaults and --help generated from the JSON Schema agents see in tools/list.
• packages/mcp-server: MCP SDK v2 (2.3.1). stdio for both the 2026-07-28 protocol and 2025-era clients, a --dry definition-size report, typed per-call client logs. A Worker on createMcpHandler and workers-oauth-provider 1.2.3: consent page, GitHub sign-in with PKCE, login allowlist, scope checks, private-address fetch guard.
• Offline tests: scripts/smoke-test.sh (40 checks, 75 with --with-worker), a byte-for-byte CLI versus MCP parity harness over three MCP clients, and an OAuth end-to-end run against wrangler dev.
• README, USAGE-GUIDE, VERIFY.md, a fifth example command, a Claude Code skill for the CLI, a dev container, single-buyer licence.

The four commands

Tested on 16 October 2026

75 of 75 checks passed on macOS (Node 24.21.0) and in Docker with networking off (Node 22.23.3 and 24.22.0), including wrangler dev and a full OAuth sign-in. Claude Code 2.1.299 connected over stdio and, after claude mcp login, over HTTP to the Worker. Two traps found in testing are handled: the SDK's own stdio example serves only the legacy handshake, and global_fetch_strictly_public still let a Worker fetch 127.0.0.1. The Worker was not deployed to Cloudflare in testing.

Free-tier numbers

Measured: one KV read and no writes per authenticated MCP request, four or five writes per sign-in, two per hourly refresh, against 1,000 free writes a day. The four definitions weigh about 3,345 tokens; price that per agent step in the free Always-On AI Agent Cost Simulator.

How to Set It Up

• Unzip, npm ci, then scripts/smoke-test.sh: expect 40 passed.
• claude mcp add wowcli -- node "$PWD/packages/mcp-server/bin/mcp-stdio.mjs"; Codex and Cursor lines are in the README.
• Run the Worker locally with scripts/dev-worker.sh, no Cloudflare login needed.
• Deploy: GitHub OAuth App, one KV namespace, two secrets, wrangler deploy. About 20 minutes.

What is not included

• Hosting: the Worker runs on your Cloudflare account.
• A published npm package: it is a monorepo you fork and rename.
• Prompts and resources: the commands are tools.
• DNS-level SSRF checks: the guard checks URLs, not resolved addresses.

Adding a command is one file and two lines. To run the calling agent in a locked-down container, pair it with the Agent Sandbox Kit.