Quarkdown MCP 服务器 (v1.1)

一个模型上下文协议 (MCP) 服务器，提供全面的 Quarkdown 文档处理功能。该服务器使 AI 助手能够通过标准化接口编译、验证、预览和批量处理 Quarkdown 文档。

最新版本 v1.1 - 包含重要的命令行兼容性修正、增强语法验证和改进的错误处理机制。

关于 Quarkdown

Quarkdown 是一个现代化、可扩展的 Markdown 处理器，它扩展了 CommonMark 和 GitHub Flavored Markdown，具有强大的功能：

高级语法：函数、变量、条件语句、循环等
多种输出格式：HTML、PDF、LaTeX、Markdown、DOCX
模板系统：可自定义的主题和文档类型
标准库：用于布局、数学、数据处理和可视化的内置模块
交互元素：幻灯片、可折叠部分和动态内容

功能特性

🚀 核心 MCP 工具

文档编译 (compile_document)：将 Quarkdown 源码转换为 HTML、PDF、LaTeX、Markdown 格式
项目创建 (create_project)：使用模板生成新的 Quarkdown 项目（基础、演示、书籍、文章）
语法验证 (validate_markdown)：检查文档语法，支持严格模式和全面的错误报告
预览服务器 (preview_server)：启动本地开发服务器，支持实时重载和主题
批量处理 (convert_batch)：高效并行处理多个文档

🎯 核心能力

多格式输出：支持 HTML、PDF、LaTeX、Markdown、DOCX
模板系统：应用自定义模板和主题（基础、演示、书籍、文章）
实时预览：实时文档预览，支持自动重载
批量操作：并行处理多个文档，可配置工作线程数
错误处理：全面验证和详细错误报告
项目管理：完整的项目脚手架，支持 Git 初始化

安装

前置要求

Python 3.8 或更高版本（推荐 Python 3.11+）
Java 11 或更高版本（用于 Quarkdown JAR 执行）
Quarkdown JAR 文件（包含在 quarkdown/build/libs/ 目录中）

快速安装

# 克隆仓库
git clone <repository-url>
cd quarkdown-mcp

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # macOS/Linux
# 或 Windows: venv\Scripts\activate

# 安装核心依赖
pip install -r requirements.txt

# 以开发模式安装
pip install -e .

开发环境设置

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 系统: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

# 或者单独安装开发依赖
pip install -r requirements.txt
pip install pytest>=7.0.0 pytest-asyncio>=0.21.0 pytest-cov>=4.0.0
pip install black>=23.0.0 isort>=5.12.0 flake8>=6.0.0 mypy>=1.0.0

# 安装 pre-commit 钩子（如果使用）
pre-commit install

配置

环境变量

# 必需：Quarkdown JAR 文件路径（使用实际的绝对路径）
export QUARKDOWN_JAR_PATH="/path/to/quarkdown-mcp/quarkdown/build/libs/quarkdown.jar"

# 可选：处理临时目录
export QUARKDOWN_TEMP_DIR="/tmp/quarkdown"

# 可选：日志级别
export QUARKDOWN_LOG_LEVEL="INFO"

MCP 客户端配置

添加到您的 MCP 客户端配置：

{
  "mcpServers": {
    "quarkdown": {
      "command": "python",
      "args": ["-m", "quarkdown_mcp.server"],
      "cwd": "/path/to/quarkdown-mcp/src",
      "env": {
        "QUARKDOWN_JAR_PATH": "/path/to/quarkdown-mcp/quarkdown/build/libs/quarkdown.jar"
      }
    }
  }
}

Quarkdown JAR 位置

Quarkdown JAR 文件包含在此仓库中，实际位置为：

quarkdown-mcp/quarkdown/build/libs/quarkdown.jar

确保在配置中使用此 JAR 文件的绝对路径。

运行服务器

启动 MCP 服务器

# 进入源代码目录
cd /path/to/quarkdown-mcp/src

# 以模块方式运行服务器
python -m quarkdown_mcp.server

验证配置

# 运行配置测试脚本
python tests/test_server_config.py

文档编译

# 将 Quarkdown 编译为 HTML
result = await mcp_client.call_tool("compile_document", {
    "source_content": "# Hello Quarkdown\n\nThis is a **sample** document.",
    "output_format": "html",
    "template": "academic"
})

项目创建

# 创建新的 Quarkdown 项目
result = await mcp_client.call_tool("create_project", {
    "project_name": "my-document",
    "project_path": "/path/to/projects",
    "template": "book",
    "include_examples": True
})

语法验证

# 基础语法验证
result = await mcp_client.call_tool("validate_markdown", {
    "source_content": "# Document\n\n{{ invalid_function() }}",
    "strict_mode": False,
    "check_functions": True
})

# 严格模式验证（推荐）
result = await mcp_client.call_tool("validate_markdown", {
    "source_content": "# Document\n\n.callout\n\n![](image.png)\n\n{{ func(",
    "strict_mode": True,
    "check_functions": True,
    "check_variables": True
})
# 返回详细的错误和警告信息，包括：
# - Callout 缺少 type 参数
# - 图片缺少 alt 文本
# - 函数调用语法错误

预览服务器

# 启动预览服务器
result = await mcp_client.call_tool("preview_server", {
    "source_content": "# Live Preview\n\nEdit and see changes!",
    "port": 8080,
    "auto_reload": True,
    "theme": "dark"
})

批量处理

# 处理多个文档
result = await mcp_client.call_tool("convert_batch", {
    "documents": [
        {"name": "doc1", "content": "# Document 1"},
        {"name": "doc2", "content": "# Document 2"}
    ],
    "output_format": "pdf",
    "parallel_processing": True,
    "generate_index": True
})

工具参考

compile_document

将 Quarkdown 源内容编译为各种输出格式。

参数：

source_content (string, 可选)：Quarkdown 源内容（input_file 的替代选项）
input_file (string, 可选)：输入 Quarkdown 文件路径
output_format (string)：输出格式（html、pdf、tex、md）
output_file (string, 可选)：输出文件路径
pretty_output (boolean)：启用美化格式
wrap_output (boolean)：启用输出包装
working_directory (string, 可选)：编译工作目录

create_project

创建具有目录结构和模板的新 Quarkdown 项目。

参数：

project_path (string, 必需)：创建项目的目录路径
project_name (string, 可选)：项目名称
template (string)：项目模板（basic、presentation、book、article）
include_examples (boolean)：包含示例文件
include_docs (boolean)：包含文档
git_init (boolean)：初始化 Git 仓库

validate_markdown

验证 Quarkdown 文档语法并报告错误。

参数：

source_content (string, 必需)：要验证的内容
strict_mode (boolean)：启用严格验证模式
check_functions (boolean)：验证函数语法
check_variables (boolean)：验证变量引用
check_links (boolean)：验证外部链接

preview_server

启动具有实时重载功能的本地预览服务器。

参数：

source_content (string, 必需)：要预览的内容
port (integer)：服务器端口（默认：8080）
auto_reload (boolean)：启用自动重载
theme (string)：预览主题
watch_files (array)：要监视变化的其他文件
open_browser (boolean)：启动时自动打开浏览器

convert_batch

在批处理模式下并行处理多个文档。

参数：

documents (array, 必需)：包含名称、内容和可选 output_file 的文档列表
output_format (string)：输出格式（html、pdf、latex、markdown、docx）
output_directory (string, 可选)：输出文件目录
template (string, 可选)：应用于所有文档的模板
parallel_processing (boolean)：启用并行处理
max_workers (integer)：最大并行工作线程数（默认：4）

架构

项目结构

quarkdown-mcp/
├── .github/                  # GitHub Actions 工作流程
│   └── workflows/
│       └── ci.yml
├── .gitignore
├── LICENSE
├── README.md                 # 本文件
├── config.example.json       # MCP 服务器配置文件示例
├── pyproject.toml            # 项目构建和依赖管理 (PEP 517/518)
├── quarkdown/                # Quarkdown JAR 包及其相关文件 (子模块或直接包含)
├── requirements-dev.txt      # 开发环境额外依赖
├── requirements.txt          # 核心依赖
├── rewritten_docs/           # (可能是文档重写或示例输出目录)
├── scripts/                  # 辅助脚本 (如开发、测试运行器)
│   ├── dev.py
│   └── test_runner.py
├── setup.cfg                 # setuptools 配置文件 (部分项目可能仍在使用)
├── setup.py                  # setuptools 构建脚本 (如果 pyproject.toml 不完整或用于旧版兼容)
├── src/                      # 主要源代码
│   └── quarkdown_mcp/
│       ├── __init__.py
│       ├── core/               # 核心逻辑 (配置、JAR 包装器等)
│       │   ├── __init__.py
│       │   ├── config.py
│       │   └── wrapper.py
│       ├── server.py           # MCP 服务器主入口
│       └── tools/              # MCP 工具实现
│           ├── __init__.py
│           ├── base.py
│           ├── batch.py
│           ├── compile.py
│           ├── create_project.py
│           ├── preview.py
│           └── validate.py
├── record/
│   └── record.md             # 项目改进和测试记录
├── tests/                    # 测试脚本
│   ├── check_mcp.py
│   ├── final_test.py
│   ├── functional_test.py
│   ├── quick_test.py
│   ├── test_import.py
│   ├── test_improvements.py
│   └── test_server_config.py
└── test_document.qmd         # Quarkdown 测试文档示例

核心组件

Server：主 MCP 服务器实现，包含工具注册
Config：配置管理和验证
Wrapper：用于 Quarkdown 执行的 Java 子进程包装器
Tools：遵循 MCP 协议的各个工具实现

开发

运行测试

# 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=quarkdown_mcp

# 运行特定测试类别
pytest -m unit
pytest -m integration

代码质量

# 格式化代码
black src/ tests/
isort src/ tests/

# 代码检查
flake8 src/ tests/
mypy src/

# 运行所有质量检查
pre-commit run --all-files

构建分发包

# 构建包
python -m build

# 本地安装
pip install dist/quarkdown_mcp-*.whl

故障排除

常见问题

MCP 服务器启动错误
- 问题: TypeError: Server.get_capabilities() missing 2 required positional arguments
- 解决方案: 确保使用 MCP SDK 1.0+ 版本，服务器代码已更新以支持新的 API
模块导入错误
- 问题: ModuleNotFoundError: No module named 'quarkdown_mcp.tools.xxx'
- 解决方案: 确保在 src 目录下运行服务器：cd src && python -m quarkdown_mcp.server
找不到 Java
- 问题: Java 未安装或不在 PATH 中
- 解决方案: 确保安装了 Java 11+ 并在 PATH 中
找不到 JAR 文件
- 问题: QUARKDOWN_JAR_PATH 环境变量未设置或路径错误
- 解决方案: 设置正确的绝对路径：/path/to/quarkdown-mcp/quarkdown/build/libs/quarkdown.jar
权限错误
- 问题: 临时目录权限不足
- 解决方案: 检查临时目录的文件权限，或设置 QUARKDOWN_TEMP_DIR 到可写目录
端口冲突
- 问题: 预览服务器端口被占用
- 解决方案: 为预览服务器使用不同端口
编译失败问题 (新增)
- 问题: 编译返回成功但实际失败
- 解决方案: 检查输出日志中的错误信息，确保 Quarkdown 语法正确
语法验证问题 (新增)
- 问题: 语法检查报告不准确
- 解决方案: 使用 strict_mode: true 获得更详细的检查结果

调试模式

# 启用调试日志
export QUARKDOWN_LOG_LEVEL="DEBUG"
cd src
python -m quarkdown_mcp.server

版本兼容性

MCP SDK: 需要 1.0.0 或更高版本
Python: 支持 3.8+，推荐 3.11+
Java: 需要 11 或更高版本

性能调优

根据系统资源调整批处理的 max_workers
使用 SSD 存储临时文件以提高 I/O 性能
为大文档处理增加 JVM 堆大小

贡献

我们欢迎贡献！详情请参阅我们的贡献指南。

开发工作流程

Fork 仓库
创建功能分支
进行更改并添加测试
运行质量检查
提交 pull request

代码标准

遵循 PEP 8 风格指南
为所有函数添加类型提示
编写全面的测试
更新文档

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

Quarkdown - 底层文档处理引擎
Model Context Protocol - 协议规范
贡献者和维护者

更新日志

v1.1 (2024-12)

🔧 重要修复

修正了与 Quarkdown CLI 的命令行参数映射问题
修正 --output-format → -r 和 --output-path → -o
添加 --pretty 和 --nowrap 选项支持

✨ 新功能

增强语法验证：支持 strict_mode 参数
新增 Quarkdown 特定语法检查（callout、函数、容器、图片）
配置类新增 create_temp_dir 方法

🛠️ 改进

更准确的编译状态判断和错误检测
详细的错误和警告分类
清理重复代码，提升代码质量
更友好的错误消息和建议

📋 测试

添加改进功能的验证测试
确保向后兼容性

v1.0 (2024-11)

初始版本发布
基础 MCP 工具实现
支持文档编译、项目创建、语法验证、预览服务器、批量处理

支持

📖 文档
🐛 问题跟踪
💬 讨论
📧 邮件支持
📁 改进记录

Quarkdown MCP Server

README Documentation

Quarkdown MCP 服务器 (v1.1)

关于 Quarkdown

功能特性

🚀 核心 MCP 工具

🎯 核心能力

安装

前置要求

快速安装

开发环境设置

配置

环境变量

MCP 客户端配置

Quarkdown JAR 位置

运行服务器

启动 MCP 服务器

验证配置

文档编译

项目创建

语法验证

预览服务器

批量处理

工具参考

compile_document

create_project

validate_markdown

preview_server

convert_batch

架构

项目结构

核心组件

开发

运行测试

代码质量

构建分发包

最新改进 (v1.1)

🎯 核心改进

📋 改进详情

故障排除

常见问题

调试模式

版本兼容性

性能调优

贡献

开发工作流程

代码标准

许可证

致谢

更新日志

v1.1 (2024-12)

v1.0 (2024-11)

支持

Quick Install

Quick Actions

Key Features