htmltool

A Bun runner for HTML-first local tools with embedded server TypeScript, typed browser RPC, async streams, and MCP 2.0 Streamable HTTP.

Install

mise use -g github:arlyon/htmltools@0.3.0
htmltool instructions

Related MCP server: req-mcp-server

Tool environment

A portable tool can declare dependencies directly in its HTMLTool manifest:

<script type="application/htmltool+json">
  {
    "name": "hello-tool",
    "dependencies": {
      "htmltool": "github:arlyon/htmltools#v0.3.0"
    }
  }
</script>

The installed CLI does not make htmltool/server or htmltool/client resolvable to a tool bundle, so include htmltool in embedded dependencies. HTMLTool first attempts to bundle without installing. If that bundle fails and the embedded environment is missing, it invokes its embedded Bun package manager with lifecycle scripts disabled, installs into a content-addressed cache under ${XDG_CACHE_HOME:-~/.cache}/htmltool/environments/ on Linux, and retries once. htmltool check installs first because type-checking requires dependency types. Set HTMLTOOL_CACHE_DIR to override the cache root. Pin exact versions for reproducibility.

Alternatively, an HTML tool can use an ordinary package environment:

open-loops/
├── index.html
├── package.json
└── bun.lock

{
  "private": true,
  "type": "module",
  "scripts": {
    "start": "htmltool index.html"
  },
  "dependencies": {
    "htmltool": "github:arlyon/htmltools#v0.3.0",
    "yaml": "^2.9.0"
  },
  "devDependencies": {
    "@types/bun": "^1.3.10"
  }
}

Install and launch it like any other Bun project:

bun install
bun run start

The runner compiles virtual client and server entries entirely in memory. Without manifest dependencies, Bun and TypeScript resolve bare imports using the nearest package.json, node_modules, and tsconfig.json. With an uncached embedded manifest, HTMLTool tries that nearest environment first; a successful bundle skips installation. If bundling fails, it installs every declared package and retries in the isolated cache, which is reused on later runs. HTML-linked assets continue to resolve beside the HTML file. Keep TypeScript in the embedded blocks for single-file mode; use project mode when importing local TypeScript modules. Missing packages are reported as normal unresolved imports.

The browser opens by default. Pass --no-open when running headlessly:

htmltool index.html --no-open

Source format

A tool has a small JSON manifest and TypeScript blocks for shared contracts, server implementation, and browser code:

<script type="application/htmltool+json">
  {
    "name": "hello",
    "dependencies": {
      "htmltool": "github:arlyon/htmltools#v0.3.0"
    }
  }
</script>

<script lang="ts" common>
  interface Server {
    greet(input: { name: string }): { message: string };
  }
</script>

<script lang="ts" server>
  import { createServer, rpc } from "htmltool/server";

  export default createServer<Server>({
    greet: rpc(({ name }) => ({ message: `Hello ${name}` }))
  });
</script>

<script lang="ts" client>
  import { createClient } from "htmltool/client";

  const client = createClient<Server>();
  const result = await client.greet({ name: "Ada" });
</script>

Run htmltool check index.html to type-check the real common + server and common + client programs. Normal startup skips type-checking and bundles both runtime programs in memory. In-editor support uses the editor's existing HTML/TypeScript handling; no language server is bundled with the runner.

MCP Apps / MCP UI

An HTMLTool can expose an interactive MCP App without a separate frontend project. Define the launch operation as an mcp(...) server method:

import { createServer, mcp, z } from "htmltool/server";

export default createServer({
  greet: mcp({
    description: "Greet someone",
    input: z.object({ name: z.string() }),
    output: z.object({ message: z.string() }),
    run: ({ name }) => ({ message: `Hello ${name}` }),
  }),
});

Then annotate one hyphenated custom element with that method name:

<greeting-card data-htmltool-ui="greet">
  <output>Waiting…</output>
</greeting-card>

HTMLTool packages the annotated fragment, document head styles, and client bundle as a text/html;profile=mcp-app resource. The matching MCP tool automatically advertises its generated ui:// resource. Connect an MCP Apps-compatible host to the /mcp URL printed at startup; the model supplies tool arguments and receives structured data, while HTMLTool supplies the interface. The tool advertises the generated ui:// resource through _meta.ui.resourceUri.

Define the element with the native Custom Elements API. The complete client bundle is included, but only elements present in the extracted fragment connect and mount:

customElements.define("greeting-card", class extends HTMLElement {
  connectedCallback() {
    this.addEventListener("htmltool:result", (event) => {
      const result = (event as CustomEvent).detail;
      this.render(result.structuredContent);
    });
  }

  render(value: unknown) {
    this.querySelector("output")!.textContent = JSON.stringify(value);
  }
});

HTMLTool buffers the official MCP input/result payloads until the element is defined and connected, then dispatches them in order as bubbling htmltool:input and htmltool:result events. An element that is not defined within five seconds displays a mounting error.

Existing createClient() calls also work inside the MCP App. HTMLTool transparently routes every rpc() and mcp() method through an MCP tool marked app-only, including async iterables, while the standalone browser continues using WebSockets. App-only visibility is enforced by compliant hosts; HTMLTool's local HTTP/MCP endpoint has no authentication, so do not bind untrusted interfaces.

Local stylesheets, CSS imports and URLs, images, fonts, and media are bundled as data URLs; remote assets are rejected. Bundles are limited to 256 assets, 10 MiB per asset, 25 MiB of source assets, and 40 MiB per generated app document.

For local process-spawned integrations, serve MCP and MCP UI over stdio:

htmltool /absolute/path/to/tool.html --stdio

Stdio mode starts no HTTP server or browser and reserves stdout for JSON-RPC. Console methods are redirected to stderr; server code must not write directly to process.stdout. Tools, ui:// resources, UI input/result events, and app-only createClient() calls use the host's MCP connection. Configure a compatible host with "command": "htmltool" and "args": ["/absolute/path/to/tool.html", "--stdio"].

Zed needs a project-aware embedded TypeScript patch for imported types and package resolution. See Zed setup for HTMLTool.

Obsidian plugin

The desktop-only Obsidian integration makes Obsidian the file host for HTMLTool:

• Opening an .html file with one valid HTMLTool manifest starts htmltool and renders its loopback URL in an Obsidian pane.

• Closing or navigating away from the pane stops the child process.

• Ordinary HTML receives a source preview instead of being executed.

• The vault path is passed as HTMLTOOL_VAULT, so tools can work with vault content without hard-coded paths.

Build and install the plugin into a local vault:

cd integrations/obsidian
bun install
bun run check

plugin_dir="/path/to/vault/.obsidian/plugins/htmltool"
mkdir -p "$plugin_dir"
cp main.js manifest.json styles.css "$plugin_dir/"

Enable HTMLTool under Settings → Community plugins, then set and test the executable under Settings → HTMLTool. The plugin requires Obsidian desktop and a local filesystem vault; Obsidian mobile cannot launch the HTMLTool process.

Open Loops example

cd tools
bun install
bun run start -- --vault "$HOME/Documents/Obsidian Vault"

The UI is served at http://127.0.0.1:7331/, browser RPC at /.htmltool/rpc, and MCP Streamable HTTP at /mcp.