Repository navigation
The MCP server
LoreMaster ships a Model Context Protocol server so an AI agent that writes documentation knows how the sync will nest and title its files. Without it the agent guesses: it picks the wrong parent, collides with an existing title or misnames a dotted file, and the page lands in the wrong place on Confluence. Tracked in the epic #211.
In the engine, as a second mode of the same binary: lore-master-engine --mcp. It speaks
newline-delimited JSON-RPC 2.0 on stdio, which is both what the engine already does for the
editor shells and what the MCP stdio transport is. It is a small hand-written server in the
mcpserver slice (tools only; no resources or prompts yet) rather than a dependency, and
that choice can be revisited if the tool surface grows (#212).
VS Code ───registers───▶ lore-master-engine --mcp --workspace <folder>
external client ─config─▶ │
├─ mcpserver protocol + the six tools
├─ markdown-workspace discovery, parsing, the nesting rules
└─ workspacesettings .lore-master.yaml: roots, excludes, ignore
The invariant: what the MCP states is exactly what the sync enforces. The tools do not restate the rules; they call the code that applies them.
- The rules text comes from
documenttree.NestingConventions(), which sits besideNestingPolicy, the code that places pages. Change one and the other is changed in the same file. -
preview_tree,validate_documentandplace_documentload the workspace through the same discovery (documentdiscovery, driven by the.lore-master.yamlroots, excludes and ignore list) and build the tree with the samedocumenttree.BuildTreethe sync uses.
So the advice cannot drift from the behaviour, and a .lore-master.yaml change shows up in
the tools without any MCP-side edit.
| Tool | Input | Returns |
|---|---|---|
loremaster_nesting_rules |
none | The rules in the order they apply, as readable text and as structured conventions (key, summary): explicit parent:, dotted file name, directory index, selected parent, then titling (H1, <titlePrefix>: <title>, per-space uniqueness). |
preview_tree |
none | The pages the sync would create, as a tree: each page's file, title, parent and the rule that placed it, plus discovery and parse notes. |
validate_document |
path (required): workspace-relative path to a Markdown file |
Where the file will nest and why, whether its title clashes with another page, whether it lacks an H1, and whether the sync includes it at all. |
site_publishing_plan |
none | How the repository deploys to GitHub Pages (from its workflows) and the setting that puts the docs site beside it: the approach (build, publish into a path, or publish-root), the .lore-master.yaml output and workflow step to use, and warnings. Detection and recommendation are the pure sitedeployment lib. Writes nothing. |
preview_site |
output (optional): position of the github-pages output |
Renders the site in memory through the same code as pages build: page and file counts, the file list, Markdown problems and warnings. Writes nothing. |
place_document |
h1 (required); parent (optional): a page title or workspace-relative file path; directory (optional): workspace-relative directory |
The file path, and any annotation, that nests a new page under the chosen parent. It writes nothing; the agent creates the file. |
The three workspace-aware tools need the workspace root. Without one they return a tool error saying so, and the rules tool still works.
A tool that fails for an operational reason returns a normal result with isError set, so
the model reads the explanation and can react; only a malformed call is a protocol error.
-
In VS Code the extension contributes an MCP server definition provider
(
loreMaster.engine) that launches the bundled engine with--mcp --workspace <the open folder>and re-advertises it when the workspace folders change (#215). -
Elsewhere the "LoreMaster: Copy MCP Server Config" command puts a ready-to-paste
mcpServersentry on the clipboard, pointing at the same engine binary and workspace (#216).
Usage steps are in Using the MCP server.
- Rules plus workspace-aware tools, not rules alone: an agent that can see the tree and preview a placement makes fewer mistakes than one that only reads prose.
- Auto-registration in the editor, copy-config outside it: zero setup where the user is already inside LoreMaster, one paste elsewhere.
- No new binary and no npm package: the engine ships inside the extension already, and distribution stays the Marketplace only.
-
LoreMaster documentation
- A documentation agent that follows the LoreMaster structure
- ADR: One Go engine, thin editor shells
- ADR: Vertical feature slices, in Go and TypeScript
- Choosing what goes where
- Command line
- Confluence editions: the facts the design rests on
- Confluence tenant for recorded fixtures
- Generators: pages written from your project's artifacts
- Getting started: syncing a workspace to Confluence
- GitHub Action: the docs site in one step
- Publishing to a GitHub wiki
- The MCP server
- Two-way sync: pull remote edits back, conflict when both sides change
- Using the MCP server
- Watch mode