mdatlas
用于Markdown文档结构分析和导航的模型上下文协议（MCP）服务器。
概述
mdatlas提供了对Markdown文档结构信息的高效访问，允许AI模型有选择地检索特定部分，而无需加载整个文件。这解决了处理大型Markdown文档时上下文窗口限制的问题。
特性
- 文档结构分析：从Markdown文件中提取层次结构（H1-H6标题）
- 基于区段的访问：通过唯一ID检索特定部分
- 元数据抽取：获取字符数、行号和嵌套信息
- 多种输出格式：JSON、Markdown和纯文本
- CLI接口：可直接使用的独立命令行工具
- MCP服务器：用于AI模型集成的基于STDIO的服务器（计划中）
安装
从源头构建
# Clone the repository
git clone https://github.com/mosaan/mdatlas.git
cd mdatlas
# Build the binary
make build
# Or install to GOPATH/bin
make install跨平台构建
# Build for all supported platforms
make release这将为以下对象创建二进制文件：
- Linux（amd64）
- macOS（amd64、arm64）
- Windows（amd64）
用法
CLI命令
提取文档结构
# Basic structure extraction
mdatlas structure document.md
# Pretty-printed JSON output
mdatlas structure document.md --pretty
# Limit heading depth
mdatlas structure document.md --max-depth 3输出示例：
{
"file_path": "/path/to/document.md",
"total_chars": 15000,
"total_lines": 500,
"structure": [
{
"id": "section_48c2fc6ee5f4af76",
"level": 1,
"title": "Introduction",
"char_count": 800,
"line_count": 25,
"start_line": 1,
"end_line": 25,
"children": [
{
"id": "section_a1b2c3d4e5f6g7h8",
"level": 2,
"title": "Background",
"char_count": 400,
"line_count": 12,
"start_line": 5,
"end_line": 16,
"children": []
}
]
}
],
"last_modified": "2025-07-09T14:00:00Z"
}摘录章节内容
# Extract specific section by ID
mdatlas section document.md --section-id section_48c2fc6ee5f4af76
# Include child sections
mdatlas section document.md --section-id section_48c2fc6ee5f4af76 --include-children
# Different output formats
mdatlas section document.md --section-id section_48c2fc6ee5f4af76 --format json
mdatlas section document.md --section-id section_48c2fc6ee5f4af76 --format plain其他命令
# Show version information
mdatlas version
# Run as MCP server (not yet implemented)
mdatlas --mcp-server --base-dir /path/to/documents
# Show help
mdatlas --help
mdatlas structure --help
mdatlas section --helpMCP服务器模式
*注：MCP服务器功能已计划，但尚未实现。*
完成后，MCP服务器将提供：
- 工具:
- get_markdown_structure：提取文档结构 - get_markdown_section：检索部分内容 - search_markdown_content：在文档中搜索
- 资源:
- markdown://file/{file_path}/structure：文档结构 - markdown://file/{file_path}/section/{section_id}：章节内容
发展
先决条件
- 转到1.22.2或更高版本
- Make（用于构建自动化）
建筑
# Download dependencies
make deps
# Build the project
make build
# Run tests
make test
# Format code
make fmt
# Run linter (if golangci-lint is installed)
make lint
# Clean build artifacts
make clean项目结构
mdatlas/
├── cmd/
│ └── mdatlas/
│ └── main.go # Entry point
├── internal/
│ ├── core/
│ │ └── parser.go # Markdown parsing logic
│ ├── mcp/
│ │ └── server.go # MCP server (stub)
│ └── cli/
│ ├── root.go # Root command
│ ├── structure.go # Structure command
│ └── section.go # Section command
├── pkg/
│ └── types/
│ └── document.go # Type definitions
├── docs/ # Documentation
├── bin/ # Built binaries
├── go.mod # Go module file
├── go.sum # Go dependencies
└── Makefile # Build automation实施状态
✅ 已完成的功能
- \[x\] 项目基本结构
- \[x\] 使用goldmark进行Markdown解析
- \[x\] 文档结构提取
- \[x\] 章节内容检索
- \[x\] 带有cobra的CLI界面
- \[x\] JSON输出格式
- \[x\] 跨平台构建
- \[x\] 使用Make构建自动化
🚧 进行中
- \[\]MCP服务器实现
- \[\]STDIO通信协议
- \[\]文件访问控制和安全
- \[\]缓存系统
- \[\]性能优化
📋 计划的功能
- \[\]文件监视和自动刷新
- \[\]内容搜索功能
- \[\]多文档支持
- \[\]配置文件支持
- \[\]自定义解析器的插件系统
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 运行测试：
make test - 格式代码：
make fmt - 提交拉取请求
许可证
\[待添加许可证信息\]
技术细节
依赖项
- 记录搜索接收机：Markdown解析
- 眼镜蛇：CLI框架
- 标准库：核心功能
建筑
- 解析器：使用goldmark AST进行可靠的Markdown解析
- 结构：具有唯一ID的分层部分表示
- 命令行界面：具有多种输出格式的命令行界面
- 主控程序：用于AI集成的未来基于STDIO的服务器
安全
- 文件访问将仅限于指定的基本目录
- 路径遍历保护
- 输入验证和净化