Click on "Install 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., "@Markdown3D MCP Server convert this markdown to 3D: # My Research Notes"
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.
Transform markdown documents into immersive 3D visualizations using the NM3 format
Markdown3D MCP is a Model Context Protocol (MCP) server that intelligently converts markdown documents into three-dimensional spatial representations. Using semantic analysis, cross-reference detection, and optimized spatial layout algorithms, it creates navigable 3D knowledge structures that preserve document hierarchy and relationships.
🎯 Semantic Analysis - Intelligent content classification using NLP to determine node types and relationships
🎨 Smart Color Mapping - Context-aware color assignment based on content semantics and tone
📐 Geometric Intelligence - Automatic shape selection based on content structure (spheres, cubes, cylinders, pyramids, tori)
🔗 Cross-Reference Detection - Parses [[node-id]] patterns and builds relationship graphs
📏 Spatial Optimization - Force-directed layout algorithms for readable 3D arrangements
⚡ Multi-Layer Caching - LRU caches with intelligent eviction for sub-second repeat requests
📊 Streaming Processing - Handle documents of any size with constant memory usage
🔄 Parallel Processing - Worker thread pool for multi-core spatial optimization
📈 Performance Monitoring - Prometheus metrics and detailed performance statistics
💾 Memory Management - Automatic monitoring and garbage collection
✅ Strict Validation - Ensures compliance with NM3 specification (16 colors, 5 shapes)
⚡ MCP Integration - Seamless integration with Claude Desktop and other MCP clients
🧪 Comprehensive Testing - Full test suite with validation and error handling
Related MCP server: knowledgebased
Node.js 20.x or higher
npm or yarn
Claude Desktop (for MCP integration)
npm install -g markdown3d-mcp# Clone the repository
git clone https://github.com/yourusername/markdown3d-mcp.git
cd markdown3d-mcp
# Install dependencies
npm install
# Build the project
npm run buildAdd the server to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"markdown3d": {
"command": "node",
"args": ["/absolute/path/to/markdown3d-mcp/dist/index.js"]
}
}
}# Run standalone test
npm run test
# Start development server
npm run devRestart Claude Desktop after configuration
Check the 🔌 MCP icon to verify "markdown3d" is connected
Use the transformation tool:
Please use the transform_to_nm3 tool to convert this markdown:
# My Research
## Key Findings
- Discovery 1
- Discovery 2# Transform a markdown file
node dist/index.js < input.md > output.nm3
# Run test client
npm run testtransform_to_nm3Transforms markdown content into NM3 3D visualization format with performance optimizations.
Parameters:
markdown (required): Markdown content to transform
title (optional): Document title override
author (optional): Author name override
options (optional): Performance options object
useCache (boolean, default: true): Enable multi-layer caching
useStreaming (boolean, default: true): Enable streaming for large documents
chunkSize (number, default: 1000): Lines per chunk for streaming
Example:
{
"markdown": "# Introduction\n\nThis is a test document.",
"title": "Test Document",
"author": "John Doe",
"options": {
"useCache": true,
"useStreaming": true
}
}Returns: Valid NM3 XML string
Performance Notes:
First request may take longer as caches warm up
Identical markdown served from cache in <10ms
Documents >50KB automatically use streaming
Cache hit rate typically >80% after warmup
validate_nm3Validates NM3 XML for compliance with the specification.
Parameters:
xml (required): NM3 XML to validate
Returns: Validation result with success status and error details
get_performance_statsRetrieves detailed performance and cache statistics from the server.
Parameters: None
Returns: Performance report including:
Cache statistics (hits, misses, hit rates) for all cache layers
Memory usage (heap, RSS, percentage)
Prometheus metrics (transform duration, counts, etc.)
Example Response:
# Performance Statistics
## Cache Stats
### parse
- Hits: 150
- Misses: 50
- Hit Rate: 75.00%
- Keys: 45
### transform
- Hits: 140
- Misses: 60
- Hit Rate: 70.00%
- Keys: 35
### xml
- Hits: 145
- Misses: 55
- Hit Rate: 72.50%
- Keys: 40
## Memory Stats
- Heap Used: 245.67MB
- Heap Total: 512.00MB
- Percent Used: 47.98%
- RSS: 385.23MB
## Prometheus Metrics
...clear_cacheClears all caches to free memory or reset performance state.
Parameters: None
Returns: Confirmation message
Use Cases:
Free memory when approaching limits
Reset cache state for testing
Clear stale cached data
Force fresh transformations
Note: After clearing cache, first requests will take longer as caches rebuild.
import { MarkdownParser } from './core/parser.js';
import { SimpleTransformer } from './core/transformer.js';
import { NM3XMLBuilder } from './core/xml-builder.js';
// Parse markdown
const parser = new MarkdownParser();
const sections = parser.parse(markdownContent);
// Transform to NM3
const transformer = new SimpleTransformer();
const nm3Doc = transformer.transform(sections);
// Build XML
const xmlBuilder = new NM3XMLBuilder();
const xml = xmlBuilder.buildXML(nm3Doc);Markdown → Parser → Semantic Analysis → Transformer → XML Builder → NM3Parsing: Markdown is tokenized and structured into hierarchical sections
Analysis: Content is analyzed for semantic meaning, patterns, and relationships
Transformation: Sections are converted to 3D nodes with appropriate shapes, colors, and positions
XML Generation: Valid NM3 XML is built with proper CDATA wrapping and validation
Color | Semantic Meaning | Triggers |
| Urgent/Critical | error, warning, critical, urgent |
| Information | main sections, documentation |
| Solutions/Success | solution, complete, done, success |
| Questions/Ideas | questions, how, why, what |
| References/Sources | citation, reference, source, link |
| Warnings/Attention | attention, caution, note |
| Fresh Ideas | new, innovation, idea, proposal |
| Technical/Code | code blocks, technical content |
| Personal Notes | subjective, opinion, note |
| Archive/Deep Content | nested content, completed items |
Shape | Usage | Best For |
🔵 Sphere | Atomic concepts | Single ideas, definitions, standalone concepts |
📦 Cube | Structured data | Categories, tables, structured information |
🔄 Cylinder | Processes | Timelines, steps, sequential processes |
🔺 Pyramid | Hierarchies | Priority lists, organizational structures |
🍩 Torus | Cycles | Loops, feedback systems, continuous processes |
Z-axis: Importance/temporal ordering (important content forward)
Y-axis: Abstraction levels (high-level concepts higher)
X-axis: Categorical grouping (related content clustered)
Hierarchy: Parent-child relationships via containment links
Spacing: Dynamic based on node importance and relationships
Markdown3D MCP is optimized for production workloads with Phase 4 performance enhancements:
Metric | Target | Description |
Cached Requests | <10ms | Repeat transformations served from cache |
Small Documents | <500ms | Documents with <100 nodes, first request |
Medium Documents | <2s | Documents with 100-1000 nodes |
Large Documents | <5s | Documents with 1000-5000 nodes (with streaming) |
Memory Footprint | <500MB | Under normal production load |
Cache Hit Rate | >80% | After initial warmup period |
Parse Cache: 100MB LRU cache with 30-minute TTL for parsed markdown
Transform Cache: 50MB LRU cache with 15-minute TTL for NM3 documents
XML Cache: NodeCache with 100 keys and 10-minute TTL
SHA-256 Hashing: Deterministic cache keys for reliable hit detection
Automatic activation for documents >50KB
Constant memory usage regardless of document size
Line-by-line parsing with chunked processing
Handles multi-GB documents efficiently
Worker thread pool for CPU-intensive operations
Multi-core spatial optimization
Configurable worker count (default: CPU cores - 1)
Automatic load balancing
Prometheus metrics integration
Real-time cache hit/miss statistics
Memory usage tracking
Transform duration histograms
Node count distributions
Automatic monitoring every 30 seconds
Warning threshold: 400MB heap usage
Critical threshold: 800MB heap usage
Automatic garbage collection on critical status
Detailed memory statistics
For best performance:
Enable Caching: Cache is enabled by default; ensure it's not disabled
Reuse Content: Identical markdown will be served from cache in <10ms
Large Documents: Documents >50KB automatically use streaming
Memory Limits: Monitor memory usage with get_performance_stats tool
Clear Cache: Use clear_cache tool if memory becomes constrained
markdown3d-mcp/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server implementation
│ ├── core/
│ │ ├── parser.ts # Markdown parsing
│ │ ├── transformer.ts # Basic transformation
│ │ ├── enhanced-transformer.ts # Advanced transformation (Phase 2)
│ │ ├── optimized-transformer.ts # Performance-optimized transformer (Phase 4)
│ │ ├── xml-builder.ts # NM3 XML generation
│ │ ├── reference-extractor.ts # Cross-reference detection
│ │ ├── content-classifier.ts # Semantic analysis
│ │ ├── intelligent-shape-assigner.ts
│ │ ├── intelligent-color-mapper.ts
│ │ ├── spatial-optimizer-v2.ts # Spatial layout optimization (Phase 3)
│ │ ├── collision-detector.ts # Collision detection (Phase 3)
│ │ ├── force-directed-3d.ts # Force-directed layout (Phase 3)
│ │ ├── layout-templates.ts # Layout templates (Phase 3)
│ │ ├── octree.ts # Octree spatial indexing (Phase 3)
│ │ ├── cache-manager.ts # Multi-layer caching (Phase 4)
│ │ ├── stream-processor.ts # Streaming processor (Phase 4)
│ │ ├── worker-pool.ts # Worker thread pool (Phase 4)
│ │ ├── metrics.ts # Performance metrics (Phase 4)
│ │ └── memory-monitor.ts # Memory management (Phase 4)
│ ├── models/
│ │ └── types.ts # TypeScript interfaces
│ ├── constants/
│ │ └── validation.ts # Valid colors and shapes
│ ├── utils/ # Utility functions
│ └── handlers/ # Additional handlers
├── docs/ # Documentation
│ ├── Markdown3D-Phase0.md # Overview
│ ├── Markdown3D-Phase1.md # Foundation implementation
│ ├── Markdown3D-Phase2.md # Advanced features
│ ├── Markdown3D-Phase3.md # Spatial optimization
│ ├── Markdown3D-Phase4.md # Performance & scalability
│ └── instruct/ # Detailed phase instructions
├── tests/ # Test suite
├── output/ # Generated NM3 files
└── specs/ # NM3 specifications
# Install dependencies
npm install
# Development mode (watch for changes)
npm run dev
# Build for production
npm run build
# Run tests
npm run test
# Start MCP server
npm start# Clone repository
git clone https://github.com/yourusername/markdown3d-mcp.git
cd markdown3d-mcp
# Install dependencies
npm install
# Build TypeScript
npm run build
# Test the build
node dist/index.jsThe project is organized into 6 development phases:
Phase 1: Foundation & Basic Functionality ✅
Working MCP server with basic transformation
Strict validation (16 colors, 5 shapes)
Simple spatial positioning
Phase 2: Advanced Parsing & Intelligence ✅
Cross-reference detection
Semantic analysis with NLP
Intelligent shape and color assignment
Relationship mapping
Phase 3: Spatial Optimization ✅
Force-directed graph algorithms
Collision detection and resolution
Layout templates
Octree spatial indexing
Phase 4: Performance & Scalability ✅
Multi-layer caching (parse, transform, XML)
Streaming processing for large documents
Worker thread pool for parallel processing
Performance monitoring with Prometheus metrics
Memory management with automatic GC
Optimized transformer with intelligent caching
Phase 5: Testing & Quality Assurance (Planned)
Comprehensive test suite
Validation framework
Error recovery
Benchmark suite
Phase 6: Production & Deployment (Planned)
Docker containerization
CI/CD pipelines
Monitoring and logging
Documentation
# Run all tests
npm run test
# Test with specific markdown file
npm run test -- --file docs/test-book.md
# Validate NM3 output
node dist/index.js validate output/test.nm3TypeScript with strict mode enabled
ESModules (.js imports required)
Functional programming patterns preferred
Comprehensive error handling
Detailed logging for debugging
NM3 (Navigable Markdown 3D) is an XML-based format for representing documents in 3D space. Each document consists of:
Metadata: Title, author, creation date, tags
Camera: Initial viewpoint and field of view
Nodes: 3D geometric shapes representing content
Links: Relationships between nodes
16 Allowed Colors: Pastel palette for visual harmony
5 Geometric Types: Sphere, Cube, Cylinder, Pyramid, Torus
CDATA Content: Preserves markdown formatting
Spatial Positioning: 3D coordinates (x, y, z)
Link Types: 13 semantic relationship types
For the complete NM3 XML specification, see:
NM3 Format Specification (placeholder - link to your spec)
<?xml version="1.0" encoding="UTF-8"?>
<nm3 version="1.0">
<meta title="Document Title" created="2025-01-01T00:00:00Z" author="Author"/>
<camera position-x="0" position-y="10" position-z="20"
look-at-x="0" look-at-y="0" look-at-z="0" fov="75"/>
<nodes>
<node id="intro" type="sphere" x="0" y="0" z="0"
color="pastel-blue" scale="1.5">
<title>Introduction</title>
<content><![CDATA[# Introduction
This is the content...]]></content>
</node>
</nodes>
<links>
<link from="intro" to="chapter1" type="leads-to" color="pastel-gray"/>
</links>
</nm3>To view the generated 3D visualizations, use the Careless-Canvas-3D application:
🔗 Careless-Canvas-3D Viewer (placeholder link)
The Careless-Canvas-3D viewer provides:
Interactive 3D navigation
Node selection and content viewing
Link traversal
Multiple camera modes
Export and sharing options
NM3 files can also be viewed with:
Any XML-compatible 3D visualization tool
Custom Three.js implementations
VR/AR compatible viewers
(Add screenshots of visualized documents here)
(Placeholder for related NM3 works, inspirations, and acknowledgments)
Contributions are welcome! Please see our Contributing Guidelines for details.
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
# Fork and clone
git clone https://github.com/yourusername/markdown3d-mcp.git
# Create branch
git checkout -b feature/my-feature
# Install dependencies
npm install
# Make changes and test
npm run dev
npm run test
# Build
npm run buildWe follow the Contributor Covenant Code of Conduct. Please be respectful and inclusive in all interactions.
This project is licensed under the ISC License - see the LICENSE file for details.
GitHub Repository: https://github.com/yourusername/markdown3d-mcp
NPM Package: https://www.npmjs.com/package/markdown3d-mcp
Documentation: https://markdown3d-docs.example.com
Issue Tracker: https://github.com/yourusername/markdown3d-mcp/issues
MCP Protocol: https://modelcontextprotocol.io
If you use this codebase in your research or project, please cite:
@software{markdown3d_mcp,
title = {Markdown3D MCP: MCP transforms MD into NM3 formatted xml},
author = {[Drift Johnson]},
year = {2025},
url = {https://github.com/MushroomFleet/Markdown3D-MCP},
version = {1.0.0}
}
Made with ❤️ by the Markdown3D team
Transform your documents into navigable 3D knowledge spaces
If you found this useful, please star the repo — it helps others discover it!
Assemble chunked output into final NM3 file
| Name | Required | Description | Default |
|---|---|---|---|
| manifestPath | Yes | Path to manifest.json from chunked transform | |
| outputDirectory | No | Optional output directory for the final NM3 file (defaults to current working directory) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states the purpose without mentioning any side effects, required permissions, error conditions (e.g., missing manifest), or whether the operation is destructive. This is insufficient for an AI agent to understand the tool's behavior.
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 a single sentence that is concise and front-loaded. Every word is necessary; no wasted text.
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?
Despite having only 2 parameters and no output schema, the description lacks important context: it does not explain what an NM3 file is, what the manifest path should point to, or what the output directory defaults to. Given the sibling tools, more details would help an agent decide when to invoke this tool.
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% (both parameters have descriptions). The tool description adds no additional meaning beyond what the schema already provides. Based on the rubric, baseline is 3 when schema coverage is high, so no deduction.
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 'Assemble chunked output into final NM3 file' clearly states the verb (assemble) and resource (chunked output to NM3 file). It distinguishes well from siblings like transform_to_nm3_chunked, which creates the chunks, and get_chunk_status, which checks progress.
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?
No explicit guidance on when to use this tool versus alternatives. While it is implied that this should be used after transform_to_nm3_chunked, the description does not state prerequisites, exclusions, or mention alternative workflows like using transform_to_nm3 for non-chunked inputs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear all caches
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for behavioral disclosure. It merely states the action without any details on side effects, destructiveness, idempotency, required permissions, or state changes. This is insufficient for an agent to gauge safety.
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 a single sentence that is front-loaded and contains zero wasted words. It is appropriately sized for a tool with no parameters.
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?
Given the lack of annotations, output schema, and usage guidance, the description is too brief to fully inform an agent. It lacks crucial behavioral and contextual details, such as when this action is safe or what the consequences are.
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?
There are no parameters, and schema coverage is trivially 100%. The description adds no parameter information because none is needed. Baseline for zero parameters is 4, which is appropriate here.
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 'Clear all caches' clearly states the verb (clear) and resource (all caches). It is specific enough for an agent to understand the action, though 'all caches' could be ambiguous in scope. Distinguishes from sibling tools which focus on chunk operations and transformations.
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?
No guidance is provided on when to use this tool vs alternatives. The description does not mention prerequisites, contexts, or situations where clearing caches is appropriate. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check status of chunked output
| Name | Required | Description | Default |
|---|---|---|---|
| manifestPath | Yes | Path to manifest.json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose any behavioral traits, such as whether the operation is read-only, has side effects, or requires specific permissions. The single sentence provides no insight into tool behavior beyond the implied status check.
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 extremely concise (one sentence), which is efficient but insufficient for a tool with no annotations or output schema. It sacrifices necessary detail for brevity.
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?
Given the tool's single parameter and lack of output schema, the description should explain what status information is returned, possible values, or how to interpret results. It provides none of this, leaving the agent underinformed.
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 schema has 100% coverage for the single parameter 'manifestPath', so the baseline is 3. The description adds no extra meaning beyond the schema's own description, but does not detract either.
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 'Check status of chunked output' merely rephrases the tool name without providing additional context or distinguishing it from siblings like 'assemble_chunks'. It lacks specificity about what 'status' entails.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, making it impossible for an agent to determine appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get performance and cache statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose any behavioral traits such as whether the operation is read-only, requires authentication, or has side effects.
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 a single sentence, but it is very brief and lacks detail. It is functional but could be improved with more context.
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?
Given no output schema and no annotations, the description is minimal. It does not explain what kind of statistics are returned, how to interpret them, or how this tool relates to other cache/tools.
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 tool has 0 parameters, and the schema coverage is 100%. Per guidelines, a baseline of 4 is appropriate since the description does not need to add parameter details.
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 'Get performance and cache statistics' clearly states the verb (Get) and resource (performance and cache statistics), distinguishing it from sibling tools like clear_cache or get_chunk_status.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transform markdown to NM3 (returns full XML - may truncate for large docs >300 nodes)
| Name | Required | Description | Default |
|---|---|---|---|
| markdown | Yes | Markdown content to transform | |
| title | No | Optional document title | |
| author | No | Optional author name | |
| useCache | No | Enable caching (default: true) | |
| useStreaming | No | Enable streaming for large documents (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the truncation behavior for large documents (>300 nodes) and states the output format (full XML). However, without annotations, it does not cover other behavioral aspects like idempotency, authorization needs, or side effects.
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 a single sentence that quickly conveys the action and a key limitation. It is efficient and front-loaded, though slightly ambiguous due to the contradiction between 'full XML' and 'may truncate'.
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 and 5 parameters, the description is insufficient. It contradicts itself (returns full XML but may truncate), lacks information about error conditions, streaming behavior, or the XML structure. For a moderately complex tool, this is incomplete.
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% with all parameters described. The tool description adds no extra meaning beyond the schema; the truncation note is not parameter-specific. Baseline score 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?
The description clearly states the verb 'Transform' and the resource 'markdown to NM3', and adds a note about returning XML with a truncation warning. However, it does not explicitly differentiate from the sibling tool 'transform_to_nm3_chunked'.
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?
No explicit when-to-use or when-not-to-use guidance is provided. The truncation warning hints at a limitation but does not suggest alternatives or contextual usage rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transform markdown to NM3 with chunked output (prevents truncation for large docs)
| Name | Required | Description | Default |
|---|---|---|---|
| markdown | Yes | Markdown content to transform | |
| outputName | No | Output filename (default: output.nm3) | output.nm3 |
| workingDirectory | No | Working directory for output file (captures where the final NM3 should be saved) | |
| title | No | Optional document title | |
| author | No | Optional author name | |
| useCache | No | Enable caching (default: true) | |
| useStreaming | No | Enable streaming for large documents (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It mentions chunked output but does not disclose behavioral traits like whether the tool is destructive, the need to later assemble chunks (given sibling assemble_chunks), or any side effects of caching/streaming parameters.
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?
Description is a single, front-loaded sentence that conveys purpose and benefit efficiently. It is concise without unnecessary words, though could be slightly expanded for clarity.
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?
Despite the tool having 7 parameters and no output schema, the description is minimal. It does not explain the chunking mechanism, how results are returned, or the relationship with sibling tool assemble_chunks. This leaves the agent with insufficient context to use the tool effectively.
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 schema already documents all parameters. The description adds no extra meaning beyond the schema; for example, it does not clarify how 'chunked output' relates to the parameters or the output process.
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 clearly states the action (transform), input (markdown), output format (NM3 with chunked output), and the problem it solves (prevents truncation for large docs). It distinguishes from sibling transform_to_nm3 by mentioning chunked output.
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?
Implies usage for large documents to prevent truncation, but does not explicitly state when to use this tool vs alternatives like transform_to_nm3, nor when not to use it. No exclusions or alternative tool names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate NM3 XML for compliance with spec
| Name | Required | Description | Default |
|---|---|---|---|
| xml | Yes | NM3 XML to validate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It indicates 'Validate' (read-only), but does not disclose what happens on failure (e.g., error thrown, return false) or side effects. Lacks depth.
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?
Single sentence with no wasted words. Could benefit from slight expansion, but not overly verbose.
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?
Simple tool with one parameter and no output schema. Description is minimally complete but lacks details on return value (boolean, errors) and the specific spec. Acceptable for a straightforward validation tool.
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% with description 'NM3 XML to validate'. Description adds no further meaning beyond schema, so baseline 3 is appropriate. No format, encoding, or size constraints mentioned.
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 verb 'Validate' and the resource 'NM3 XML', and mentions compliance with a spec. It distinguishes from sibling tools like transform_to_nm3. However, 'spec' is vague without specifying which standard.
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?
No guidance on when to use this tool versus alternatives (e.g., after transformation, before further processing). No exclusions or prerequisites mentioned.
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. Dates show when Glama detected each change.
v1.0.0assemble_chunksclear_cacheget_chunk_statusget_performance_statstransform_to_nm3transform_to_nm3_chunkedvalidate_nm3Each tool has a clearly distinct purpose: transformation (normal and chunked), validation, assembly, cache management, status checking, and performance stats. The only potential overlap is between the two transform tools, but the chunked variant's purpose is explicitly differentiated.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., assemble_chunks, clear_cache, get_performance_stats, transform_to_nm3). The naming is predictable and uniform.
With 7 tools, the set is well-scoped for a server focused on transforming markdown to NM3. Each tool serves a specific function in the workflow, and there are no extraneous or missing tools relative to the domain.
The tool set covers the core transformation lifecycle (normal and chunked), validation, and assembly, plus utility functions (cache, status, performance). A minor gap is the lack of a reverse conversion (NM3 to markdown), but this is not part of the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Turn AI conversations into visual knowledge maps. Create, connect, search, and organize thoughts.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Map text into knowledge graphs to create a structured representation of conceptual relations and t…
Build a real 3D website by chatting: pages, models and text in space, published to a live URL.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MushroomFleet/Markdown3D-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
