Skip to content

Toolgrain 0.1.0

Choose a tag to compare

View all tags
@keshavkatwe keshavkatwe released this 25 Oct 06:54
v0.1.0
526ea39
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Toolgrain 0.1.0, the first stable release, is available on npm. All six libraries use the shared version 0.1.0 under the latest tag.

Toolgrain is a TypeScript toolkit for building MCP servers with reusable, typed tools. It implements MCP directly, independently of @modelcontextprotocol/sdk.

What's included

  • Typed tool authoring: reusable tool() definitions, inferred inputs, asynchronous Zod 4 Classic/Mini validation, output schemas, and explicit rich results through mcpResult().
  • Two protocol revisions: MCP 2026-07-28 and initialization-based 2025-06-18, using the same tool API over stdio and independent HTTP POSTs with JSON responses.
  • Request context: frozen request metadata, cooperative cancellation through ctx.signal, and lazy context providers with request-local caching and typed overrides.
  • HTTP authorization: JWT and Clerk integrations, protected-resource metadata, verified request identities, and audience validation.
  • Compiled packages: ESM JavaScript and declarations. MCP also includes JavaScript source maps, declaration maps, and original TypeScript sources for debugging and editor navigation.
  • Reviewed compatibility: packed-consumer checks across supported runtimes/platforms and minimum/current TypeScript and Zod versions.

Packages

Install the packages your application uses at matching versions.

Package Purpose
@toolgrain/mcp Tool authoring, server composition, execution, context, and authorization contracts
@toolgrain/node Stdio and Node HTTP transports
@toolgrain/http Web HTTP handlers
@toolgrain/jwt JWT authorization
@toolgrain/clerk Clerk OAuth authorization
@toolgrain/protocol Pinned MCP wire types, constants, provenance, and upstream licenses

Requirements

  • Node.js ^24.20.0 or Bun >=1.4.4 <2.
  • ESM; TypeScript 5.5.4 or later, with strict enabled.
  • Zod ^4.6.6 for MCP authoring and integrations. Classic and Mini schemas are supported.

CommonJS and legacy node10 module resolution are unsupported. Node 26 remains a preview runtime, outside the supported runtime policy.

Installation

For a typed server using stdio or Node HTTP:

npm install @toolgrain/mcp@0.1.0 @toolgrain/node@0.1.0 "zod@^4.6.6"
npm install --save-dev typescript@7.0.2 @types/node@24.10.0

With a supported Bun version:

bun add @toolgrain/mcp@0.1.0 @toolgrain/node@0.1.0 "zod@^4.6.6"
bun add --dev typescript@7.0.2 @types/node@24.10.0

Configure your project for ESM ("type": "module" in package.json) and enable TypeScript strict mode. The typed stdio quickstart includes the server and compiler configuration. See the Node HTTP example for an HTTP listener.

For a Web HTTP handler, add:

npm install @toolgrain/http@0.1.0
# Bun: bun add @toolgrain/http@0.1.0

Add an authorization integration only when needed:

npm install @toolgrain/jwt@0.1.0
# Or: npm install @toolgrain/clerk@0.1.0
# Bun equivalents: bun add @toolgrain/jwt@0.1.0 or bun add @toolgrain/clerk@0.1.0

Import protocol wire types/constants directly from @toolgrain/protocol; add @toolgrain/protocol@0.1.0 as a direct dependency when your application imports it. Modern exports are at the package root; legacy types use @toolgrain/protocol/2025-06-18.

Upgrading from RC0

Update each Toolgrain dependency your application uses from 0.1.0-rc.0 to 0.1.0. The tool authoring API, library behavior, supported protocol revisions, and dependency requirements match the accepted RC0; no application API migration is required.

latest now resolves to stable 0.1.0 for all six packages. next remains at 0.1.0-rc.0; installations using @next should switch to an explicit stable version or @latest.

Verification

This release is pinned to commit 526ea39af39413d1ea2693b3961c127343b982e4, merged through PR #32.

  • Release verification passed all 20 executed jobs, including the supported Linux/macOS/Windows matrix, intermediate TypeScript versions, stable dependency drift, and informational Node 26/prerelease probes.
  • The npm publication workflow reran full verification and published all six packages using GitHub Actions OIDC. All 22 executed jobs passed; the PR-report job was intentionally skipped.
  • All six downloaded npm archives matched the reviewed archives byte for byte and matched their registry integrity metadata. Each package's recorded OIDC publisher matched its configured trusted publisher.
  • Fresh public-registry installations through latest passed all six imports and strict TypeScript 5.5.4 and 7.0.2 declaration checks.
  • All 10 runtime consumer cases passed on both Node 24.20.0 and minimum Bun 1.4.4, covering both protocol revisions, stdio, HTTP, authorization, context, and cancellation. The Bun consumer also used minimum Zod 4.6.6; the npm/Node consumer used 4.6.7.

Scope and known limitations

  • HTTP serves independent POST requests with JSON responses. Persistent sessions, SSE streaming, progress, resumability, subscriptions, MCP resources, prompts, and elicitation remain outside this release's implemented scope.
  • Cancellation is cooperative. Work that ignores ctx.signal can continue after its response is discarded. The tested Codex CLI/app-server 0.163.0-alpha.10.2 direct-call timeout path did not promptly abort server work; applications performing expensive work should enforce execution deadlines. Direct stdio cancellation and HTTP disconnect controls passed for both supported protocol revisions.
  • The tested Claude Code 2.1.191 client hides supplemental text when structured content is supplied. Put essential narrative information in structured content, or use a text-only result where the tool contract permits it. Both documented workarounds passed.
  • Client interoperability coverage remains partial. Cursor execution/cancellation, modern Claude Code coverage, live OAuth login, and GUI flows remain unverified. See the RC0 acceptance record and interoperability report for tested flows, versions, and findings.

Further reading

Toolgrain-owned code is MIT licensed, copyright 2026 Keshav Katwe. Vendored protocol material and dependency notices retain their upstream terms.

Assets 2
Loading