Enables AI agents to perform precise, block-level reads and writes on Markdown and GEML files to prevent context bloat and semantic drift.
Also known as geml-spec/geml, geml, @geml/geml
- Stars
- 31
- Tools
- 9
- Downloads, 30 days
- 2,120
- Latest version
- 1.13.1
- Last commit
- Nov 11, 2026
- License
- MIT
What is GEML MCP?
GEML enables AI agents to perform precise, block-level reads and writes on Markdown and GEML files to prevent context bloat and semantic drift. It exposes 9 tools, such as geml_list, geml_find, geml_get.
Summary generated from the project's README
About GEML MCP server
GEML provides a specialized markup language designed for high-precision document manipulation by AI agents. It addresses the limitations of Markdown and JSON by offering a system where documents are treated as collections of addressable, named blocks. This allows an agent to target a specific section, table cell, or metadata key without needing to process or rewrite the entire file. By focusing on individual blocks, the server helps prevent context window bloat and semantic drift during multi-turn editing sessions.
Developers can use this server with existing Markdown files without any conversion, utilizing commands like geml list, geml get, and geml set to interact with sections via unique identifiers. For more complex structural needs, the .geml format allows for fine-grained editing of charts, tables, and code blocks. The system includes a history mechanism that saves revisions to a .gemlhistory file, enabling atomic rollbacks of single blocks rather than entire documents. This makes it an ideal tool for automated knowledge work and agent-driven development workflows.
What you can do with it
- 1Perform precise data updatesA developer can instruct an agent to update a specific cell within a table or a single leaf in a JSON-like structure using coordinates.
- 2Maintain document integrityUse the history feature to revert a single incorrect edit made by an agent without losing other changes in the file.
Written from the project's README. Every use case is checked against a quote from it.
How to install GEML MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall GEML MCP in Claude Code
$ claude mcp add geml -- npx -y @geml/geml mcp --root /path/to/folderInstall GEML MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"geml": {
"command": "npx",
"args": [
"-y",
"@geml/geml",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Install GEML MCP in VS Code
.vscode/mcp.json
{
"servers": {
"geml": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@geml/geml",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Install GEML MCP in VS Code CLI
$ code --add-mcp '{"name":"geml","type":"stdio","command":"npx","args":["-y","@geml/geml","mcp","--root","/path/to/folder"]}'Install GEML MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"geml": {
"command": "npx",
"args": [
"-y",
"@geml/geml",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Install GEML MCP in Codex
$ codex mcp add geml -- npx -y @geml/geml mcp --root /path/to/folderInstall GEML MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.geml] command = "npx" args = ["-y", "@geml/geml", "mcp", "--root", "/path/to/folder"]
Install GEML MCP in Gemini CLI
$ gemini mcp add -s user geml npx -- -y @geml/geml mcp --root /path/to/folderInstall GEML MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"geml": {
"command": "npx",
"args": [
"-y",
"@geml/geml",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @geml/geml 1.13.1 in an isolated container with no network and no keys. It answered and listed 11 tools.
GEML MCP tools 9
Read from the server with tools/listgeml_listRead-onlyList every addressable block in a GEML document — its address, kind and heading text — in one call, with no paging. Call this FIRST: what it returns is what every other tool here addresses, and it is cheaper and more reliable than reading the file to see what is in it. Rows marked `anon` have no `#id`; geml_get and geml_set take their `address` as `id`, while the other write tools need a real id, so give such a block one first. A file that is not under the server root is an error. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_findRead-onlySearch block CONTENT in the document; each hit is one `<name>\t<address>` row. geml_list says what a document contains, this says which block holds the words — as an address that pastes straight into geml_get or geml_set, not a line number the next edit invalidates. The address is the innermost block holding the match, and a block matching on many lines is reported once. Substring, case-insensitive unless `case` is true. No match is an empty result, not an error. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_getRead-onlyRead ONE block from a GEML document instead of the whole file: only that block comes back, typically a few percent of the document. Pass the `address` geml_list prints as `id` — it also reaches blocks with no `#id`; to locate a block by its words instead, use geml_find first. An `id` that matches nothing, or a file that is not under the server root, is an error naming it. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_checkRead-onlyValidate a GEML document without changing it: returns every diagnostic with a stable `code`, a severity and a line, and an empty list means the document is valid. Use it to confirm a document is sound before reporting work as finished. Every write through this server runs the same check before it lands, so a refused write already carries this information. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_toRead-onlyConvert a WHOLE document and get the result back as text — the read half of the CLI's `geml <file> --to <fmt>`. `to: "geml"` on a Markdown file is the importer, the one thing the block tools cannot do; `to: "md"` projects a GEML document out (lossy); `to: "json"` returns the full document model, for when geml_list plus geml_get is not enough. Nothing is written — pass the result to geml_add or geml_set to land it. `to: "html"` also works but returns a whole self-contained page, usually tens of kilobytes this server cannot save: prefer the CLI (`geml <file> --to html -o out.html`) unless you want the markup in the conversation. A document with errors returns its diagnostics instead of a conversion, and a file that is not under the server root is an error. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_setActionReplace ONE block and leave every other byte untouched — prefer this to rewriting a file. For content that does not exist yet use geml_add; to remove a block, geml_delete. The replacement is validated before it is written: if it would break the document, nothing is written and the diagnostics come back — fix the body rather than resending it. Removing content is not refused: if the replacement drops blocks, the write goes through and the result names each one, so check it after shortening a section; geml_revert puts one back. `part` replaces the whole block (default), its head line, a section's `intro`, or its body. In a Markdown file a heading's anchor is its text, as on GitHub: new heading text gives the heading a new address, and the document's links to the old one follow in the same write. GEML content written over a Markdown heading or prose is converted to Markdown, as in geml_add; a GEML block already in the file stays GEML. An `id` that matches no block, or several, is refused. Returns `{ok, file, diagnostics, revision}`, with `notes` when the write did something to say out loud (a block it dropped, an address it changed); a refusal is `ok: false` with a `hint`, and the file is unchanged. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_addActionInsert new content — one or more blocks, or prose — at the end of the document (`position: append`) or before/after the block named by `anchor`. Use this for content that does not exist yet; to change a block that does, use geml_set. Ids inside the content are kept. In a `.md` file Markdown lands as written, and GEML content is converted to Markdown as `to: "md"` converts it, the result's `notes` saying so; content Markdown cannot hold, such as a view without its source, is refused. Like every write here it is validated first: a missing anchor, an id that clashes with an existing one, or content that would break the document is refused. Returns `{ok, file, diagnostics, revision}`, with `notes` when the write did something to say out loud (a block it dropped, an address it changed); a refusal is `ok: false` with a `hint`, and the file is unchanged. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_deleteActionRemove one or more blocks, each named by an id or any address geml_list prints; a filter (`=== type`, `{key=value}`) removes every block it matches. Each block takes the blank line that separated it from its neighbours, so deleting what geml_add inserted leaves the file as it was. To undo a deletion, geml_revert the removed id; to change a block rather than remove it, use geml_set. References left pointing at a removed block come back as diagnostics but do NOT block the deletion — read them, then repair the references or revert. A selector that names nothing is skipped, so repeating a call changes nothing. Returns `{ok, file, diagnostics, revision}`, with `notes` when the write did something to say out loud (a block it dropped, an address it changed); a refusal is `ok: false` with a `hint`, and the file is unchanged. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
geml_renameActionRename a block id AND every reference to it in the same document, in one id-boundary-safe write. Use this rather than geml_set or a text search-and-replace, which would also hit ids that merely share a prefix. A Markdown heading's anchor is its text, so it is renamed by changing the heading with geml_set (`part: head`), not here. An `old` id that does not exist, or a `new` one already taken, is refused. Returns `{ok, file, diagnostics, revision}`, with `notes` when the write did something to say out loud (a block it dropped, an address it changed); a refusal is `ok: false` with a `hint`, and the file is unchanged. This server is STATELESS: the document travels in `source` and a write comes back as `document` for you to save; it holds no other documents, so a cross-document reference such as `[[other.geml#id]]` cannot be resolved here and is reported as `unresolvable-document`.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablegeml-spec/geml is public and reachablegithub.com/geml-spec/geml ↗Pass
- Package names this repository as its source@geml/geml names geml-spec/geml as sourcenpmjs.com/package/@geml/geml ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @geml/gemlnpmjs.com/package/@geml/geml/v/1.13.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/geml-spec/geml ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @geml/gemlPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-11-25 in 101 ms; tools/list returned 9 toolsPass
README
View on GitHubGEML — General Expressive Markup Language
English | 中文
GEML is a lightweight markup language with uniform, addressable blocks and standard verbs. Easy for humans to read, safe for agents to mutate. In agent-driven development and knowledge work, plain text and Markdown have no deterministic block boundaries: a program and a model trade the whole file in and the whole file back out — at best probing for it with line windows, and restating the original verbatim to rewrite it. Token cost grows with the length of the document, and the operation turns bloated. After a few rounds of rewriting, the copies excerpted elsewhere start to drift.
Contents: What it solves · What an LLM needs · What's different · The format in 1 minute · Profiles · Get hands-on · With an LLM · Maturity & versions · The design · Roadmap · Take part · License
You can start without changing a thing. geml list, geml find and geml get address the Markdown you already have — nothing is converted, no new files, your .md stays .md:
geml list README.md # every section, as an address
geml get README.md '#key-features' # read ONE section, not the file
geml set README.md '#key-features' --body # write one section back
geml replace README.md 'old text' 'new text' # swap a string, told which block held it
geml history save README.md -m 'tighten intro' # a revision into README.md.gemlhistory, beside the file
Only that section enters the agent’s context — a couple of KB, not the whole file, however long it grows. And every save is a revision you can read back or roll back, one block or the whole file.
▶ Try it in the Playground — no install, nothing to read first.
Need finer than a section — one block, one chart, one table? Let .geml stand in the middle ground: edit at that grain, and the --to md you ship never drifts from it.
A block has a name; the things inside it have a coordinate. A table's cell, a
data block's leaf, a key in meta — each has a coordinate the structure already
gives it, and get and set land on exactly that value.
geml get doc.geml '#fy[2]["Q1"]' # one cell
geml set doc.geml '#intake["fields"][1]["name"]' # one leaf in the JSON
For people, it is plain text that reads clean; for agents, it is an addressable, verifiable, traceable, revertible "Doc-as-a-Base".
GEML is minimal. It is plain text — still clean with no renderer in sight; one block syntax for the whole language; addressable, verifiable, referenceable structure, natively.
Instead of a separate mini-syntax for each kind of content, GEML carries every kind in one container: the typed block. Code is a block. So are tables, diagrams, math, callouts, even metadata — and a run of prose can be one too (=== text), whenever you want it addressable. Extending it later is just as plain. The shape is the same every time, which makes the language easy enough to learn that it's hard to get wrong.
Blocks have names so the verbs have somewhere to land — the full syntax is in the format in 1 minute.
What it solves
Problems solved
- Context load and token bloat: JSON/XML carry heavy wrapper syntax, and Markdown lacks structural metadata and references; GEML reads and writes only the target block, so context cost stops growing with document length.
- AST-level precision and parsing determinism: unstructured text degrades over rounds of LLM reads and writes — broken formatting, semantic drift; GEML's deterministic grammar maps to an AST, so programs and LLMs create, read, update and delete one block at a time.
- Document copy fragmentation: multi-agent work and shared pipelines pass content around by copy-paste, leaving copies that drift apart; GEML is built around a single source of truth, with standard references and data binding in place of copies.
Key features
- AST-level structured operations: a document parses into a typed tree; an agent pinpoints its target and patches it in place, idempotently. Writes land as byte splices with whole-document re-validation, and every untouched byte stays as it was.
- Low-token reads and writes: what is saved is not markup characters but the part never read —
#idhits one semantically complete block, and the rest never enters the context. - Single source of truth, modular references: native cross-document, cross-fragment references; change the source once and every reference follows.
- Robust two-way reads and writes: one block shape for the whole language, easy to generate and hard to get wrong; a strict validator with precise error locations and repair feedback.
- Profile-based domain extensibility: declare a
profilein=== metato add a domain vocabulary (design styles, forms, code graphs, media timelines) without new syntax; a declared vocabulary is checked by its own checker, with safe fallback to standard blocks in unknown environments.
What kind of text format does an LLM need?
Text in the AI era is "produced by models, read by people and models together".
Reading together means readability cannot be traded away; and when models settled on Markdown, it was a compromise made for want of anything better, not the final answer.
A text format built for people and models working together should change what reading and writing feel like for the machine:
- Fine-grained: address precisely by block, and by coordinate inside it — no more scanning the whole file;
- Structured: better organized, more flexible in what it holds;
- Consistent: one standard read/write interface, with other modalities extending it naturally;
- Zero barrier: minimal mental load, and a smooth, near-zero-cost migration.
Yet none of our existing text infrastructure was designed for this scene:
- Markdown (typeset for people): no stable structural blocks, no machine keys. To change one parameter, an agent must read and write the whole text — wasting context budget across multi-turn loops, and inviting drift in both format and meaning.
- JSON / XML (serialized for machines): full of wrapper syntax and structural noise — blocking natural human reading, while quietly eating expensive tokens in long contexts.
- Scratch memory and scattered files (no single source of truth): context is torn across chat history and Markdown copies everywhere; a copy is drift from the moment it is made, and version skew and hallucinated distortion follow.
The root of all three failures is each tool's own virtue: Markdown's "never error, write anything" is what gives people their freedom to write — and exactly why a machine cannot trust the structure it reads back; JSON/XML's strict schema is what gives machines their certainty — and exactly why nobody writes prose in it. The virtue is the defect, which is why patches cannot fix this: bolting "a broken reference must fail the build" onto Markdown betrays its contract, and stripping the wrapper syntax from JSON denies its nature. When people and agents start co-writing the same text at high frequency, what is needed is not a compromise between the two poles, but a format that treats "readable by people" and "operable by machines" as one design constraint from day one.
The answer: "Doc-as-a-Base"
GEML is a new format, but the wine is old: enhancing and unifying Markdown-style expression, stripping away HTML-style presentational syntax, and the idea of fenced blocks come from Markdown, #ids and embeds from XML and AsciiDoc, inline projection from Obsidian, and the verbs from the REST architectural style of Dr. Roy Fielding's dissertation. What is new is one block container for all of them. It is a little like TypeScript to JavaScript — the syntax can't be compatible, but list, get, set, add and delete already work on the Markdown you have. That container gives plain-text documents one standard set of operational semantics:
| Old pain | The matching capability (the four laws) | What it buys developers and agents |
|---|---|---|
| Changing one spot means rewriting the whole text | The Law of Addressing | Every block carries an #id; get/set reads and writes that block alone. What is never loaded cannot be broken — the context window stays yours. |
| Copies everywhere, all drifting | The Law of Projection | === embed evaluates dynamically instead of copy-pasting; one definition at the source ends the labor of syncing copies. |
| Bad formats / broken references pollute downstream | The Law of Validation | References and syntax are checked at build time; a bad write is stopped before it lands, with no waiting for human review. |
| One bad edit forces a whole-file rollback | The Law of Rollback | The companion .gemlhistory reverts a single block atomically — no tearing down the page; a lightweight version safety net for agents. |
A document no longer needs just a format — it needs a set of verbs. GEML keeps plain-text readability and adds deterministic block-level operations. The dilemma of engineering documents in the LLM era, and why these old practices belong in one new block container, is argued in full on the blog: "Why Do We Need a New Text Format in the Era of LLMs?"
What's different about GEML
Where each format lands on the four capabilities of the last chapter — addressing, projection, validation, rollback — is the table below; GEML stays small on purpose, and what it refuses is in how we thought about the design.
How other formats compare
Each of the four has mature solutions in its own field; what's unusual is meeting all four in one plain-text format:
| Family | What the state really is | Addressable / referenceable | Projectable / embeddable | Verifiable | History / traceability |
|---|---|---|---|---|---|
| Word / Docs | Opaque state | ❌ No block-level keys; access via platform APIs | ❌ Copy-paste only | ❌ No checking at all | ⚠️ Platform server-side, not in the file |
| Markdown / AsciiDoc | A stream of characters | ⚠️ Heading anchors or dialect ids; no read/write verbs | ⚠️ Dialect embeds (Obsidian ![[…]], include::) — break silently |
❌ Broken links fail silently | ❌ None in-format — external git required |
| JSON / XML | Data serialization | ✔️ (id / schema) | ⚠️ XML only (XInclude, external) | ✔️ Via an external toolchain | ❌ None in-format — external git required |
| GEML | Plain text + block structure | ✔️ A unique #id per block (referenceable natively) |
✔️ === embed: a reference is a lookup (native) |
✔️ A build-time error | ✔️ .gemlhistory next to the file (traceable natively) |
Item by item: vs. CommonMark · vs. XML and JSON · a 7-format capability matrix · the Markdown variants and tools in awesome-markdown (Chinese, an HTML page).
Coexisting with Markdown: GEML is the editing source of truth, Markdown is the delivered artifact. Project one way with geml <file> --to md|html and ship .md or .html as before. Collaboration, not lock-in. (Projection is lossy: block ids and table-bound charts don't survive it.)
Don't take the table's word for it — re-run it. This is what I asked the model:
Based on your own experience editing the READMEs just now, describe the command steps you go through on a document (I saw you using grep and such), and whether you cache documents to save tokens — let's compare, and from that see which parts of GEML would actually earn their place.
What came back: what one edit costs and a real day replayed. Paste the question to your own model and see what it tells you.
PS: I am still trying to work out whether the upstream chain (who calls this) and the downstream chain (what it calls) that codemap produces can pin down functions and call sites — and change project code — the same way. I will post a report when I have one.
The format in 1 minute
Typed blocks
One shape, every type. A block's basic syntax is === type [attributes] … === (where attributes like {#id .class key=val} are optional) — only the type (and how its body is read) changes:
=== code {lang=python}
print("hi")
===
=== note {.intro}
Parsed prose with *emphasis* and a [[#budget]] reference.
===
=== meta
title = "Budget plan"
===
A run of = (three or more) opens a block; an equal-length run closes it; longer fences nest inside shorter ones. A block that carries an #id can also close with the labeled fence === #id — no fence-length counting, which makes long blocks much harder to get wrong (nesting still requires a longer outer fence: a same-length bare === in the body closes the block early, labeled or not). The type decides how the body is read — raw (verbatim: code, diagram, math, table), flow (parsed prose with inline markup: note, text), or data (one key=val per line: meta); embed carries no body at all — its src= names the block it stands for — and every block may carry an attribute object {#id .class key=val}, where a .class is a semantic label, never a styling hook. The full inline grammar (emphasis, links, [[#id]] auto-references, media, footnotes, inline $math$) is in the spec.
Tables — two bodies, one model
Write a table visually:
=== table {#budget caption="Annual cost"}
| Plan | Months | Rate |
|-------|-------:|-----:|
| Basic | 1 | 30 |
| Pro | 2 | 30 |
===
…or as data. A table holds the facts; a view over it derives the
computed columns and the summary row:
=== table {#fy25 format=csv header=1}
Segment, Q1, Q2, Q3, Q4
Cloud, 8, 10, 12, 14
Platform, 5, 6, 7, 9
Services, 3, 4, 4, 5
===
=== view {#fy25-report src=#fy25 compute="FY [%.1f] = Q1 + Q2 + Q3 + Q4; n = 1" summary="Segment = 'Total'; FY [%.1f] = sum(FY); n = sum(n)"}
===
Both table forms describe the same model. The FY column and Total row are computed at build time, by the view:
| Segment | Q1 | Q2 | Q3 | Q4 | FY | n |
|---|---|---|---|---|---|---|
| Cloud | 8 | 10 | 12 | 14 | 44.0 | 1 |
| Platform | 5 | 6 | 7 | 9 | 27.0 | 1 |
| Services | 3 | 4 | 4 | 5 | 16.0 | 1 |
| Total | 87.0 | 3 |
compute runs + - * / ( ) per row over columns; summary adds a foot row from the aggregates sum / avg / min / max / count (with arithmetic over them, e.g. weighted ratios); a trailing [printf] sets numeric display. n above is the row-count idiom — count tallies non-empty cells in one column, so a constant column summed is what counts rows.
Tables can also pull their data from an external CSV via src="regions.csv".
Math
=== math {#gauss caption="Gaussian integral"}
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
===
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
Diagrams & charts — host a DSL, or chart a table
GEML never interprets a diagram body; it routes it to a pluggable renderer (an unknown format is a warning, body preserved):
=== diagram {#flow format=mermaid caption="Review flow"}
graph LR
A[Draft] --> B{Review} -->|ok| C[Publish]
===
graph LR
A[Draft] --> B{Review} -->|ok| C[Publish]
A diagram can also chart a table — single source of truth, with the column references checked at build time and no data copied:
=== diagram {format=geml-chart data=#fy25-report type=bar x=Segment y=FY}
===
Drawn from the #fy25-report view above — FY is a computed column, so the
chart binds to the view that derives it, not to the base table:
xychart-beta
title "FY by segment"
x-axis [Cloud, Platform, Services]
y-axis "FY"
bar [44, 27, 16]
Data — a value, not just text
Every block type names what it holds: code a region of code, table a grid, math a formula. data holds a data value, and it is where the data formats live — json (the default), jsonl, and yaml for a declared subset; toml reserved. Being typed means the body is read, not just displayed: a missing comma fails the build, geml get --json returns the value itself, and a chart can read it directly.
=== data {#log format=jsonl}
{"ts":"09:00","p95":41}
{"ts":"09:10","p95":58}
===
A jsonl body holds one record per line, which a program can blind-append at end-of-file. Records can also stay in their own file: src=ops/latency.jsonl#L900-999 names the file and, optionally, a line window — so the log keeps being appended and tailed as before, while the document is its verified, addressable, chartable view of it.
Embeds — a dynamic reference, not a copy
One block can stand for another: in the same document by src=#id, across documents by src=other.geml#id. An embed is a dynamic lookup of the source at render time — change the source once and every embed follows; delete it and geml check fails the build on the spot.
=== embed {src=#fy25}
===
The body stays empty; the target lives in src=.
Markdown can't show you the projection. To see it live: install the browser extension, open the raw link to sample.geml, and scroll to the Transclusion section — a same-document projection (src=#roadmap), cross-document projections, and even chained resolution (an embed pulls a chart, which itself binds to a table in another file) all render in place: nothing is written there, yet edit the source once and the projection follows.
Profiles — domain vocabularies, assembled like Lego bricks
Want to author interactive forms, define a design token system, or map an entire codebase's call graph inside your documents?
In traditional Markdown, this requires proprietary plugins (:::note, custom JSX tags), inevitably fracturing into incompatible dialect silos.
GEML solves this with Profiles (Application-layer vocabularies, spec §8.6): A single-line declaration that unlocks domain-specific structured superpowers on demand.
=== meta
profile = "geml-style/v1 geml-form/v1"
===
==== form {#signup handler=subscribe}
=== form-field {name=email label="Work email" type=text required pattern="[^@]+@acme\\.com"}
===
====
=== style-rule {#cta match="button.cta" bg="{{brand}}" radius="6px"}
===
Extension without fragmentation
- 🧩 Mix & match like Lego bricks: the core syntax stays minimal and frozen, while domain vocabularies grow beside it; call graphs, design tokens, form validation, version history... compose several of them with one
profile = "..."line. - ⚡ No plugin to write, the tooling already there: adding a new domain block requires no parser fork and no custom plugin; it gets the same infrastructure as every other block — deterministic
#idaddressing,geml get/setblockwise mutation, CLI verbs, MCP protocol, and autonomous AI Agent control. - 🛡️ Naturally portable, never locked in: extend capabilities without breaking interoperability; a processor that doesn't know a profile still reads every block and addresses it by its
#id, so a document keeps its structure when it moves to another tool.
GEML MCP questions
How do I add GEML MCP to Claude Code?
Run claude mcp add geml -- npx -y @geml/geml mcp --root /path/to/folder in your terminal. Add --scope user to make it available in every project.
How do I add GEML MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does GEML MCP provide?
It exposes 9 tools, including geml_list, geml_find, geml_get, geml_check, geml_to.
Can I use GEML with my existing Markdown files?
Yes, you can use commands like list, find, and get to address existing Markdown without converting them or creating new files.
How does GEML help with LLM token costs?
It allows agents to read and write only specific, addressable blocks rather than the entire file, which keeps the context window small.
Does GEML prevent bad writes or formatting errors?
Yes, it uses a deterministic grammar and a strict validator to ensure writes are valid and land as precise byte splices.
Can I roll back changes made by an agent?
Yes, GEML maintains a history that allows you to revert a single block atomically.