Podlite for your AI agent

a parser your agent can call, instead of a guess

Two pieces — a writing skill and an MCP server — give a coding agent a real Podlite parser it can call, so it checks the structure of a document instead of matching its shape.

Guessing is the normal state, and it is subtle. While writing this page I put a three-line example in it and described what a parser would say. The parser said something else: the heading had swallowed the sentence underneath it. I had read the example several times without seeing it.

Agents make that mistake constantly, and for the same reason — they match shapes. The skill teaches your agent how Podlite is written; the server hands it the parser. Checking structure is not the same as being right about the content, and this page claims only the first.

Install

Add the writing skill. It travels with your agent and needs no server:

npx skills add podlite/podlite-skills

Add the parser as an MCP server. Put this in your MCP client config — Claude Code, Cursor, and other MCP-compatible tools read the same shape:

{
  "mcpServers": {
    "podlite": {
      "command": "npx",
      "args": ["-y", "@podlite/mcp"]
    }
  }
}

Nothing is installed globally. npx fetches the package on first run.

What each piece gives

Two pieces, two jobs
Piece	What it does	Runs where
`podlite-skills`	teaches the agent how to write Podlite	with the skill
`@podlite/mcp`	parses, checks, renders and queries the text	as a server

The skill is instructions. The server is a program. The skill helps the agent produce markup; the server tells it whether the markup is real.

What the server actually does

Four operations, each over source text you hand it. The package README is the reference for exact arguments; this is the short version:

The four calls
Call	You give it	You get back
`podlite_parse`	Podlite source	a tree of typed blocks with line and column
`podlite_validate`	Podlite source	errors with positions, or nothing
`podlite_render`	Podlite source	HTML or Markdown
`podlite_query` source	selector the blocks that match

Check it worked

Ask your agent a question it could not answer before:

Parse this and tell me where every heading starts:

=head1 Setup

Install the thing.

=head2 Windows

The parser answers: head at line 1, level 1; a paragraph at line 3; head at line 5, level 2. If you get line numbers, the server is connected.

Or hand your agent the whole check at once — paste this:

Use the podlite MCP server to parse the document below. Tell me, for every
block: its type, its level if it has one, and the line it starts on. Name the
tool you called.

=head1 Setup

Install the thing.

=head2 Windows

Asking it to name the tool is the point: an agent that answers without calling anything is answering from its training, and that is the guess this page is about.

The blank lines matter, and this is the first thing the server buys you. Drop the one after =head1 Setup and the heading swallows the sentence below it — the abbreviated form runs until a blank line. An agent guessing from shape will not warn you. The parser reports a heading whose text is Setup Install the thing., and the mistake is visible before it ships.

What the agent gets that it did not have

A parse tree, not a string. Each block arrives with its type, its attributes and its position in the source. An agent editing a document can find the third code sample under a named section and leave the rest untouched, because it knows where the boundaries are.

Attributes come back as the author wrote them — who marked a decision, what state it carries, when it changed. That is a record of what the author declared, not proof that they wrote it.

What this does not do

The server works on text you send it. It does not hold a document collection, and it does not search documentation on its own. Connecting it does not make your agent know Podlite's docs, or yours, or anyone's — it makes your agent able to handle Podlite text correctly when that text is in front of it.

Knowing a body of documents is a different job, done by a different server.

Two doors from here

A collection instead of a file. @podlite/mcp works on text you hand it. If you want an agent that already holds a document collection and can search it, the Raku knowledge base runs its own server over an entire ecosystem's documentation — kept in Podlite, with the three commands on its own page.

Writing your own. The first step is connecting a parser, not learning a syntax. The language comes second, and only if you decide to write documents yourself: it is written down in the specification.