forked from EduCraft/curriculum-project-hub

Files

T

hongjr03 bb96159b3b 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.

2026-07-18 21:41:40 +08:00

2.2 KiB

Raw Blame History

name, description

name	description
pdf-to-md	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

Use feishu_read_context to find the file_key of the PDF attachment.
Use feishu_download_resource to download it into the workspace.
Use convert_pdf_to_md with the downloaded file path and an output directory.

PDF already in the workspace

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.

2.2 KiB Raw Blame History