MCP server that transforms markdown documents to NM3 3D visualization format
Markdown3D MCP has 7 tools with visible schemas and descriptions in src/server.ts. Naming is mostly action-verb based (transform_*, get_*, validate_*, clear_*). However, schema quality is inconsistent: while all tools have basic descriptions and schemas, many lack depth and parameter constraints. Descriptions are present but often vague (e.g., 'Transform markdown to NM3... may truncate for large docs >300 nodes' leaves the 300-node threshold undocumented and vague). Output schemas are not documented, critical for LLM planning. Error handling is not visible in the tool definitions. Only two tools (transform_to_nm3_chunked, assemble_chunks) have write-side safety considerations called out. The tool set shows reasonable composition (one job per tool), but lacks the rigor expected for production: missing output type documentation, insufficient parameter constraints, and no recovery guidance.
Assemble chunked output into final NM3 file
Clear all caches
Check status of chunked output
Get performance and cache statistics
Transform markdown to NM3 (returns full XML - may truncate for large docs >300 nodes)
Transform markdown to NM3 with chunked output (prevents truncation for large docs)
Validate NM3 XML for compliance with spec
Output schemas not documented. Tools return results but LLMs have no visibility into the structure of returned data. This forces agents to guess field names and data types, breaking downstream tool chains and increasing hallucination risk. Critical for tools like transform_to_nm3 (returns XML) and get_performance_stats (returns statistics).
Vague threshold documentation. 'May truncate for large docs >300 nodes' in transform_to_nm3 description is underspecified. What format is returned when truncation occurs? How should the agent handle it? When should it use chunked mode instead? The LLM must guess.
Missing parameter constraints and enum values. Boolean flags useCache and useStreaming lack explanation of what 'streaming' means or when to disable it. workingDirectory in transform_to_nm3_chunked is not constrained (absolute vs relative path? must exist beforehand?). No enum values or validation hints for any parameter.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 46 | 2026-07-28+ | v2 |
Minimal descriptions for utility tools. get_performance_stats, clear_cache, and get_chunk_status have descriptions under 50 characters ('Get performance and cache statistics', 'Clear all caches', 'Check status of chunked output'). These lack context for when an LLM should invoke them, dependencies, and side effects. clear_cache especially needs to warn that it clears all caches, a destructive operation.
No error handling guidance. Visible code shows tool implementations but no callable error messages, recovery suggestions, or error categories. If markdown parsing fails, XML validation fails, or chunk assembly fails, the LLM receives no hint about what to do next. This violates the recovery-guide pattern.
Unclear parameter relationships. transform_to_nm3_chunked has outputName, workingDirectory, title, author, useCache, useStreaming, but their interaction is not documented. Does workingDirectory override outputName? Is outputName relative to workingDirectory or absolute? The LLM must reason through ambiguous relationships.
Tool composition risk: chunked transformation workflow. transform_to_nm3_chunked + get_chunk_status + assemble_chunks is a three-step process, but the tool descriptions do not document the expected sequence, dependencies, or manifest file format. An LLM may call these out of order or misunderstand state transitions.