Podlite for your AI agent
a parser your agent can call
Add the writing and verification skills, and connect the MCP server. Your agent can parse source text, select blocks, render output, and run validation.
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 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:
| Call | You give it | You get back |
|---|---|---|
podlite_parse | Podlite source | a tree of typed blocks, each with a start and end position |
podlite_validate | Podlite source | a report: ok, counts, and the problems found |
podlite_render | Podlite source | HTML or Markdown |
podlite_query | Podlite source and a selector | the blocks that match |
Each tool receives source text. Validate, render, and query also accept a map of file paths to text.
podlite_validate returns syntax, lint, and AST schema findings. ok is true
when the report contains no errors.
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
Select a code block and check the document. Call podlite_query with the
selector code[:lang<js>] and JSON output. You get one block: name code,
attribute lang js, with its start and end position. Call
podlite_validate on the same source. You get ok: true and no problems.
Leave out an end marker, for example the end of a table, and
podlite_validate returns ok: false and names the open block and the line
where it begins.
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 start and end position. An agent can select a block by name and attributes instead of searching the text.
Attributes come back as the author wrote them — who marked a decision, what state it carries, when it changed. Attributes store the values written in the document.
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.