Typst Agent Toolkit

Typst Agent Toolkit gives AI coding tools a focused Typst authoring workflow and live access to Typst's official documentation. It includes:

• a Pi typst_docs extension with a compact custom TUI renderer;
• a reusable Typst authoring skill for Pi;
• a stdio MCP server exposing the same typst_docs search and page-reading tool.

This toolkit is not affiliated with, endorsed by, or maintained by Typst GmbH or the Model Context Protocol project.

Independent projects: this repository supports a workspace of independent Typst document projects. It does not turn sibling document directories into one codebase or impose shared version control on them.

Prerequisites

• Node.js 20 or newer
• Git
• npm (included with Node.js)
• Pi, only when using the Pi extension and skill

Typst, Typstyle, and Tinymist are useful for document work but are not required by the documentation server.

Install in Pi

Install the package directly from its Git URL:

pi install https://git.dikka.dev/lab/typst-agent-toolkit.git@trunk

trunk is the moving pre-release branch. No release or version tag is claimed here; after a version tag is published, prefer that tag in place of trunk for a reproducible install.

Run /reload in Pi after installing or after changing a locally loaded extension or skill. Do not reload an active session from automation on someone else's behalf.

Use from VS Code via MCP

Create .vscode/mcp.json in the document project:

{
  "servers": {
    "typst-docs": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "--yes",
        "--package=git+https://git.dikka.dev/lab/typst-agent-toolkit.git#trunk",
        "typst-docs-mcp"
      ]
    }
  }
}

This pre-release configuration asks npm/npx to download and cache the Git source, run its prepare build, and execute typst-docs-mcp. It does not install a publication from the npm registry; package.json is deliberately marked private: true to block registry publication. Replace trunk with a published version tag when one exists.

The stdio server accepts only stateless MCP (2026-07-28). It rejects the legacy stateful initialize handshake, so the host must support modern per-request metadata and server/discover negotiation.

The MCP tool accepts:

• query (required): a Typst concept, function, parameter, or documentation question;
• limit (optional, 1–10; default 5);
• includeContent (optional; default true) to fetch an excerpt from the best result.

Search results link only to https://typst.app, and fetched page text is capped at a 14,000-character excerpt.

Development

From this repository root:

npm install          # installs locked dependencies and runs prepare
npm run build        # compile src/ into dist/
npm run check        # TypeScript typecheck
npm test             # build and run the focused Node test suite
npm pack --dry-run   # inspect the package payload without publishing

The shared implementation lives in src/typst-docs.ts. Both extensions/typst-docs.ts and the built MCP executable use that core; do not duplicate its search, ranking, network, or HTML extraction logic.

Local Typst preview workflow

The repository also retains its local workspace helpers. From the parent Typst workspace:

# Concurrent Tinymist preview; prints a temporary .localhost route
./tin my-document/main.typ

# Choose a route or skip local-router integration
./tin --route annual-report my-document/main.typ
./tin --no-router my-document/main.typ

From a document project:

typst compile main.typ
typst watch main.typ
typstyle --inplace main.typ
bash ../.pi/skills/typst-authoring/scripts/render-pages.sh main.typ

Adjust the relative .pi path for more deeply nested projects. Current local setup pins Typst CLI 0.15.1, Typstyle 0.15.0, and Tinymist 0.15.2 in scripts/update-tools.sh; update those values deliberately because Typst language upgrades can change document behavior.

License

MIT. See LICENSE.