马克ダウン3D-MCP
项目介绍
技术文档摘要
Markdown3D MCP Server
使用NM3格式将Markdown文档转换为沉浸式3D可视化
Markdown3D MCP是一个模型上下文协议（MCP）服务器，它智能地将Markdown文档转换为三维空间表示。通过语义分析、交叉引用检测和优化的空间布局算法，它创建了可导航的3D知识结构，保留了文档层次结构和关系。
✨ 特性
- 🎯 语义分析 - 使用自然语言处理（NLP）进行智能内容分类，确定节点类型和关系
- 🎨 智能色彩映射 - 根据内容语义和语气进行上下文感知的颜色分配
- 📐 几何智能 - 根据内容结构自动选择形状（球体、立方体、圆柱体、金字塔、环面）
- 🔗 交叉引用检测 - 解析
[[节点ID]]模式并构建关系图 - 📏 空间优化 - 使用力导向布局算法实现可读的3D排列
- ⚡ 多层缓存 - 带有智能淘汰策略的LRU缓存，用于亚秒级重复请求
- 📊 流式处理 - 处理任意大小的文档，内存使用量恒定
- 🔄 并行处理 - 工作线程池用于多核空间优化
- 📈 性能监控 - Prometheus指标和详细的性能统计
- 💾 内存管理 - 自动监控和垃圾收集
- ✅ 严格验证 - 确保符合NM3规范（16种颜色，5种形状）
- ⚡ MCP集成 - 无缝集成到Claude Desktop和其他MCP客户端
- 🧪 综合测试 - 包含验证和错误处理的完整测试套件
📋 目录
🚀 安装
先决条件
- Node.js 20.x或更高版本
- npm或yarn
- Claude Desktop（用于MCP集成）
从npm安装
npm install -g markdown3d-mcp
从源代码安装
# 克隆仓库
git clone https://github.com/yourusername/markdown3d-mcp.git
cd markdown3d-mcp
# 安装依赖
npm install
# 构建项目
npm run build
配置Claude Desktop
在你的Claude Desktop配置中添加服务器：
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": ["/绝对路径/to/markdown3d-mcp/dist/index.js"]
}
}
}
验证安装
# 运行独立测试
npm run test
# 启动开发服务器
npm run dev
⚡ 快速开始
使用Claude Desktop
- 配置后重启Claude Desktop
- 检查🔌 MCP图标以确认“markdown3d”已连接
- 使用转换工具：
请使用transform_to_nm3工具来转换此Markdown：
# 我的研究
## 关键发现
- 发现1
- 发现2
命令行用法
# 转换Markdown文件
node dist/index.js < input.md > output.nm3
# 运行测试客户端
npm run test
📖 用法
MCP工具
transform_to_nm3
将Markdown内容转换为NM3 3D可视化格式，并进行性能优化。
参数：
markdown（必需）：要转换的Markdown内容title（可选）：文档标题覆盖author（可选）：作者名称覆盖options（可选）：性能选项对象useCache（布尔值，默认：true）：启用多层缓存useStreaming（布尔值，默认：true）：启用流式处理大型文档chunkSize（数字，默认：1000）：流式处理每块的行数
示例：
{
"markdown": "# 引言\n\n这是一个测试文档。",
"title": "测试文档",
"author": "John Doe",
"options": {
"useCache": true,
"useStreaming": true
}
}
**返回值：**有效的NM3 XML字符串
性能说明：
- 第一次请求可能需要更长时间，因为缓存正在预热
- 相同的Markdown从缓存中提供，时间小于10毫秒
- 文档大于50KB时自动使用流式处理
- 缓存命中率通常在预热后超过80%
validate_nm3
验证NM3 XML是否符合规范。
参数：
xml（必需）：要验证的NM3 XML
**返回值：**包含成功状态和错误详情的验证结果
get_performance_stats
从服务器检索详细的性能和缓存统计信息。
**参数：**无
**返回值：**包括以下内容的性能报告：
- 所有缓存层的缓存统计（命中次数、未命中次数、命中率）
- 内存使用情况（堆、RSS、百分比）
- Prometheus指标（转换持续时间、计数等）
示例响应：
# 性能统计
## 缓存统计
### 解析
- 命中次数：150
- 未命中次数：50
- 命中率：75.00%
- 键数：45
### 转换
- 命中次数：140
- 未命中次数：60
- 命中率：70.00%
- 键数：35
### XML
- 命中次数：145
- 未命中次数：55
- 命中率：72.50%
- 键数：40
## 内存统计
- 堆使用量：245.67MB
- 堆总量：512.00MB
- 使用百分比：47.98%
- RSS：385.23MB
## Prometheus指标
...
clear_cache
清除所有缓存以释放内存或重置性能状态。
**参数：**无
**返回值：**确认消息
使用场景：
- 当接近限制时释放内存
- 为测试重置缓存状态
- 清除过期的缓存数据
- 强制刷新转换
**注意：**清除缓存后，首次请求会花费更长时间，因为缓存需要重建。
API用法
import { MarkdownParser } from './core/parser.js';
import { SimpleTransformer } from './core/transformer.js';
import { NM3XMLBuilder } from './core/xml-builder.js';
// 解析Markdown
const parser = new MarkdownParser();
const sections = parser.parse(markdownContent);
// 转换为NM3
const transformer = new SimpleTransformer();
const nm3Doc = transformer.transform(sections);
// 构建XML
const xmlBuilder = new NM3XMLBuilder();
const xml = xmlBuilder.buildXML(nm3Doc);
🔧 工作原理
转换流水线
Markdown → 解析器 → 语义分析 → 转换器 → XML生成器 → NM3
- 解析：Markdown被标记化并结构化为分层部分
- 分析：内容被分析以获取语义意义、模式和关系
- 转换：部分被转换为具有适当形状、颜色和位置的3D节点
- XML生成：生成有效的NM3 XML，带有适当的CDATA包装和验证
色彩映射规则
| 颜色 | 语义含义 | 触发器 |
|---|---|---|
pastel-pink | 紧急/关键 | 错误、警告、关键、紧急 |
pastel-blue | 信息 | 主要部分、文档 |
pastel-green | 解决方案/成功 | 解决方案、完成、成功 |
pastel-yellow | 问题/想法 | 问题、如何、为什么、什么 |
pastel-purple | 参考/来源 | 引用、参考、来源、链接 |
pastel-orange | 警告/注意 | 注意、谨慎、注释 |
pastel-mint | 新颖的想法 | 新的、创新、想法、提案 |
pastel-lavender | 技术/代码 | 代码块、技术内容 |
pastel-peach | 个人笔记 | 主观、意见、注释 |
pastel-gray | 存档/深度内容 | 嵌套内容、已完成项目 |
形状分配逻辑
| 形状 | 使用 | 最佳用途 |
|---|---|---|
| 🔵 球体 | 原子概念 | 单一想法、定义、独立概念 |
| 📦 立方体 | 结构化数据 | 类别、表格、结构化信息 |
| 🔄 圆柱体 | 过程 | 时间轴、步骤、顺序过程 |
| 🔺 金字塔 | 层次结构 | 优先列表、组织结构 |
| 🍩 环面 | 循环 | 循环、反馈系统、连续过程 |
空间布局策略
- Z轴：重要性/时间顺序（重要内容向前）
- Y轴：抽象级别（高级概念较高）
- X轴：类别分组（相关内容聚类）
- 层次结构：通过包含链接的父子关系
- 间距：基于节点重要性和关系动态调整
⚡ 性能
关键性能指标
Markdown3D MCP针对生产负载进行了优化，并在第4阶段进行了性能增强：
| 指标 | 目标 | 描述 |
|---|---|---|
| 缓存请求 | <10ms | 重复转换从缓存提供 |
| 小文档 | <500ms | 小于100个节点的文档，第一次请求 |
| 中型文档 | <2s | 100-1000个节点的文档 |
| 大型文档 | <5s | 1000-5000个节点的文档（带流式处理） |
| 内存占用 | <500MB | 在正常生产负载下 |
| 缓存命中率 | >80% | 初始预热期后 |
性能特性
多层缓存系统
- 解析缓存：100MB LRU缓存，解析Markdown的TTL为30分钟
- 转换缓存：50MB LRU缓存，NM3文档的TTL为15分钟
- XML缓存：NodeCache，100个键，TTL为10分钟
- SHA-256哈希：用于可靠命中检测的确定性缓存键
流式处理
- 对大于50KB的文档自动激活
- 不管文档大小，内存使用量恒定
- 行行解析，分块处理
- 高效处理多GB文档
并行处理
- 工作线程池用于CPU密集型操作
- 多核空间优化
- 可配置的工作线程数量（默认：CPU核心数-1）
- 自动负载均衡
性能监控
- Prometheus指标集成
- 实时缓存命中/未命中统计
- 内存使用跟踪
- 转换持续时间直方图
- 节点计数分布
内存管理
- 每30秒自动监控
- 警告阈值：400MB堆使用量
- 临界阈值：800MB堆使用量
- 在临界状态下自动垃圾收集
- 详细的内存统计
优化指南
为了获得最佳性能：
- 启用缓存：缓存默认启用；确保没有禁用
- 复用内容：相同的Markdown将从缓存中提供，时间小于10毫秒
- 大型文档：大于50KB的文档自动使用流式处理
- 内存限制：使用
get_performance_stats工具监控内存使用 - 清除缓存：如果内存受限，请使用
clear_cache工具
👨💻 开发者指南
项目结构
markdown3d-mcp/
├── src/
│ ├── index.ts # 入口点
│ ├── server.ts # MCP服务器实现
│ ├── core/
│ │ ├── parser.ts # Markdown解析
│ │ ├── transformer.ts # 基本转换
│ │ ├── enhanced-transformer.ts # 高级转换（第二阶段）
│ │ ├── optimized-transformer.ts # 性能优化转换器（第四阶段）
│ │ ├── xml-builder.ts # NM3 XML生成
│ │ ├── reference-extractor.ts # 交叉引用检测
│ │ ├── content-classifier.ts # 语义分析
│ │ ├── intelligent-shape-assigner.ts
│ │ ├── intelligent-color-mapper.ts
│ │ ├── spatial-optimizer-v2.ts # 空间布局优化（第三阶段）
│ │ ├── collision-detector.ts # 碰撞检测（第三阶段）
│ │ ├── force-directed-3d.ts # 力导向布局（第三阶段）
│ │ ├── layout-templates.ts # 布局模板（第三阶段）
│ │ ├── octree.ts # 八叉树空间索引（第三阶段）
│ │ ├── cache-manager.ts # 多层缓存（第四阶段）
│ │ ├── stream-processor.ts # 流式处理器（第四阶段）
│ │ ├── worker-pool.ts # 工作线程池（第四阶段）
│ │ ├── metrics.ts # 性能指标（第四阶段）
│ │ └── memory-monitor.ts # 内存管理（第四阶段）
│ ├── models/
│ │ └── types.ts # TypeScript接口
│ ├── constants/
│ │ └── validation.ts # 有效颜色和形状
│ ├── utils/ # 工具函数
│ └── handlers/ # 额外处理器
├── docs/ # 文档
│ ├── Markdown3D-Phase0.md # 概览
│ ├── Markdown3D-Phase1.md # 基础实现
│ ├── Markdown3-Phase2.md # 高级功能
│ ├── Markdown3D-Phase3.md # 空间优化
│ ├── Markdown3D-Phase4.md # 性能与可扩展性
│ └── instruct/ # 详细阶段指令
├── tests/ # 测试套件
├── output/ # 生成的NM3文件
└── specs/ # NM3规范
开发流程
# 安装依赖
npm install
# 开发模式（监视更改）
npm run dev
# 构建生产环境
npm run build
# 运行测试
npm run test
# 启动MCP服务器
npm start
从源代码构建
# 克隆仓库
git clone https://github.com/yourusername/markdown3d-mcp.git
cd markdown3d-mcp
# 安装依赖
npm install
# 构建TypeScript
npm run build
# 测试构建
node dist/index.js
开发阶段
该项目分为6个开发阶段：
-
第一阶段：基础及基本功能 ✅
- 带有基本转换的MCP服务器
- 严格的验证（16种颜色，5种形状）
- 简单的空间定位
-
第二阶段：高级解析与智能 ✅
- 交叉引用检测
- 使用NLP的语义分析
- 智能形状和颜色分配
- 关系映射
-
第三阶段：空间优化 ✅
- 力导向图算法
- 碰撞检测和解决
- 布局模板
- 八叉树空间索引
-
第四阶段：性能与可扩展性 ✅
- 多层缓存（解析、转换、XML）
- 大文档的流式处理
- 工作线程池用于并行处理
- 使用Prometheus指标的性能监控
- 带有自动GC的内存管理
- 带有智能缓存的优化转换器
-
第五阶段：测试与质量保证（计划中）
- 综合测试套件
- 验证