Skip to content
WeavetabPublic

About

Official TypeScript SDK for developing Weavetab plugins and tools

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Weavetab SDK

Official TypeScript SDK and CLI for extending Weavetab MCP.
Build typed tools, middleware hooks, custom commands, and HUD overlays with manifest-enforced permissions.

version license MCP Node templates

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.


Design Philosophy

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:

  1. Manifest-only permissions. Capabilities (tools, hooks, extension, commands, prompts, resources, cdp, desktop, storage, config, network) are declared exclusively in weavetab.json. The MCP loader ignores JS-exported permission objects so every tool call and hook is gated against an auditable static manifest.
  2. TypeScript and Zod as the single source of truth. Define parameters once with defineTool({ name, description, schema, handler }). weavetab-sdk build compiles TypeScript and exports JSON Schema directly into weavetab.json.
  3. Sandboxed runtime boundaries. Each plugin gets its own ~/.weavetab/plugins/<name>/ directory (config.json, storage.json, data/) and interacts with pages through TabProxy, DesktopProxy, and ExtensionBridge.
  4. Offline-first verification. Run unit tests, tool call simulations, and preflight security audits in-process with @weavetab/sdk/testing and @weavetab/sdk/preflight before launching a browser or publishing.

Architecture

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
Loading

Quick Start

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 override

Generated 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

Authoring Patterns

Type-Safe Tools (defineTool)

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})` }],
    };
  },
});

Fluent Builder (PluginBuilder)

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();

Declarative Definition (definePlugin)

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");
  },
});

Middleware, Overrides & Extension Bridge

Tool Overrides (ctx.mcp.overrideTool)

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 };
});

Sandboxed Storage (ctx.storage)

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();

Visual HUD & Extension (ctx.extension)

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; }`);

Testing & Preflight

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);
});

CLI Reference

@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

Publishing & Installing in Weavetab MCP

npm run build
npx @weavetab/sdk validate
npm run release              # runs weavetab-sdk publish

Install 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

License

MIT © Weavetab (owned by fy2ne)

About

Official TypeScript SDK for developing Weavetab plugins and tools

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages