The WorkerKit API client and tool registry for Node.js. It provides 97 authenticated management tools, 8 anonymous directory tools, and a shared execution engine for their HTTP requests.
Descriptors include agent guidance, annotations and Zod input schemas. MCP servers, CLIs and documentation tools can use the same registry without an MCP SDK dependency.
Tool definitions, schemas, HTTP mappings and agent guidance are authored by the WorkerKit backend. Core distributes a generated, versioned copy to MCP and CLI consumers. Live catalog and account data comes from backend endpoints.
To update the contract, import the reviewed backend Data/AgentContract.json with npm run import:contract -- <artifact-path>. Commit the pinned artifact and generated modules together. npm run check:contract and every build reject manual changes to generated modules. Core owns the HTTP client and execution engine; tool-specific behavior is part of the backend contract.
Adapters advertise each descriptor's description and render its footer with applicable results. For full offline help or REST documentation, use toolDocumentation(descriptor): it includes result interpretation without requiring an API call. Raw JSON response bodies remain unchanged.
npm install @workerkit/coreRequires Node.js >= 22.
import {
WorkerKitClient,
allDescriptors,
byName,
executeTool,
isSuccess,
} from "@workerkit/core";
const client = new WorkerKitClient({
baseUrl: "https://api.workerkit.ai",
});
// Anonymous: search the public kits directory.
const search = byName("kits_search")!;
const result = await executeTool(client, search, { query: "invoice" });
if (isSuccess(result)) {
console.log(result.data);
}
// Authenticated: list your worker fleet with a manager key.
const list = byName("workers_list")!;
const fleet = await executeTool(client, list, {}, { token: process.env.WK_MANAGER_KEY });
await client.close();Each ToolDescriptor declares its name, agent-facing description, zod input
schema, auth mode (manager | anonymous), and how its parameters map onto one
HTTP request; executeTool is the only place that mapping is interpreted, so
every consumer produces an identical wire call.
The client ships sensible production defaults: per-attempt timeouts under a
whole-call deadline, bounded retries for idempotent methods only, a streamed
response-size cap, and quota/rate-limit header extraction. scrubSecrets helps
keep credentials out of logs.
app_github_accounts, app_github_repos and app_github_branches look up
connected GitHub accounts and the repositories and branches their GitHub App
installations grant, so a kit can be installed against exact targets without
running a worker. They need the discoverAppResources scope, which existing
keys gain only through explicit re-scoping, and return setup metadata only,
never repository content or credentials. Accounts come from the workspace's
saved connections, not from GitHub's user directory.
Pass the workspace and connection explicitly. Repository and branch q filters
apply to one provider page, so keep following nextPage even when a filtered
page is empty. Put the returned repository IDs in kit_install.githubSelection
with repositoryMode: "selected"; "all" also covers repositories granted to
the connection later, and accounts: [] defers GitHub setup. The githubSetup
block in kit_install_preview names the required scope and says whether an
explicit selection is mandatory. A branch given as a kit input configures the
job but does not restrict the worker's access. Returned names come from GitHub,
so treat them as untrusted data.
app_slack_workspaces lists the connected Slack workspaces with their saved
token capabilities; app_slack_conversations then lists channel and DM IDs in
the chosen workspaceId, narrowed by conversation types. Both need the
discoverAppResources scope. A filtered page can come back empty while
nextCursor continues, so keep following it. capabilities.conversationTypes
shows which types the saved bot read scopes allow. Message search needs a user
token with search:read; reading history needs the channel ID, the matching
history scopes and bot membership, and covers one conversation.
worker_get and workers_list report each worker's modelType, the same
vocabulary as a kit's: language runs an instruction on a model chosen at
deployment, decision runs a routing table on the decision model, hybrid
classifies and then hands the selected items to one language-model agent, and
none is an Action worker, described below. The kind decides which fields
worker_run and instruction_set accept, and whether a worker is deployed at
all.
A hybrid worker classifies a bounded source window and runs one language-model agent on the selected batch. Core exposes the configuration and a single run receipt; model execution, permissions and billing remain server responsibilities. See the hybrid worker guide.
The purpose: "decision" recipes from kit_app_tools are shortcuts, not a
limit. For any other source, call kit_app_tools without purpose, copy the
tool's argsSchema and documented decisionSource mapping, then validate,
publish privately and install the kit. models_list lists the available
classifiers in decisionProfiles; decisionProfileId sets a kit or deployment
default, or overrides it for one run. Runs execute their declared actions:
there is no preview mode, and unsupported run controls, including those in
run_bulk entries, are rejected before any request is sent.
An Action worker exposes explicitly selected, typed app tools that a caller
invokes directly, without a reasoning model or a hosted deployment.
action_worker_options lists the native and reviewed MCP apps, their tool
schemas and the server's defaults. Creating one with action_worker_create and
an app copies that app's default tools once; an explicit actionSpec can
instead select up to 64 tools across apps. Omitting app selects Slack, and
tools added to the catalog later must be selected by hand.
Read a worker's tool schemas with worker_tools before calling one with
worker_tool_call, which takes tokenId, toolName, arguments and an
optional contractVersion: 1 and idempotencyKey. The key travels in the
Idempotency-Key header; only the version and arguments go in the body. Give
each intended write its own key and keep it for transport retries. Poll
worker_tool_invocation for pending results, and never automatically resend
an outcome_unknown call with a new key: the app may already have acted. A
refusal marked retryable can be tried again later under a new key. A call
cannot change the saved tool selection, connection or sender, and a
changed tool contract needs an explicit owner review and save. Generic write
receipts keep the confirmation without storing private app response bodies.
A call answers with status succeeded, denied, failed, in_progress or
outcome_unknown, plus invocationId on a write (reads leave no receipt).
Repeating a write's key with the same arguments returns the stored receipt
without calling the app again; the same key with different arguments is a 409
idempotency_conflict.
An Action worker reports modelType: "none" and deployment: null, and
readiness.canInvoke says whether its tools can be called now. It is never
deployed or run: worker_run and worker_deploy refuse it with
400 action_worker_requires_invoke, and it takes no instruction, schedule or
trigger.
Discovery needs readWorkers, creation needs createWorkers, and calls and
receipts need invokeActions; existing manager keys may need those scopes
granted explicitly.
git clone https://github.com/workerkit/core.git && cd core
npm ci
npm test # descriptor-contract suite
npm run typecheck
npm run build
npm run check:descriptions # rebuild, then report size and guidance warningscheck:release includes the fresh description report. For the complete per-tool
report, run npm run build then node scripts/check-descriptions.mjs --json.
An optional --baseline <report.json> compares reports made with the same
projection and tokenizer. This is a transport-neutral core projection; the MCP
repository separately checks real SDK metadata and reviewed growth budgets.
Size, uppercase and unattributed repeated-clause findings are review warnings,
never truncation instructions. Generated shared guidance is attributed by its
canonical identifier; other repeated text still needs contextual review.
Publishing also runs check:provenance: the pinned backend artifact must name
its reviewed 40-character source commit and match the generated modules.
Local working-tree-* artifacts remain usable for development and package
smoke tests, but cannot pass this publication gate.
Issues and pull requests are welcome. Every tool is a declarative ToolDescriptor;
the descriptor-contract tests pin each one's exact wire call, so behavior changes
are visible in the diff. Security reports go to SECURITY.md, not the
issue tracker.
Releases are tag-driven: the workerkit account pushes a vX.Y.Z tag and CI publishes to npm
via trusted publishing with a
provenance attestation. Publication reruns also require the workerkit account.
- WorkerKit: https://workerkit.ai
- Changelog: CHANGELOG.md
- Terms of Service · Privacy Policy · Acceptable Use Policy · Security Overview
This package is released under the MIT License. That covers the software itself; using it against WorkerKit's hosted API is separately governed by the Terms of Service above.