Getting started

Create, run and test your first Quartal Plugin in a few minutes.

Requirements

  • Node.js 20+
  • We recommend MCPJam for local testing, especially for widgets.

Create a plugin

pnpm create @quartal/plugin

Coding agents and CI can skip the prompts — every question has a flag, and --yes accepts the defaults for the rest:

pnpm create @quartal/plugin my-plugin --yes

Flags: --description <text>, --auth / --no-auth, --sample-tool / --no-sample-tool, --widgets none|vue|react|js (with npm, pass flags after --: npm create @quartal/plugin -- my-plugin --yes). There is also a ready-made prompt for your coding agent on the front page, and the docs are indexed for agents at /llms.txt.

Alternatively, fork the template repository at quartal-hub/plugin-template.

Run it

pnpm install
pnpm dev

Your plugin is an Astro project running on http://localhost:4321, serving:

URL What
/ Documentation site for your plugin (tools, widgets, skills, API testers)
/mcp The MCP server — connect any MCP client here
/api/<Class>/<method> The generated OpenAPI / REST actions
/plugin.json The Agent Plugins manifest (/plugin.zip is the installable package)
/widgets/<toolId> Your widget pages
/skills/catalog.json The Agent Skills catalog

The full endpoint list is in the HTTP endpoints reference.

Make it yours

  1. Add a tool: create a class in src/tools/ and export it from src/tools/mod.ts — see Creating tools.
  2. Add a widget for a tool: create a page in src/pages/widgets/ — see MCP Apps widgets.
  3. Add a skill: create a folder with a SKILL.md under skills/ — see Agent Skills.

Test with an MCP client

Point MCPJam (or Claude, or any MCP client) at http://localhost:4321/mcp and try your tools live.

Deploy

Build and run like any server-output Astro site — then deploy to any modern hosting platform:

pnpm build
node ./dist/server/entry.mjs