Documents
safe-html-pdf
Print HTML to PDF with Playwright and headless Chromium, with JavaScript and the network turned off, hard limits, and a layout lint for overflow and broken images.
AI agent guardrails for MCP servers: dry run and confirm, signed preview tokens, optimistic concurrency, revision undo and errors that teach the agent.
npm install mcp-guardrails
# for the official SDK integration:
npm install @modelcontextprotocol/sdk zodAn agent with write tools behaves like a fast, confident new hire. It retries calls that already succeeded, guesses field names, edits a record it read ten minutes ago, and runs a delete on the first try because nothing asked it to look first. The official MCP SDKs give you tool annotations, which are hints, but no dry-run and confirm flow, no preview tokens, no version checks and no undo.
mcp-guardrails is that layer for MCP security, extracted from production servers. You define each tool once with a kind of read, write or destructive, and the package sets the MCP annotations and enforces the guard. It works with the official MCP TypeScript SDK through an optional entry point, and the same guardrails protect the MCP servers of Sitessa and the Bundlewise CRM.
The core has no runtime dependencies and uses WebCrypto, so it runs on Node 20+ and on edge runtimes such as Cloudflare Workers.
import { z } from 'zod';
import { createPreviewTokens, deleteIfUnchanged, notFound } from 'mcp-guardrails';
import { defineTool } from 'mcp-guardrails/sdk';
const tokens = createPreviewTokens({ secret: process.env.MCP_PREVIEW_SECRET! }); // 32+ bytes
const notesDelete = defineTool({
name: 'notes_delete',
kind: 'destructive', // with tokens: dryRun → previewToken → confirm
idempotent: true,
description: "Delete a note. Needs a dry run and the user's confirmation.",
input: { id: z.string() },
version: true, // adds a required expectedVersion argument
tokens,
actor,
async plan({ id }) {
const note = await notes.get(id);
if (!note) throw notFound('note', id);
return { deletes: { id, title: note.value.title, version: note.version } };
},
async run({ id }, extra, guard) {
const deleted = await deleteIfUnchanged(notes, { id, expectedVersion: guard.expectedVersion });
return { deleted: id, revisionId: deleted.revisionId };
},
});→ notes_delete { "id": "n1", "expectedVersion": 1 }
← isError: { "error": { "code": "confirmation_required",
"message": "notes_delete needs confirm: true. Call notes_delete with dryRun: true first, show the user the plan, then call it again with the same arguments plus previewToken and confirm: true." } }→ notes_update { "id": "n3", "expectedVersion": 4, "patch": { "title": "New" } }
← isError: { "error": { "code": "version_conflict", "currentVersion": 6, "expectedVersion": 4,
"message": "note \"n3\" was changed since you read it (current version 6, you sent 4). Read it again, redo your change on the current data, and pass the new version." } }Define each tool with mcp-guardrails. Mark deletes as kind: 'destructive' with preview tokens so they need a dry run and a signed token, add expectedVersion so stale edits are refused, and record revisions so a change can be undone. The agent gets an error that says what to do next.
Checks that run on the server, outside the model, so they hold even when the agent guesses wrong. Here that means a dry run before a destructive call, a signed token tied to the previewed arguments, a version check on every update, and an undo log.
Yes, through mcp-guardrails/sdk, which wraps registerTool for McpServer. It needs @modelcontextprotocol/sdk 1.32 or later and zod 4 as optional peer dependencies. The core package needs neither.
A destructive tool refuses to act on the first call and returns a plan and a previewToken. The agent is told to show the plan to the user and call again with the same arguments, the token and confirm: true. The server enforces the two steps; showing the plan to a person is up to your client.
Documents
Print HTML to PDF with Playwright and headless Chromium, with JavaScript and the network turned off, hard limits, and a layout lint for overflow and broken images.
Localization
Translation quality assurance for the facts in a string: check that numbers, prices, percentages, URLs, emails and {placeholders} survive translation.
Author
Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.