
Quarkdown MCP Server
Provides comprehensive Quarkdown document processing capabilities, enabling AI assistants to compile, validate, preview, and batch process Quarkdown documents through a standardized interface.
README
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\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
最新改进 (v1.1)
🎯 核心改进
- 命令行兼容性修正: 修正了与 Quarkdown CLI 的参数映射问题,确保编译功能正常工作
- 增强语法验证: 新增
strict_mode
支持和 Quarkdown 特定语法检查 - 改进错误处理: 更准确的编译状态判断和详细的错误报告
- 配置类扩展: 添加
create_temp_dir
方法,支持临时目录管理 - 代码质量提升: 清理重复代码,增强代码健壮性
📋 改进详情
-
命令行参数修正
- 修正
--output-format
→-r
(render target) - 修正
--output-path
→-o
(output directory) - 添加
--pretty
和--nowrap
选项支持
- 修正
-
语法验证增强
- 支持
strict_mode
参数 - 检查
.callout
缺少 type 参数 - 检查函数调用语法错误
- 检查未知容器类型
- 检查图片缺少 alt 文本
- 支持
-
错误处理改进
- 检查返回码和输出内容中的错误模式
- 详细的错误和警告分类
- 更友好的错误消息
故障排除
常见问题
-
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 工具实现
- 支持文档编译、项目创建、语法验证、预览服务器、批量处理
支持
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.