Official TypeScript SDK and CLI for extending Weavetab MCP.
Build typed tools, middleware hooks, custom commands, and HUD overlays with manifest-enforced permissions.
Overview · Quickstart · Manifest · Plugin API · CLI · Testing
@weavetab/sdk is the TypeScript toolkit for building plugins on top of the Weavetab MCP runtime. Write tools with Zod, intercept or override any of the 40 built-in browser and Electron tools, persist plugin state in an isolated sandbox, and drive the Chrome extension HUD without hand-writing JSON Schema.
@weavetab/sdk tracks @weavetab/mcp in 1:1 SemVer lock-step (v2.6.4). Declaring "@weavetab/sdk": "^2.6.4" in package.json defines your plugin's compatible MCP runtime range with no duplicate version fields in weavetab.json.
Built by Weavetab, architected by fy2ne.
Most plugin SDKs either expose raw host internals with zero isolation or bury authors under hand-written JSON Schema boilerplate. @weavetab/sdk is built around four rules:
- Manifest-only permissions. Capabilities (
tools,hooks,extension,commands,prompts,resources,cdp,desktop,storage,config,network) are declared exclusively inweavetab.json. The MCP loader ignores JS-exported permission objects so every tool call and hook is gated against an auditable static manifest. - TypeScript and Zod as the single source of truth. Define parameters once with
defineTool({ name, description, schema, handler }).weavetab-sdk buildcompiles TypeScript and exports JSON Schema directly intoweavetab.json. - Sandboxed runtime boundaries. Each plugin gets its own
~/.weavetab/plugins/<name>/directory (config.json,storage.json,data/) and interacts with pages throughTabProxy,DesktopProxy, andExtensionBridge. - Offline-first verification. Run unit tests, tool call simulations, and preflight security audits in-process with
@weavetab/sdk/testingand@weavetab/sdk/preflightbefore launching a browser or publishing.
flowchart TB
Author["Plugin Author (src/index.ts · Zod + TypeScript)"]
Build["weavetab-sdk build · schema exporter & preflight"]
Bundle["Plugin Package (dist/index.js + weavetab.json)"]
subgraph Runtime["Weavetab MCP PluginRuntime"]
direction TB
Gate["Manifest Gate — static weavetab.json permissions"]
Surface["McpSurface & Hooks — add/override/remove · before/after/DOM/navigate"]
Bridge["Host Proxies — TabProxy · DesktopProxy · ExtensionBridge · PluginStorage"]
Gate --> Surface --> Bridge
end
Target["40 Built-In MCP Tools · Chrome Tabs · Electron Apps"]
Author --> Build --> Bundle --> Gate
Bridge --> Target
classDef author fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#f8fafc
classDef build fill:#1e1b4b,stroke:#8b5cf6,stroke-width:2px,color:#f5f3ff
classDef gate fill:#31102f,stroke:#ec4899,stroke-width:2px,color:#fdf2f8
classDef bridge fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#ecfdf5
classDef target fill:#0f172a,stroke:#64748b,stroke-width:1.5px,color:#e2e8f0
class Author,Bundle author
class Build build
class Gate,Surface gate
class Bridge bridge
class Target target
Scaffold a new TypeScript plugin from one of 5 templates (Node.js >= 20.19.0):
npx -y @weavetab/sdk init my-custom-plugin| Template | Focus | Included Surfaces |
|---|---|---|
standard |
General purpose | defineTool, PluginStorage, HUD thought bubble, onBeforeAction |
visual |
UI & Visual Feedback | setHudState, showThought, injectStyles |
scraper |
Data Extraction | callCtx.tab.evaluate, storage.setJSON |
automation |
Workflows | Multi-step browser workflows and form helpers |
override |
Interception & Guardrails | overrideTool("browser_navigate"), beforeToolCall, extension.hud |
# Pass a specific template
npx -y @weavetab/sdk init my-guard-plugin --template overrideGenerated layout:
my-custom-plugin/
├── src/
│ └── index.ts # Plugin entry (tools, hooks, lifecycle)
├── test/
│ └── manifest.test.mjs # Manifest and preflight verification
├── weavetab.json # Security manifest, permissions & tool schemas
├── package.json # Scripts (build, dev, validate, release)
├── tsconfig.json # Strict ESM TypeScript config
└── README.md
Parameters are inferred directly from the Zod schema:
import { defineTool, z } from "@weavetab/sdk";
export const auditTool = defineTool({
name: "audit_page",
description: "Audits target page components and reports issues",
schema: z.object({
selector: z.string().describe("Root CSS selector to inspect"),
maxDepth: z.number().default(5).describe("Maximum DOM depth to traverse"),
strictMode: z.boolean().optional().describe("Fail on accessibility warnings"),
}),
handler: async (args, callCtx) => {
const count = await callCtx.tab.evaluate(
`(sel) => document.querySelectorAll(sel).length`,
args.selector
);
return {
content: [{ type: "text", text: `Found ${count} nodes for ${args.selector} (depth ${args.maxDepth})` }],
};
},
});import { PluginBuilder, z } from "@weavetab/sdk";
export default new PluginBuilder("weavetab-plugin-analytics")
.version("1.0.0")
.description("Real-time page analytics and HUD plugin")
.defaultConfig({
enableHud: true,
sampleRate: 100,
})
.addTool({
name: "record_metric",
description: "Records a metric in isolated plugin storage",
schema: z.object({
metric: z.string().describe("Metric name"),
value: z.number().describe("Numeric value"),
}),
handler: async (args, callCtx) => {
await callCtx.storage.set(`metric:${args.metric}`, args.value);
return { content: [{ type: "text", text: `Recorded ${args.metric}: ${args.value}` }] };
},
})
.onBeforeAction(async (tool, args) => {
if (tool === "browser_navigate" && String(args.url || "").includes("tracking-ads.com")) {
return { __blocked: true, reason: "Blocked navigation to tracking domain" };
}
})
.onPageNavigate(async (url) => {
console.log("navigated:", url);
})
.onLoad(async (ctx) => {
ctx.logger.info("analytics plugin ready", ctx.config);
})
.build();import { definePlugin, type PluginContext } from "@weavetab/sdk";
import { auditTool } from "./tools.js";
export default definePlugin({
name: "weavetab-plugin-example",
version: "1.0.0",
defaultConfig: {
enableHud: true,
maxRetries: 3,
},
tools: [auditTool],
onAfterAction: async (tool, result) => result,
onDOMMutation: async (delta) => {
if (delta.significantChange) {
console.log(`mutated ${delta.url}: +${delta.added?.length || 0}`);
}
},
async onLoad(ctx: PluginContext) {
ctx.mcp.registerTool({
name: "example_ping",
description: "Health check probe",
handler: async () => ({ content: [{ type: "text", text: "pong" }] }),
});
},
async onUnload(ctx: PluginContext) {
ctx.logger.info("plugin unloaded");
},
});Wrap or replace any of the 40 built-in MCP tools (requires permissions.tools.override in weavetab.json):
ctx.mcp.overrideTool("browser_eval", async (args, session, config, originalHandler) => {
ctx.logger.debug("eval audit:", args.expression);
const res = originalHandler ? await originalHandler(args, session, config) : null;
return { ...res, auditedByPlugin: true };
});Every plugin writes inside ~/.weavetab/plugins/<plugin-name>/ (config.json, storage.json, data/):
await ctx.storage.set("last_run", Date.now());
const lastRun = await ctx.storage.get<number>("last_run");
await ctx.storage.setJSON("data/report.json", { items: [1, 2, 3] });
const files = await ctx.storage.list("data");
await ctx.storage.setWithExpiry("session_cache", { ok: true }, 60_000);
const cached = await ctx.storage.getWithExpiry("session_cache");
await ctx.storage.pruneExpired();await ctx.extension.showThought(session, "Extraction complete", { durationMs: 3500 });
await ctx.extension.setHudState(session, {
action: "Extracting",
badge: "Running",
badgeColor: "#10b981",
});
// Plain text panels require extension.hud or extension.overlay; raw html requires extension.scripts
await ctx.extension.mountPanel(session, {
title: "Table Extractor",
text: "Parsed 24 rows",
position: "bottom-right",
});
await ctx.extension.clearPanel(session);
await ctx.extension.injectStyles(session, `.wt-mark { outline: 2px solid #3b82f6 !important; }`);Test plugins headless without launching Chrome:
import test from "node:test";
import assert from "node:assert/strict";
import { createMockContext, simulateToolCall } from "@weavetab/sdk/testing";
import { runPreflight } from "@weavetab/sdk/preflight";
test("passes preflight audit", async () => {
const audit = await runPreflight(process.cwd());
assert.equal(audit.success, true);
});
test("executes tool in mock context", async () => {
const ctx = createMockContext({
config: { enableHud: true },
mockUrl: "https://example.com",
});
const res = await simulateToolCall(myTool, { selector: "h1" }, ctx);
assert.equal(res.isError, undefined);
});@weavetab/sdk ships weavetab-sdk, weavetab-plugin, and weavetab binaries. When @weavetab/mcp is installed globally, prefer weavetab-sdk (or npx @weavetab/sdk) for SDK authoring commands and weavetab plugin for MCP runtime management.
| Command | Description |
|---|---|
weavetab-sdk init [name] [--template <id>] |
Scaffolds a new TypeScript plugin (standard, visual, scraper, automation, override) |
weavetab-sdk templates |
Lists the 5 starter templates |
weavetab-sdk build |
Compiles TypeScript, checks instructions budget, and syncs weavetab.json |
weavetab-sdk manifest / schema |
Generates weavetab.json from Zod tool definitions and hooks |
weavetab-sdk dev |
Runs tsc --watch and auto-syncs weavetab.json on dist/ updates |
weavetab-sdk preflight [dir] |
Audits manifest, permissions, entry path containment, and instructions budget |
weavetab-sdk validate [--offline] |
Validates weavetab.json against the schema (--offline skips remote fetch) |
weavetab-sdk doctor |
Checks Node.js, npm, TypeScript, and ~/.weavetab environment health |
weavetab-sdk publish [--dry-run] |
Runs preflight gate, npm publish, and weavetab.dev registry sync |
weavetab-sdk version |
Prints the installed SDK version |
npm run build
npx @weavetab/sdk validate
npm run release # runs weavetab-sdk publishInstall and manage in the MCP runtime:
weavetab plugin add your-published-package-name
weavetab plugin info your-published-package-name
weavetab plugin enable your-published-package-name
weavetab plugin use your-published-package-name