MCP server for nodiom — structured read/write access to Markdown documents for AI agents.
nodiom-mcp provides 7 well-structured tools for Markdown document manipulation with clear naming (verb_noun pattern: read, write, append, delete, query, tree). All tools have descriptions (avg 180 chars, within 10-1024 baseline) and Zod schemas with typed parameters. However, descriptions lack actionable context for LLM selection (no 'when to use' guidance, no dependency hints). Parameter descriptions are present but generic ('Absolute path', 'Selector'). Output schemas are undocumented, LLMs cannot predict response structure. Error handling returns text-only responses without recovery guidance or error classification. No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels (READ_ONLY, WRITE, DESTRUCTIVE). Missing pagination, result limits, and batch operations despite tools operating on file structures.
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.
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.
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.
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.
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.
Output schemas undocumented. LLMs cannot predict response structure (e.g., does nodiom_read_list return array of strings or objects? Does nodiom_tree return nested JSON with what fields?). Forces agents to guess and parse unstructured text.
Descriptions lack 'when to use' context and dependency hints. E.g., nodiom_read says what it does but not when to call it vs nodiom_tree, or that nodiom_tree should be called first to understand document structure. LLMs cannot distinguish between similar tools.
No tool annotations despite clear risk levels. nodiom_delete is destructive, nodiom_write and nodiom_append modify state, but no readOnlyHint/destructiveHint/idempotentHint annotations. Agents cannot reason about side effects or retry safety.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 60 | 2026-07-28+ | v2 |
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.
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.
Error responses are text-only with no recovery guidance or error classification. E.g., 'Error: SelectorNotFoundError' tells agent nothing about whether to retry, ask user, or abort. No actionable next steps.
Parameter descriptions are generic and lack format/constraint details. 'Absolute path to the Markdown file' does not specify: must file exist? What if path is relative? 'Selector' lacks examples of valid syntax or error cases. LLMs cannot validate inputs before calling.