Provides structured read/write access to Markdown documents, allowing AI agents to read, write, append, and delete content using structural selectors without regex.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nodiom-mcp Show the active tasks in /Users/me/projects/wiki.md"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for nodiom — structured read/write access to Markdown documents for AI agents.
Expose nodiom's structural Markdown operations as Model Context Protocol tools. Any MCP-compatible agent — Claude Desktop, Claude Code, or any custom MCP client — can read, write, append, and delete content in Markdown files using structural selectors, without regex or string hacking.
npm install -g @synexiom-labs/nodiom-mcpOr use directly with npx (no install required):
npx @synexiom-labs/nodiom-mcpRelated MCP server: search-docs
Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"nodiom": {
"command": "npx",
"args": ["-y", "@synexiom-labs/nodiom-mcp"]
}
}
}claude mcp add -s user nodiom -- npx -y @synexiom-labs/nodiom-mcpThe -s user flag registers the server globally across all your projects. Without it, the server is only active when Claude Code's working directory matches the project where you ran the command.
{
"command": "npx",
"args": ["-y", "@synexiom-labs/nodiom-mcp"]
}The server exposes 7 tools, all operating on local Markdown files by absolute path.
nodiom_treeGet the structural outline of a document before reading or modifying it.
file: "/path/to/wiki.md"
→ Returns a nested JSON tree of all headingsnodiom_readRead the content at a structural location.
file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks > ### Active"
→ Returns the Markdown content of that sectionnodiom_read_listRead all list items under a section as a JSON array.
file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Team"
→ ["- Alice Chen — Tech Lead", "- Bob Martinez — ML Engineer", ...]nodiom_writeReplace the content of a section (heading is preserved).
file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Overview"
content: "Project Aurora is on track for Q3 delivery."
→ Replaces only the Overview body. Nothing else changes.nodiom_appendAppend content after the last item in a section.
file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks > ### Active"
content: "- [ ] Deploy to staging"
→ Adds the new task at the end of Active. Existing tasks untouched.nodiom_deleteRemove a node or section.
file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks > ### Completed > li[0]"
→ Removes the first completed task.nodiom_queryCheck if a section exists and get its metadata.
file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks"
→ { "exists": true, "type": "heading", "depth": 2, "childCount": 3, "index": 4 }Selectors are " > "-separated paths of heading and element segments:
"# Project" → H1 section
"# Project > ## Tasks" → H2 under H1
"# Project > ## Tasks > ### Active" → H3 under H2 under H1
"## Tasks > li[0]" → First list item
"## Tasks > li[-1]" → Last list item
"## Notes > p[0]" → First paragraph
"## Arch > table[0]" → First tableWhen a selector doesn't match, the error includes fuzzy suggestions: "Did you mean '## Tasks'?"
Once the server is configured, you can instruct Claude naturally:
"Look at my project wiki at
/Users/me/projects/aurora/wiki.md. What are the active tasks? Add a new task: 'Write integration tests'. Then move the first completed task to a new '## Archive' section."
Claude will use nodiom_tree to understand the structure, nodiom_read_list to get the tasks, nodiom_append to add the new one, and nodiom_read + nodiom_delete + nodiom_append to move the completed task — all without loading the entire file as a string.
Package | Description |
Core library — use directly in your Node.js code | |
| This package — MCP server for AI agents |
MIT — Synexiom Labs Inc.
Appends new content after the last item in a section. Use this to add a new task, log entry, or note without disturbing existing content. Content is added at the end of the matched section.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. | |
| content | Yes | Markdown content to append. Example: "- [ ] New task" | |
| selector | Yes | Selector for the section to append to. Example: "## Tasks > ### Active" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It does communicate non-destructive behavior and placement ('at the end of the matched section'), but it omits edge-case behavior such as selector-match failures, whether the file is created if missing, or formatting/line-break handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action. However, the third sentence ('Content is added at the end of the matched section') repeats the placement detail from the first sentence, creating mild redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with no output schema, the description covers the essential usage and placement. It does not describe success/error responses or what happens when the selector does not match, but the schema already documents all parameters clearly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description references 'section' and 'content' but adds no parameter semantics beyond what the schema already provides for file, selector, and content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Appends new content'), a resource ('Markdown section'), and positional behavior ('after the last item'), clearly distinguishing append from sibling write/delete tools. The title is consistent and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('add a new task, log entry, or note') and explains the intended effect ('without disturbing existing content'). It does not mention when not to use the tool or explicitly route to a sibling, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes the node or section matched by the selector. Use "## Section > li[0]" to delete the first list item. Use "## Section" to delete an entire section including its heading. All other content is untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. | |
| selector | Yes | Selector for the node to delete. Example: "## Completed > li[0]", "## Old Section" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that delete operations on a selector can remove a list item or an entire section including its heading, and confirms that all other content is untouched. It does not mention whether deletions are irreversible or whether any confirmation is required, but the destructive nature is explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loads the core action, and uses examples to illustrate selector syntax efficiently. Every sentence earns its place: the first states the action, the second and third clarify scope with examples and reassurance. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter deletion tool with clear behavioral implications, the description is complete. It explains the selector semantics, the two levels of deletion, and the safety guarantee that other content is untouched. The absence of an output schema is acceptable because the tool's return value is not critical to correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes both parameters but with minimal detail. The description adds valuable meaning to the selector parameter by explaining its syntax and providing two concrete examples that cover different scopes of deletion. With only 2 parameters and the selector being the critical one, the description compensates well for the schema's brevity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Removes the node or section matched by the selector') and provides concrete examples that distinguish it from siblings like nodiom_append and nodiom_write. It clearly identifies the scope of what is deleted (node vs entire section including heading), which is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The examples show when to use the tool and what selector syntax to use for different deletion targets. It explicitly says 'All other content is untouched,' which sets expectations about scope. It does not explicitly name alternatives or exclusion conditions, but the examples provide sufficient context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns structural metadata about a location: whether it exists, its type, depth, and child count. Use this to check if a section exists before reading or writing to it.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. | |
| selector | Yes | Selector to query. Example: "## Tasks > ### Active" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool returns structural metadata rather than modifying content, and it specifies what information is returned. This sufficiently conveys the non-destructive, query-like nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant wording. The core behavior is stated first, and the usage guidance follows immediately. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter metadata query with no output schema, the description is complete: it names the parameters' purpose, explains what the tool returns, and gives a practical usage scenario. Nothing critical is missing for an agent to decide whether to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add significant detail about the parameters beyond what the schema already provides. It reinforces that the selector refers to a nested location, but the baseline of 3 is appropriate since the schema already documents both parameters fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Returns structural metadata about a location' and enumerates the exact fields returned (existence, type, depth, child count). This distinguishes it from sibling tools like nodiom_read, which return content, or nodiom_write, which modifies the file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit use case: 'Use this to check if a section exists before reading or writing to it.' This makes the primary context clear, though it does not explicitly name alternatives or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Markdown content at a structural location in a file. Use a selector like "# Heading > ## Subheading" to address any section. Use "# H1 > ## H2 > li[0]" to read a specific list item. Returns the raw Markdown string of the matched content.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. | |
| selector | Yes | Structural selector. Examples: "# Project > ## Tasks", "## Notes > p[0]", "## Tasks > li[-1]" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool returns the raw Markdown string of the matched content and explains the selector addressing scheme. It does not discuss error behavior when no content is matched, but for a read operation the return type and non-destructive nature are reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. The core behavior and output are stated first, followed by two concise selector examples. Every sentence carries useful information, and nothing is redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with two required parameters and no output schema, the description covers the main inputs and the return type. It does not mention edge cases like missing files or unmatched selectors, but the provided examples and clear return description are sufficient for an agent to call this tool correctly in typical cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the selector semantics with additional examples and explains that it can address sections and specific list items, but this largely duplicates examples already present in the schema. It adds some conceptual clarity but does not compensate for a schema gap because there is none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Returns the Markdown content at a structural location in a file.' It also names the exact output ('raw Markdown string') and gives concrete selector syntax examples, which distinguishes it from sibling tools like nodiom_write, nodiom_delete, and nodiom_tree.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is clear from examples like '# Heading > ## Subheading' and 'li[0]', but no explicit when-to-use versus alternatives is given. It does not mention when not to use this tool or point toward sibling tools like nodiom_read_list, so the agent must infer applicability from the name and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns all list items under a selector as a JSON array of strings. Useful when you need to iterate over tasks, team members, or any bullet list.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. | |
| selector | Yes | Selector pointing to a section containing a list. Example: "## Tasks > ### Active" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden; it reasonably discloses that the tool is read-only in nature, returns all list items, and returns them as a JSON array of strings. It does not describe edge cases like missing selectors or nested lists, but the core behavior and output contract are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the main behavior and return format, then add a brief use-case note. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool, the description covers the key facts an agent needs: what is returned and when to use it. No output schema exists, so the return-type statement is valuable; the only minor gap is behavior when the selector matches no list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters with examples. The description adds little beyond reinforcing that the selector points at a list, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description names a specific operation (returns list items), a resource (items under a selector), and the return shape (JSON array of strings). This distinguishes it from siblings like nodiom_read, which presumably returns file content, and nodiom_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States clear use cases (iterating over tasks, team members, bullet lists) that signal when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the use-case framing is enough to guide basic selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the full structural outline of a Markdown document as a nested JSON tree of headings. Use this to understand the structure of a document before reading or modifying it.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the burden of disclosing behavior. It states that the tool returns a nested JSON tree of headings, which implies a read-only operation and clarifies the output shape. It does not explicitly say 'does not modify the document' or describe error behavior, but for a simple structural read tool the key behavior is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words. The most important fact—the return value being a nested JSON tree of headings—appears in the first sentence, and the second sentence adds practical usage context without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain what the caller receives, and it does: 'nested JSON tree of headings.' Given the tool has one parameter and a read-only purpose, this is enough for an agent to invoke it correctly, though it could add edge-case behavior like empty documents or missing files.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter, file, as 'Absolute path to the Markdown file,' giving 100% schema coverage. The description adds no parameter-level detail beyond the schema, which is acceptable because the schema fully defines the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Returns' and clearly identifies the resource: 'full structural outline of a Markdown document' in the form of a 'nested JSON tree of headings.' This directly distinguishes it from sibling tools like nodiom_read, which presumably returns content, and nodiom_read_list, which likely returns a file listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool: 'Use this to understand the structure of a document before reading or modifying it.' It does not name alternative sibling tools or state negative conditions, but the provided context is actionable and reasonably complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces the content at a structural location with new content. The heading itself is preserved — only the body content is replaced. All other sections in the document are untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to the Markdown file. | |
| content | Yes | New Markdown content to place at this location. | |
| selector | Yes | Selector for the section to replace. Example: "## Summary" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it uses the opportunity well: it discloses that this is a destructive replacement, precisely what gets destroyed (body content only), and what is preserved (heading, all other sections). This directly answers the main risk question for a mutation tool — 'what will I lose?' The only gap is failure behavior when the selector matches no section or the file doesn't exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: core action, key nuance (heading preserved), and scope guarantee (other sections untouched). Every word is load-bearing, and the critical safety detail is front-loaded in the second sentence. There is no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the change semantics well but stays silent on outcomes and failure modes — whether the file must exist, whether a non-matching selector is an error or a no-op, and what the tool returns on success. These are the remaining gaps an agent needs to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it connects 'selector' to 'structural location,' clarifies that 'content' is body-only, and explains the heading/body relationship that the individual parameter descriptions don't state. It doesn't describe the selector syntax (already covered by the schema example), so it stops short of 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource — 'Replaces the content at a structural location' — and immediately adds the two distinguishing nuances: the heading survives and the rest of the document is untouched. Combined with the title 'Write (replace) Markdown section,' an agent can easily separate this from the read, append, delete, query, and tree siblings without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case — replacing body content within a section while preserving the heading — but never names a sibling or states when to prefer an alternative like nodiom_append or nodiom_delete. An agent must infer the boundary between replace, append, and delete purely from the sibling names. The scoping sentence ('All other sections in the document are untouched') provides context but no explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0nodiom_appendnodiom_deletenodiom_querynodiom_readnodiom_read_listnodiom_treenodiom_writeScored across 7 tools
Each tool targets a distinct operation on the Markdown structure: reading content, reading list items, writing, appending, deleting, querying metadata, and viewing the outline. There is no meaningful overlap that would cause an agent to select the wrong tool.
Tools consistently use the nodiom_ prefix with lowercase snake_case names. Most are verb-based (read, write, append, delete, query), though 'tree' is a noun rather than a verb and could have been 'get_tree' for full consistency.
Seven tools is a well-scoped set for structured Markdown editing. Each tool covers a distinct need without redundancy or bloat, and the count is appropriate for the server's focused purpose.
The toolset covers read, write, append, delete, and structural inspection well. A minor gap is the lack of an explicit create-section operation; a selector must presumably reference an existing heading, so creating wholly new sections may require workarounds.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Portable AI memory shared across models and harnesses - plain markdown you own.
Personal context for every AI: search, read, and write back to your private Markdown library.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
