README.md•15.6 kB
# 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/` 目录中)
### 快速安装
```bash
# 克隆仓库
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 .
```
### 开发环境设置
```bash
# 创建虚拟环境
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
```
## 配置
### 环境变量
```bash
# 必需: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 客户端配置:
```json
{
"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 服务器
```bash
# 进入源代码目录
cd /path/to/quarkdown-mcp/src
# 以模块方式运行服务器
python -m quarkdown_mcp.server
```
### 验证配置
```bash
# 运行配置测试脚本
python tests/test_server_config.py
```
### 文档编译
```python
# 将 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"
})
```
### 项目创建
```python
# 创建新的 Quarkdown 项目
result = await mcp_client.call_tool("create_project", {
"project_name": "my-document",
"project_path": "/path/to/projects",
"template": "book",
"include_examples": True
})
```
### 语法验证
```python
# 基础语法验证
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 文本
# - 函数调用语法错误
```
### 预览服务器
```python
# 启动预览服务器
result = await mcp_client.call_tool("preview_server", {
"source_content": "# Live Preview\n\nEdit and see changes!",
"port": 8080,
"auto_reload": True,
"theme": "dark"
})
```
### 批量处理
```python
# 处理多个文档
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 协议的各个工具实现
## 开发
### 运行测试
```bash
# 运行所有测试
pytest
# 运行覆盖率测试
pytest --cov=quarkdown_mcp
# 运行特定测试类别
pytest -m unit
pytest -m integration
```
### 代码质量
```bash
# 格式化代码
black src/ tests/
isort src/ tests/
# 代码检查
flake8 src/ tests/
mypy src/
# 运行所有质量检查
pre-commit run --all-files
```
### 构建分发包
```bash
# 构建包
python -m build
# 本地安装
pip install dist/quarkdown_mcp-*.whl
```
## 最新改进 (v1.1)
### 🎯 核心改进
- **命令行兼容性修正**: 修正了与 Quarkdown CLI 的参数映射问题,确保编译功能正常工作
- **增强语法验证**: 新增 `strict_mode` 支持和 Quarkdown 特定语法检查
- **改进错误处理**: 更准确的编译状态判断和详细的错误报告
- **配置类扩展**: 添加 `create_temp_dir` 方法,支持临时目录管理
- **代码质量提升**: 清理重复代码,增强代码健壮性
### 📋 改进详情
1. **命令行参数修正**
- 修正 `--output-format` → `-r` (render target)
- 修正 `--output-path` → `-o` (output directory)
- 添加 `--pretty` 和 `--nowrap` 选项支持
2. **语法验证增强**
- 支持 `strict_mode` 参数
- 检查 `.callout` 缺少 type 参数
- 检查函数调用语法错误
- 检查未知容器类型
- 检查图片缺少 alt 文本
3. **错误处理改进**
- 检查返回码和输出内容中的错误模式
- 详细的错误和警告分类
- 更友好的错误消息
## 故障排除
### 常见问题
1. **MCP 服务器启动错误**
- **问题**: `TypeError: Server.get_capabilities() missing 2 required positional arguments`
- **解决方案**: 确保使用 MCP SDK 1.0+ 版本,服务器代码已更新以支持新的 API
2. **模块导入错误**
- **问题**: `ModuleNotFoundError: No module named 'quarkdown_mcp.tools.xxx'`
- **解决方案**: 确保在 `src` 目录下运行服务器:`cd src && python -m quarkdown_mcp.server`
3. **找不到 Java**
- **问题**: Java 未安装或不在 PATH 中
- **解决方案**: 确保安装了 Java 11+ 并在 PATH 中
4. **找不到 JAR 文件**
- **问题**: `QUARKDOWN_JAR_PATH` 环境变量未设置或路径错误
- **解决方案**: 设置正确的绝对路径:`/path/to/quarkdown-mcp/quarkdown/build/libs/quarkdown.jar`
5. **权限错误**
- **问题**: 临时目录权限不足
- **解决方案**: 检查临时目录的文件权限,或设置 `QUARKDOWN_TEMP_DIR` 到可写目录
6. **端口冲突**
- **问题**: 预览服务器端口被占用
- **解决方案**: 为预览服务器使用不同端口
7. **编译失败问题** (新增)
- **问题**: 编译返回成功但实际失败
- **解决方案**: 检查输出日志中的错误信息,确保 Quarkdown 语法正确
8. **语法验证问题** (新增)
- **问题**: 语法检查报告不准确
- **解决方案**: 使用 `strict_mode: true` 获得更详细的检查结果
### 调试模式
```bash
# 启用调试日志
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 堆大小
## 贡献
我们欢迎贡献!详情请参阅我们的[贡献指南](CONTRIBUTING.md)。
### 开发工作流程
1. Fork 仓库
2. 创建功能分支
3. 进行更改并添加测试
4. 运行质量检查
5. 提交 pull request
### 代码标准
- 遵循 PEP 8 风格指南
- 为所有函数添加类型提示
- 编写全面的测试
- 更新文档
## 许可证
本项目采用 MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 致谢
- [Quarkdown](https://github.com/iamgio/quarkdown) - 底层文档处理引擎
- [Model Context Protocol](https://modelcontextprotocol.io/) - 协议规范
- 贡献者和维护者
## 更新日志
### 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 工具实现
- 支持文档编译、项目创建、语法验证、预览服务器、批量处理
## 支持
- 📖 [文档](https://quarkdown-mcp.readthedocs.io)
- 🐛 [问题跟踪](https://github.com/quarkdown/quarkdown-mcp/issues)
- 💬 [讨论](https://github.com/quarkdown/quarkdown-mcp/discussions)
- 📧 [邮件支持](mailto:support@quarkdown-mcp.org)
- 📁 [改进记录](record/record.md)