72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
---
|
||
name: markdownify-mcp
|
||
description: >-
|
||
使用 req-doc-markdownify（mcp-markdownify-server）将本地 PDF、DOCX 等转为 Markdown，供需求分析使用。
|
||
在用户要解析需求文档、钉钉导出文件、PRD 转文本时使用。
|
||
---
|
||
|
||
# 需求文档 Markdownify MCP 使用指南
|
||
|
||
> **配图 PRD**：Word 含截图时 **优先** 使用 `admin/scripts/docx_to_markdown_with_images.py`（或复制到全局脚本目录），生成含 `` 的 `.md`；纯文本、简单结构可用本 MCP `docx-to-markdown`。得到 `.md` 后，在业务仓库用 **`requirements-analysis`** 直接 **Read** 该文件做落点与清单，无需单独的「整理版」智能体。
|
||
|
||
## 何时使用
|
||
|
||
- 已把钉钉导出的 **PDF / Word（.docx）** 存到本机，需要转成 Markdown 再给 AI 做需求分析
|
||
- 用户提供「本地文件路径」，希望抽取正文与表格（效果受版式影响，需人工抽查）
|
||
|
||
## Cursor 中的服务名
|
||
|
||
配置键名：`req-doc-markdownify`（见 `admin/mcp.json`）。
|
||
|
||
首次用 `npx` 拉起时，包内 `preinstall` 会尝试执行 `python -m venv` 并安装 `markitdown`，**需本机已安装 Python 且可在终端执行 `python`**。若失败，请在终端手动执行一次 `npx -y mcp-markdownify-server` 查看报错。
|
||
|
||
**手动补环境（在 `mcp-markdownify-server` 包目录下，与 `package.json` 同级）**：
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\pip.exe install "markitdown[docx]"
|
||
```
|
||
|
||
仅装 `markitdown` 不含 Word 依赖时，调用 `docx-to-markdown` 会报 `MissingDependencyException`；Word 须使用 **`markitdown[docx]`**（或 `markitdown[all]`）。PDF 可再按需安装 `markitdown[pdf]` 等，见 markitdown 文档。
|
||
|
||
## 常用工具
|
||
|
||
以下工具参数中的 **`filepath` 必须为绝对路径**（Windows 例如 `D:\\docs\\需求.docx`）。
|
||
|
||
| tool | 说明 | 必选参数 |
|
||
|----------------------|-------------|------------|
|
||
| `docx-to-markdown` | Word 转 MD | `filepath` |
|
||
| `pdf-to-markdown` | PDF 转 MD | `filepath` |
|
||
| `get-markdown-file` | 读取已有 .md | `filepath` |
|
||
|
||
其他：`xlsx-to-markdown`、`pptx-to-markdown`、`image-to-markdown`、`webpage-to-markdown` 等见上游 README。
|
||
|
||
## 可选环境变量
|
||
|
||
- **`MD_SHARE_DIR`**：若设置，则 `get-markdown-file` 仅能读取该目录下的 Markdown，降低误读路径风险。
|
||
|
||
## 限制说明
|
||
|
||
- 上游 README 标注 **Windows 支持仍在完善**，复杂 PDF/扫描件可能需 OCR 或改导出 Word 再转。
|
||
- **钉钉链拉取** 不在本 MCP 内；流程为：钉钉下载 → 本地路径 → 调用 `docx-to-markdown` / `pdf-to-markdown`。
|
||
|
||
### Word 里的截图/图片为什么 MCP 里「没了」？
|
||
|
||
- **MCP / markitdown**：底层用 mammoth 等做结构转换，在 **表格嵌套、图文混排** 等版式下，经常出现 **整格图片被省略**，只保留右侧文字（与插件「看到的样子」不一致）。
|
||
- **Office Viewer（等插件）**：是编辑器 **按 Word 规则直接渲染**，不是把 docx 抽成纯 Markdown，所以版式与图片更完整。
|
||
|
||
**需要正文的图片一并给 AI 时**，优先用仓库脚本（导出 PNG + Markdown 相对路径）：
|
||
|
||
```powershell
|
||
pip install mammoth
|
||
python admin/scripts/docx_to_markdown_with_images.py ".temp\你的需求.docx" -o ".temp\你的需求.md" --media-dir "你的需求.media"
|
||
```
|
||
|
||
生成的 `.md` 中会包含 `` 等引用，同目录旁会有图片文件夹。再让 AI `Read` 该 `.md` 即可。
|
||
|
||
- **选型**：纯文本、简单结构可用 MCP `docx-to-markdown`；**强依赖版面截图**时用本脚本或 **Pandoc**（`--extract-media`）做对照。
|
||
|
||
## 调用方式
|
||
|
||
使用 Cursor MCP 工具调用界面或 `call_mcp_tool`：`server` 为配置中的键名（如 `req-doc-markdownify`），`toolName` 为上表名称，`arguments` 传 JSON（如 `{ "filepath": "D:\\\\docs\\\\需求.docx" }`）。
|