Markdown TOC MCP Server

一个专门用于 Markdown 文档目录分析和处理的 Model Context Protocol (MCP) 服务器，为 TRAE IDE 提供强大的 Markdown 文档处理能力。

可以先阅读 从零构建 MCP 服务：为 TRAE IDE 添加智能 Markdown TOC 处理能力 来了解背后的故事！

1. 功能说明

功能模块	主要特性	详细说明
提取文档目录	自动识别 Markdown 标题	智能解析文档中的各级标题结构
	生成层级目录结构	构建完整的目录层次关系
	包含行号信息	提供精确的标题位置信息
检查编号问题	检测重复编号	识别文档中重复的章节编号
	发现不连续编号	发现跳跃或缺失的编号序列
	分析格式问题	检查编号格式的一致性
生成目录内容	创建格式化 TOC	生成美观的目录内容
	支持多种输出格式	提供 Markdown、HTML、文本格式
	可自定义深度	灵活控制目录显示层级

MCP 工具唤醒方法：

请使用 MCP 工具提取文档的目录结构。

或者直接：

请提取文档的目录结构

2. 项目结构

markdown-mcp/
├── README.md                    # 项目说明文档
├── LICENSE                      # 许可证文件
├── requirements.txt             # Python 依赖包
├── setup.py                     # 安装配置文件
├── run_tests.py                 # 测试运行脚本
├── start_mcp_for_trae.sh       # TRAE IDE 启动脚本
├── stop_mcp_for_trae.sh        # TRAE IDE 停止脚本
├── config/                      # 配置文件目录
│   ├── config.yaml             # 主配置文件
│   └── trae_mcp_config.json    # TRAE IDE 配置
├── src/                         # 源代码目录
│   ├── __init__.py
│   ├── markdown_toc/           # 核心模块
│   │   ├── __init__.py
│   │   └── extractor.py        # TOC 提取器
│   └── server/                 # 服务器模块
│       ├── __init__.py
│       └── mcp_server.py       # MCP 服务器主程序
├── tests/                      # 测试文件目录
│   ├── __init__.py
│   ├── fixtures/               # 测试数据
│   ├── test_*.py              # 各种测试文件
│   └── test_config.py         # 测试配置
└── docs/                       # 文档目录
    ├── setup.md               # 安装说明
    ├── usage.md               # 使用指南
    ├── testing.md             # 测试说明
    └── reports/               # 测试报告

---

3. TRAE MCP 配置

请参考 安装说明 进行安装和配置。

---

4. 测试说明

请参考 测试说明 进行测试。

---

5. 功能详细说明

5.1 extract_markdown_toc

从 Markdown 文档中提取目录结构。

参数：

• file_path (string, 必需): Markdown 文件路径
• output_format (string, 可选): 输出格式，可选值：json, text, markdown，默认为 json
• max_depth (integer, 可选): 最大提取深度，默认为 6
• min_depth (integer, 可选): 最小提取深度，默认为 1
• include_line_numbers (boolean, 可选): 是否包含行号，默认为 false

示例：

{
  "name": "extract_markdown_toc",
  "arguments": {
    "file_path": "/path/to/document.md",
    "output_format": "json",
    "max_depth": 4,
    "include_line_numbers": true
  }
}

5.2 analyze_numbering_issues

分析 Markdown 文档中的编号问题。

功能说明：

该工具会智能识别文档中的有编号标题和无编号标题，只对有编号的标题进行编号问题分析。无编号标题（如以 emoji、中文、纯文本开头的标题）不会参与编号连续性检查，避免误报。

参数：

• file_path (string, 必需): Markdown 文件路径
• check_types (array, 可选): 检查类型，可选值：duplicates, discontinuous，默认为 ["duplicates", "discontinuous"]

行为逻辑：

• duplicates: 检查是否存在重复的编号（如两个 "1.1" 标题）
• discontinuous: 检查编号是否连续（如 "1.1" 后直接跟 "1.3"，缺少 "1.2"）
• 只分析实际有编号的标题，忽略无编号标题
• 支持多种编号格式：数字编号（1.、1.1）、中文编号（一、二）等

示例：

{
  "name": "analyze_numbering_issues",
  "arguments": {
    "file_path": "/path/to/document.md",
    "check_types": ["duplicates", "discontinuous"]
  }
}

5.3 generate_toc

生成格式化的 TOC 内容供插入文档。

参数：

• file_path (string, 必需): Markdown 文件路径
• format_type (string, 可选): 输出格式，可选值：markdown, html, text，默认为 markdown
• include_links (boolean, 可选): 是否包含链接（仅对 markdown 格式有效），默认为 true
• max_level (integer, 可选): 最大包含的标题级别，默认为 6

示例：

{
  "name": "generate_toc",
  "arguments": {
    "file_path": "/path/to/document.md",
    "format_type": "markdown",
    "include_links": true,
    "max_level": 4
  }
}

---

6. 开发和调试

6.1 开发环境设置

# 安装开发依赖
pip install -r requirements.txt

# 代码格式化
black src/

# 代码检查
flake8 src/
mypy src/

6.2 调试模式

在 config/config.yaml 中启用调试模式：

development:
  debug: true

logging:
  level: "DEBUG"

6.3 日志分析

查看详细日志：

# 查看日志文件
tail -f logs/mcp_server.log

# 或在启动时查看实时日志
./start_mcp_for_trae.sh

---

7. 常见问题

问题：服务器启动失败：

# 检查 Python 版本
python3 --version

# 检查依赖安装
pip list | grep mcp

# 查看错误日志
tail -f logs/mcp_server.log

问题：文件权限错误：

# 检查文件权限
ls -la start_mcp_for_trae.sh
chmod +x start_mcp_for_trae.sh

问题：编码错误：

服务器支持多种编码格式（UTF-8、GBK 等），如果遇到编码问题，请确保文件编码正确。

---