feat(hub): expose pdf_to_md_bundle as MCP tool to agent (ADR-0027)

The Agent was falling back to Read+Write to manually parse PDFs because it
had no way to invoke the capability adapter. This adds a convert_pdf_to_md
MCP tool to the cph_hub server so the Agent can call it like send_file.

Changes:
- roleTools.ts: register convert_pdf_to_md as a CPH_HUB_MCP tool id
- fileDeliveryTool.ts: add convert_pdf_to_md tool that creates the
  PdfToMdBundleAdapter (with AliyunDocmindClient + org credential resolution)
  and invokes it with workspace-confined paths. Returns generated file paths
  + page count + cost. MCP instructions tell the Agent to always use this
  tool instead of Read/Bash for PDF parsing.
- trigger.ts: pass secretEnvelope + prisma + organizationId to the MCP
  server so it can resolve capability credentials
- hub.ts: pass secretEnvelope to makeTriggerHandler
- skills/pdf-to-md/SKILL.md: thin skill describing the workflow
  (download from Feishu → convert_pdf_to_md → send_file), when to use, and
  the fallback message if no capability connection is configured

The Agent now sees mcp__cph_hub__convert_pdf_to_md and the MCP instructions
explicitly say: 'Do NOT attempt to parse PDFs yourself with Read or Bash —
always use convert_pdf_to_md.'

Version bump 0.0.32 → 0.0.33.
This commit is contained in:
2026-07-18 21:41:40 +08:00
parent ef96f8d33d
commit bb96159b3b
6 changed files with 133 additions and 2 deletions
+63
View File
@@ -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.