llm-delegate

MCP tool that generates ready-to-run LLM delegation scripts. Use it when you want Claude Code to delegate a short-context, single-shot judgment or extraction task to an LLM — fuzzy classification, scoring, detection, multi-label tagging, structured extraction, summarization, or any one-off judgment call (fact-check, risk assessment, grading).

Core idea: the agent delegates the task to an LLM; the timing and details of the LLM call are delegated back to the agent. This tool just hands the agent a ready-to-run template — it does not perform any LLM calls itself.

Why

Subagents, claude -p, and pi-agent are too heavy for simple judgment tasks. A single curl-equivalent call to an LLM is enough — but the agent often lacks the awareness to delegate, or hand-writes a brittle heuristic instead. llm-delegate exists to give the agent a named delegation surface and a script that handles auth/model/prompt for it.

Install

From npm (recommended for end users):

npm install -g @joezm/llm-delegate

Verify: llm-delegate --help (or npx @joezm/llm-delegate --help without installing).

For MCP usage you usually don't even need a global install — see "Use as an MCP server" below (npx form). The global install is only required for the standalone CLI command or the node <abs-path> MCP form.

Configure

Create a .env (search order: ./.env → ~/.llm_delegate.env → $XDG_CONFIG_HOME/llm_delegate/.env). See .env.example:

LLM_DELEGATE_API_KEY=sk-xxxx
LLM_DELEGATE_BASE_URL=http://localhost:14000/v1
LLM_DELEGATE_MODEL_NANO=qwen3-27b
LLM_DELEGATE_MODEL_MINI=qwen-plus
LLM_DELEGATE_MODEL_STD=gpt-4o-mini
LLM_DELEGATE_MODEL_PRO=gpt-4o

process.env overrides .env. The tool ships no default model IDs — every tier you use must be configured.

Use as an MCP server

MCP clients launch the server via a command + args pair. Most clients (Claude Code included) only resolve a small set of commands reliably (npx, node, python, uvx) — a globally-installed bin name like llm-delegate often isn't on the client's PATH (especially for GUI-launched clients). Use one of the two forms below instead.

Option 1 — npx (recommended, zero local install):

{
  "mcpServers": {
    "llm_delegate": {
      "command": "npx",
      "args": ["-y", "@joezm/llm-delegate", "--mcp"]
    }
  }
}

npx -y fetches the latest published version on first run (and when the version bumps). Requires network access on cold start.

Option 2 — node with an absolute path (pinned version, offline-capable):

First install once and locate the compiled entry point:

npm install -g @joezm/llm-delegate
# Find the installed location:
node -e "console.log(require.resolve('@joezm/llm-delegate/dist/cli.js'))"
# e.g. /usr/local/lib/node_modules/@joezm/llm-delegate/dist/cli.js

Then point node at that absolute path:

{
  "mcpServers": {
    "llm_delegate": {
      "command": "node",
      "args": ["/absolute/path/to/@joezm/llm-delegate/dist/cli.js", "--mcp"]
    }
  }
}

The server exposes one tool: delegate. Call it with action + spec + examples (required), plus optional tier and options. It returns a .mjs script — save it, chmod +x, and run it (./script.mjs "input" or cat inputs.txt | ./script.mjs).

Runtime dependency: generated scripts import OpenAI from 'openai'. openai is a dependency of this package, so it's available wherever this package is installed — but if you save a script somewhere that can't resolve those modules (e.g. an empty dir), run npm install openai there first.

Use as a CLI

After npm install -g @joezm/llm-delegate (so the llm-delegate bin is on your shell PATH — fine for terminal use, unlike MCP clients):

llm-delegate generate \
  --action classify \
  --spec "CANDIDATES: positive, negative, neutral" \
  --example "I love it -> {\"result\":\"positive\",\"reason\":\"likes it\"}" \
  --tier auto \
  > classify.mjs

Or, without a global install: npx @joezm/llm-delegate generate ... (same args).

Actions

| action | what it does | default tier | |---|---|---| | classify-binary | yes/no judgment | nano | | classify | single-label multi-class | nano | | score | numeric rating | mini | | detect | "what is this" | mini | | label | multi-label tagging | mini | | summarize | compress text | mini | | extract | text → JSON | std | | task | catch-all (fact-check, grade, …) | std |

Judgment actions (classify-binary, classify, score, detect) emit {"result":...,"reason":...}. label emits {"results":[...],"rationale":"..."}. extract emits a bare JSON object. summarize and task emit free text.

Tiers

nano < mini < std < pro. The agent only sees tier names; the underlying model ID is resolved from LLM_DELEGATE_MODEL_* env vars and baked into the generated script as a literal. auto uses each action's default tier.

Development

git clone <repo> && cd llm_delegate
npm install
npm test          # vitest
npm run typecheck # tsc --noEmit
npm run build     # tsc → dist/