CLI and MCP server

huellup is a companion CLI (and MCP server) for working with a docs/ folder outside the dashboard — scaffold one, validate it before pushing, preview it locally, or let an AI coding agent write it for you.

Note

This is entirely optional. Nothing about connecting a repo or uploading a docs.zip requires it — it just makes authoring docs locally faster, and gives AI agents a correct, structured way to generate them.

Commands

Every command below works with a bare npx huellup ... (fetches from npm each time, nothing installed permanently), or install it once and drop the npx:

npm i -g huellup

huellup init [dir]command

Scaffolds a new docs/ folder (defaults to ./docs) with an example docs.json, an introduction.mdx, and a getting-started/installation.mdx — a minimal starting point that already validates cleanly.

npx huellup init

huellup validate [dir]command

Checks a docs/ folder for errors before you push or upload it — runs the exact same migration Huell’s build worker runs, against a scratch directory, so a clean result here means the real build will succeed too. This includes a broken-link check: an internal link to a page that doesn’t exist is a warning by default, but a link to localhost or any local address always fails validation outright, since that can never resolve for a real reader.

npx huellup validate ./docs
npx huellup validate ./docs --strict   # also fail on warnings, not just errors

huellup preview [dir]command

Runs a hot-reloading local preview of a docs/ folder, so you can see exactly what it’ll look like before publishing.

npx huellup preview ./docs

Tip

preview ships its own bundled copy of the docs-site template — a plain npm install -g huellup (or npx huellup preview) works standalone, with no Huell repo clone required.

huellup mcpcommand

Starts an MCP server over stdio — not something you run directly, this is what an AI coding agent’s config launches for you.

Using the MCP server with an agent

Add this to your agent’s MCP server config (Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP):

{
  "mcpServers": {
    "huellup": {
      "command": "npx",
      "args": ["-y", "huellup", "mcp"]
    }
  }
}

npx fetches the package from the npm registry the first time it’s used — no cloning this repo, no global install.

What the agent gets

docs-json-schema (resource)huell://docs-json-schema

A full description of every docs.json field, with an example — the same fields documented in Migrating existing docs.

components (resource)huell://components

The list of MDX components available with no import (Note, Tip, Card, Steps, …), including a note that CodeGroup doesn’t yet tab-switch between code blocks.

validate_docs (tool)tool

Takes a path to a docs/ folder, runs the same validation as huellup validate, and returns errors/warnings as structured JSON — lets an agent check its own output before handing it back to you.

Tip

Point an agent at a task like “write me a docs.json and an introduction page for this project” and it can read the schema resource, generate valid MDX using only supported components, and self-check it with validate_docs before finishing — instead of guessing at a format it’s never seen.