feat(hub): expose pdf_to_md_bundle as MCP tool to agent + skill (ADR-0027) (#9)

Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>
2026-07-18 21:43:00 +08:00
parent ef96f8d33d
commit ce18740870
6 changed files with 133 additions and 2 deletions
@@ -0,0 +1,63 @@
+---
+name: pdf-to-md
+description: >
+  Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool.
+  Handles PDFs from Feishu messages, local workspace files, and produces
+  high-quality Markdown with LaTeX formulas and extracted images.
+---
+
+# PDF to Markdown Conversion
+
+## When to use
+
+Use this skill when the user asks to convert a PDF to Markdown, extract text
+from a PDF, or turn a PDF document into an editable format.
+
+## How it works
+
+The `convert_pdf_to_md` tool (provided by the `cph_hub` MCP server) calls
+Alibaba Cloud Document Mind to parse the PDF. It:
+
+- Extracts text in reading order (handles multi-column, scanned, and
+  multi-language documents)
+- Converts mathematical formulas to **LaTeX** (`$...$` inline, `$$...$$` block)
+- Extracts tables as Markdown tables
+- Downloads embedded images into the output directory
+- Writes a single `document.md` file plus image files
+
+## Workflow
+
+### PDF from a Feishu message
+
+1. Use `feishu_read_context` to find the `file_key` of the PDF attachment.
+2. Use `feishu_download_resource` to download it into the workspace.
+3. Use `convert_pdf_to_md` with the downloaded file path and an output directory.
+
+### PDF already in the workspace
+
+1. Use `convert_pdf_to_md` directly with the file path and an output directory.
+
+## Important rules
+
+- **Always** use `convert_pdf_to_md` for PDF→Markdown. Do NOT attempt to parse
+  PDFs yourself with Read, Bash, Python, or any other method. The tool provides
+  accurate formula, table, and image extraction that manual methods cannot
+  match.
+- If `convert_pdf_to_md` fails because no capability connection is configured,
+  tell the user to ask their organization admin to configure the Aliyun
+  docmind credential in the admin web UI (组织后台 → 能力).
+- The output directory will be created if it does not exist.
+- After conversion, use `send_file` to send the generated markdown back to the
+  user if they requested it.
+
+## Output
+
+The tool returns a list of generated files:
+- `document.md` — the main markdown file
+- `*.jpg` / `*.png` — extracted images, referenced from the markdown
+
+## Cost
+
+The conversion is billed per page (0.04 CNY/page ≈ $0.0056/page for the
+enhanced formula mode). The cost is automatically recorded on the run's
+usage ledger.