Podlite for your assistant
two commands, and your assistant stops guessing
Two commands — a writing skill and an MCP server — give a coding assistant a real Podlite parser instead of a pattern match.
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.
Assistants make that mistake constantly, and for the same reason — they match shapes. The skill teaches your assistant how Podlite is written; the server hands it the parser.
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
| Piece | What it does | Runs where |
|---|---|---|
podlite-skills | teaches the assistant how to write Podlite | in the agent |
@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 assistant 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:
| 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 assistant 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.
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 assistant 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 assistant 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 assistant 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 corpus, and it does not search documentation on its own. Connecting it does not make your assistant know Podlite's docs, or yours, or anyone's — it makes your assistant 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 corpus instead of a file. @podlite/mcp works on text you hand it. If you
want an assistant that already holds a body of documents 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.