@kolmopdf/mcp-server 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "kolmopdf",
+  "description": "Official KolmoPDF plugin marketplace for Claude Code.",
+  "owner": {
+    "name": "KomoAI LLC",
+    "email": "support@kolmopdf.com"
+  },
+  "plugins": [
+    {
+      "name": "kolmopdf",
+      "displayName": "KolmoPDF",
+      "source": "./plugins/kolmopdf",
+      "description": "High-fidelity PDF to Markdown parsing, layout-preserving PDF translation, and Markdown format conversion.",
+      "version": "1.0.0",
+      "author": { "name": "KomoAI LLC", "email": "support@kolmopdf.com" },
+      "homepage": "https://www.kolmopdf.com",
+      "repository": "https://github.com/kolmopdf/claude-plugin",
+      "license": "MIT",
+      "keywords": ["pdf", "markdown", "ocr", "translation", "latex", "research"],
+      "category": "document-processing",
+      "tags": ["pdf", "markdown", "translation", "academic", "arxiv"]
+    }
+  ]
+}

package/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,75 @@
+name: Bug report
+description: Report a problem with the KolmoPDF plugin or MCP server.
+title: "[bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please fill in the minimal diagnostic info below (TESTING_AND_USAGE.md §9).
+        Do NOT paste your API key. Use support@kolmopdf.com for secret-bearing reports.
+  - type: input
+    id: client-version
+    attributes:
+      label: Client version
+      description: "Claude Code: `claude --version` / Codex: `codex --version`"
+    validations:
+      required: true
+  - type: input
+    id: plugin-version
+    attributes:
+      label: Plugin version
+      description: "`/plugin list` or plugin.json version"
+    validations:
+      required: true
+  - type: input
+    id: mcp-version
+    attributes:
+      label: MCP server version
+      description: "`npx @kolmopdf/mcp-server --version`"
+    validations:
+      required: true
+  - type: input
+    id: node-version
+    attributes:
+      label: Node version
+      description: "`node --version`"
+    validations:
+      required: true
+  - type: input
+    id: task-id
+    attributes:
+      label: task_id
+      description: From the failing tool's return value (if any).
+    validations:
+      required: false
+  - type: textarea
+    id: error
+    attributes:
+      label: error_code + message
+      description: The MCP tool's returned error payload.
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: "`uname -a` or OS + version"
+    validations:
+      required: true
+  - type: dropdown
+    id: network
+    attributes:
+      label: Network location
+      description: Affects KolmoPDF upstream link quality.
+      options:
+        - Mainland China
+        - Outside mainland China
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true

package/.github/workflows/ci.yml

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  schedule:
+    - cron: "0 3 * * *" # nightly integration smoke
+  workflow_dispatch:
+  
+env:
+  PNPM_VERSION: 9.12.0
+  NODE_VERSION: 20
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm biome check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r typecheck
+
+  test-unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r test:unit
+
+  test-integration:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm --filter @kolmopdf/mcp-server test:integration
+        env:
+          KOLMOPDF_API_KEY: ${{ secrets.KOLMOPDF_API_KEY }}
+
+  validate-plugin:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      # Enable once the CLI exposes plugin validation in CI:
+      # - run: npx @anthropic-ai/claude-code plugin validate .
+      - name: Validate marketplace & plugin JSON
+        run: |
+          node -e "JSON.parse(require('fs').readFileSync('.claude-plugin/marketplace.json','utf8'))"
+          node -e "JSON.parse(require('fs').readFileSync('plugins/kolmopdf/.claude-plugin/plugin.json','utf8'))"
+          node -e "JSON.parse(require('fs').readFileSync('plugins/kolmopdf/.mcp.json','utf8'))"
+
+  mirror-codex-skill:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Ensure Codex skill mirror is byte-identical
+        run: |
+          diff plugins/kolmopdf/skills/kolmopdf/SKILL.md codex-skill/kolmopdf/SKILL.md
+          diff plugins/kolmopdf/skills/kolmopdf/references/parameter-glossary.md codex-skill/kolmopdf/references/parameter-glossary.md
+          diff plugins/kolmopdf/skills/kolmopdf/references/chain-recipes.md codex-skill/kolmopdf/references/chain-recipes.md

package/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.12.0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          registry-url: "https://registry.npmjs.org"
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Sanity check — versions match the tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          MCP=$(node -p "require('./packages/mcp-server/package.json').version")
+          PLUGIN=$(node -p "require('./plugins/kolmopdf/.claude-plugin/plugin.json').version")
+          MARKET=$(node -p "require('./.claude-plugin/marketplace.json').plugins[0].version")
+          echo "tag=$TAG mcp=$MCP plugin=$PLUGIN marketplace=$MARKET"
+          test "$TAG" = "$MCP" && test "$TAG" = "$PLUGIN" && test "$TAG" = "$MARKET" \
+            || (echo "::error::version mismatch between tag and manifests" && exit 1)
+
+      - run: pnpm -r build
+
+      - name: Publish @kolmopdf/mcp-server
+        working-directory: packages/mcp-server
+        run: pnpm publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial monorepo scaffold: `@kolmopdf/mcp-server` package, Claude Code plugin,
+  KolmoPDF skill, marketplace entry, Codex CLI skill mirror, CI/CD workflows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KomoAI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# KolmoPDF for Claude Code
+
+[![npm version](https://img.shields.io/npm/v/@kolmopdf/mcp-server)](https://www.npmjs.com/package/@kolmopdf/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+High-fidelity PDF→Markdown parsing, layout-preserving PDF translation, and Markdown→DOCX/HTML/PDF/LaTeX conversion — delivered as a Claude Code plugin, a Codex CLI / Cursor skill, and a standalone MCP server.
+
+## Install (Claude Code)
+
+```
+/plugin marketplace add kolmopdf/claude-plugin
+/plugin install kolmopdf@kolmopdf
+```
+
+Then set `KOLMOPDF_API_KEY` in your environment and restart Claude Code.
+
+```bash
+export KOLMOPDF_API_KEY=sk-xxxxxxxxxxxxxxxx
+```
+
+Other clients (Codex CLI, Cursor, Claude Desktop): see [`doc/plan/TESTING_AND_USAGE.md`](doc/plan/TESTING_AND_USAGE.md) §2.
+
+## Tools
+
+| Tool | Capability |
+| --- | --- |
+| `kolmopdf_parse_pdf` | PDF → Markdown (optional translation) |
+| `kolmopdf_translate_pdf` | Layout-preserving PDF translation |
+| `kolmopdf_convert_markdown` | Markdown → DOCX / HTML / PDF / LaTeX |
+| `kolmopdf_estimate_cost` | Pre-flight credit estimate |
+| `kolmopdf_check_balance` | Current credit balance |
+
+## Requirements
+
+- Node.js ≥ 20
+- KolmoPDF Plus or Pro account ([sign up](https://www.kolmopdf.com))
+- API key from [API Management](https://www.kolmopdf.com/api-keys)
+
+## Repository layout
+
+| Path | Contents |
+| --- | --- |
+| `packages/mcp-server` | `@kolmopdf/mcp-server` (MCP server) |
+| `plugins/kolmopdf` | Claude Code plugin (skill, commands, manifest) |
+| `.claude-plugin/marketplace.json` | Marketplace entry |
+| `codex-skill/kolmopdf` | Codex CLI / Cursor skill mirror |
+| `doc/` | API guides and project plans |
+
+## Development
+
+```bash
+corepack enable pnpm
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test:unit
+pnpm build
+```
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignore": ["dist", "node_modules", "coverage", "kolmopdf-output"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  }
+}

package/codex-skill/kolmopdf/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: kolmopdf
+description: Use this skill ONLY when the user gives an explicit operational instruction to process a PDF or Markdown file. Specifically: (1) explicitly asks to parse/convert a PDF into Markdown, (2) explicitly asks for layout-preserving PDF translation to produce a new translated PDF, (3) explicitly asks to export/convert Markdown to DOCX/HTML/PDF/LaTeX, or (4) a combination of the above (e.g. "parse this PDF to Markdown, then translate it, then export to DOCX"). Do NOT trigger for general PDF reading, summarization, or Q&A unless the user explicitly requests Markdown extraction first. Triggers: "parse PDF to markdown", "convert PDF to markdown", "translate this PDF preserving layout", "export markdown to docx/html/pdf/latex", "PDF to markdown with tables as images", "parse and translate this PDF".
+allowed-tools: mcp__kolmopdf__kolmopdf_parse_pdf, mcp__kolmopdf__kolmopdf_translate_pdf, mcp__kolmopdf__kolmopdf_convert_markdown, mcp__kolmopdf__kolmopdf_estimate_cost, mcp__kolmopdf__kolmopdf_check_balance, Read, Write
+---
+
+# KolmoPDF Skill
+
+You have access to KolmoPDF tools (prefix `kolmopdf_*`) for high-fidelity PDF parsing and translation. These tools call a paid cloud service. Always follow the rules below.
+
+## When to use
+
+This skill triggers ONLY on explicit user instructions to perform a file operation:
+
+- User explicitly asks to parse/convert a PDF into Markdown → `kolmopdf_parse_pdf`.
+- User explicitly asks for layout-preserving PDF translation → `kolmopdf_translate_pdf`.
+- User explicitly asks to export Markdown to DOCX/HTML/PDF/LaTeX → `kolmopdf_convert_markdown`.
+- User requests a combination (e.g. "parse this PDF, translate it, then export to DOCX") → chain the tools in sequence.
+
+Do NOT trigger when:
+- User just wants to read or summarize a PDF without requesting Markdown output.
+- User asks general questions about a PDF's content (use built-in Read instead).
+- User mentions PDF in passing without an explicit processing instruction.
+
+## Natural language parameter mapping
+
+Users may describe parameters in natural language. Map their descriptions to tool parameters:
+
+| User says | Parameter |
+| --- | --- |
+| "tables as images" / "keep table layout" | `table_mode="image"` |
+| "use dollar signs for formulas" / "KaTeX format" | `formula_format="dollar"` |
+| "use bracket notation" / "LaTeX-style delimiters" | `formula_format="bracket"` |
+| "translate to Chinese/Japanese/..." | `enable_translation=true`, `target_language="zh"/"ja"/...` |
+| "bilingual output" / "show both languages" | `output_options=["bilingual"]` |
+| "images as URLs" / "don't download images" | `images_as_url=true` |
+| "merge tables across pages" / "cross-page tables" | `enable_cross_page_merge=true` |
+| "side by side translation" | `layout_modes=["side_by_side"]` |
+| "translate images too" | `enable_image_translation=true` |
+| "translate tables too" | `enable_table_translation=true` |
+| "export to Word/DOCX/HTML/PDF/LaTeX" | `target_format` accordingly |
+
+When the user's natural language is ambiguous, use sensible defaults from `references/parameter-glossary.md`. When the user specifies multiple preferences in one request, combine all applicable parameters in a single tool call.
+
+## Cost-awareness protocol
+
+Before running any operation that consumes credits:
+
+1. Call `kolmopdf_estimate_cost` with the file path and intended operation.
+2. If `sufficient` is false: stop and report `shortfall` and the top-up URL `https://www.kolmopdf.com/subscription` to the user. Do not proceed.
+3. If `estimated_credits > 50`: tell the user the estimated cost and ask for confirmation before proceeding.
+4. Otherwise: proceed.
+
+## API key requirement
+
+Tools require `KOLMOPDF_API_KEY` in the MCP server environment. If a tool returns `invalid_api_key`:
+
+- Direct the user to https://www.kolmopdf.com/api-keys to create a key (requires Plus or Pro plan).
+- Tell the user to set `KOLMOPDF_API_KEY` in their environment and restart Claude Code.
+- Do not proceed with retries until the user confirms.
+
+## Chained workflows
+
+### PDF → DOCX/HTML/PDF/LaTeX (full pipeline)
+
+1. `kolmopdf_estimate_cost(file, "parse")` → check balance.
+2. `kolmopdf_parse_pdf(file)` → get `markdown_path`.
+3. `kolmopdf_convert_markdown(markdown_path, target_format)` → final file.
+
+If the PDF contains many images, pass the original directory (not just the markdown file) by zipping `output_root` first using your own tools, then pass the zip to convert. See `references/chain-recipes.md`.
+
+### Read + ask Q&A about a paper
+
+1. `kolmopdf_parse_pdf(file)` → get `markdown_path` and `preview`.
+2. Use `Read` on `markdown_path` to load the full content.
+3. Answer the user's question grounded in the markdown.
+
+### Translate then convert to bilingual deliverable
+
+Option A (PDF deliverable):
+- `kolmopdf_translate_pdf(file, layout_modes=["side_by_side"])` → single PDF with side-by-side layout.
+
+Option B (editable Markdown deliverable):
+- `kolmopdf_parse_pdf(file, enable_translation=true, output_options=["bilingual"])` → bilingual markdown.
+
+## Parameter guidance
+
+See `references/parameter-glossary.md` for the full parameter table and defaults. Highlights:
+
+- `formula_format=dollar` is the default and works with KaTeX/MathJax. Use `bracket` for LaTeX-strict downstream renderers.
+- `enable_cross_page_merge=true` is recommended when the source PDF has tables spanning page breaks.
+- `images_as_url=true` returns a single markdown file with 30-day URL references; use this for ephemeral pipelines. Default `false` returns a self-contained ZIP.
+
+## Output handling
+
+After successful tool calls, treat `output.markdown_path` / `output.translated_pdf_path` / `output.output_path` as the canonical local file paths and reference them in your reply to the user. Show the user the absolute path; do not re-print the entire file unless asked.
+
+## Failure modes
+
+| error_code | Action |
+| --- | --- |
+| `invalid_api_key` | Stop; follow API key requirement section above. |
+| `insufficient_points` | Stop; report shortfall and top-up URL. |
+| `parse_page_limit_exceeded`, `parse_file_too_large` | Stop; suggest splitting the PDF locally. |
+| `parse_file_not_pdf`, `parse_file_invalid` | Stop; ask the user to re-export the PDF. |
+| `parse_error`, `parse_timeout` | Server auto-refunds points. Suggest retry with smaller page range. |
+| `client_polling_timeout` | Tell the user the task is still running server-side and suggest using `kolmopdf_get_task_status` with the task_id later. |
+| Network/5xx | Tools auto-retry up to 3 times. If still failing, suggest checking https://www.kolmopdf.com/contact. |

package/codex-skill/kolmopdf/references/chain-recipes.md

@@ -0,0 +1,35 @@
+# KolmoPDF Chain Recipes
+
+Expanded, step-by-step playbooks for the chained workflows summarized in `SKILL.md`.
+
+## Recipe 1 — PDF → DOCX/HTML/PDF/LaTeX (full pipeline)
+
+1. `kolmopdf_estimate_cost({ file_path, operation: "parse" })`.
+   - If `sufficient=false` → stop; report `shortfall` + https://www.kolmopdf.com/subscription.
+   - If `estimated_credits > 50` → ask the user to confirm.
+2. `kolmopdf_parse_pdf({ file_path })` → capture `output.markdown_path` and `output.output_root`.
+3. Decide the convert input:
+   - **Markdown has no local images** (or `images_as_url=true` was used): pass `output.markdown_path` directly.
+   - **Markdown references local images**: zip `output.output_root` with your own tools (`Write`/shell), then pass the `.zip` path so figures survive conversion.
+4. `kolmopdf_convert_markdown({ file_path: <md-or-zip>, target_format })`.
+5. Report `output.output_path` to the user (absolute path).
+
+Total cost ≈ `pages × 2 + 1`.
+
+## Recipe 2 — Read + Q&A about a paper
+
+1. `kolmopdf_parse_pdf({ file_path })` → `output.markdown_path`, `preview`.
+2. `Read` the `markdown_path` to load full content into context.
+3. Answer the user's question grounded strictly in the parsed markdown. Cite section headings where useful.
+
+## Recipe 3 — Translate then deliver bilingual
+
+**Option A — PDF deliverable (layout preserved):**
+1. `kolmopdf_estimate_cost({ file_path, operation: "translate" })`.
+2. `kolmopdf_translate_pdf({ file_path, source_language, target_language, layout_modes: ["side_by_side"] })`.
+3. Report `output.translated_pdf_path`.
+
+**Option B — editable Markdown deliverable:**
+1. `kolmopdf_estimate_cost({ file_path, operation: "parse_translate" })`.
+2. `kolmopdf_parse_pdf({ file_path, enable_translation: true, target_language, output_options: ["bilingual"] })`.
+3. Report `output.markdown_path`. Optionally chain Recipe 1 step 4 to produce a bilingual DOCX.

package/codex-skill/kolmopdf/references/parameter-glossary.md

@@ -0,0 +1,72 @@
+# KolmoPDF Parameter Glossary
+
+Full parameter reference for the KolmoPDF tools. This file is not auto-loaded; the skill reads it on demand.
+
+## `kolmopdf_parse_pdf`
+
+| Parameter | Type | Legal values | Default | Billing impact |
+| --- | --- | --- | --- | --- |
+| `file_path` | string | local path to a `.pdf` | — | — |
+| `table_mode` | enum | `markdown`, `image` | `markdown` | none |
+| `formula_format` | enum | `dollar`, `bracket` | `dollar` | none |
+| `enable_translation` | boolean | `true`, `false` | `false` | `true` → 3 pts/page instead of 2 |
+| `target_language` | enum | `zh`, `en`, `ja`, `ko`, `fr`, `de`, `es`, `ru` | `zh` | only when `enable_translation=true` |
+| `output_options` | string[] | `original`, `translated`, `bilingual` | `original` | none |
+| `images_as_url` | boolean | `true`, `false` | `false` | none (`true` → single `.md` w/ 30-day URLs; `false` → ZIP) |
+| `skip_rotation_detection` | boolean | `true`, `false` | `false` | none |
+| `enable_cross_page_merge` | boolean | `true`, `false` | `false` | none (merges tables across ≤ 3 pages) |
+| `output_subdir` | string | any dir name | `<task_id>` | none |
+
+Cost: parse only = `pages × 2`; parse + translate = `pages × 3`.
+
+## `kolmopdf_translate_pdf`
+
+| Parameter | Type | Legal values | Default |
+| --- | --- | --- | --- |
+| `file_path` | string | local path to a `.pdf` | — |
+| `source_language` | string | language code | `en` |
+| `target_language` | string | language code | `zh` |
+| `layout_modes` | string[] | `translated_only`, `side_by_side` | `["translated_only"]` |
+| `enable_image_translation` | boolean | `true`, `false` | `false` |
+| `enable_table_translation` | boolean | `true`, `false` | `false` |
+| `output_subdir` | string | any dir name | `<task_id>` |
+
+Cost: `pages × 2`.
+
+## `kolmopdf_convert_markdown`
+
+| Parameter | Type | Legal values | Default |
+| --- | --- | --- | --- |
+| `file_path` | string | `.md`, `.markdown`, or `.zip` | — |
+| `target_format` | enum | `word`, `docx`, `html`, `pdf`, `latex`, `tex` | `word` |
+| `output_subdir` | string | any dir name | `<task_id>` |
+
+Extension mapping: `word|docx → .docx`, `html → .html`, `pdf → .pdf`, `latex|tex → .tex`.
+
+Cost: 1 credit/task.
+
+## Language codes
+
+| Code | Language |
+| --- | --- |
+| `zh` | Chinese |
+| `en` | English |
+| `ja` | Japanese |
+| `ko` | Korean |
+| `fr` | French |
+| `de` | German |
+| `es` | Spanish |
+| `ru` | Russian |
+
+## ZIP output structure (`images_as_url=false`)
+
+```
+<KOLMOPDF_OUTPUT_DIR>/<task_id>/
+├── <document>.md          # canonical markdown_path (first *.md found)
+├── images/                # extracted figures → images_dir
+│   ├── img-0001.png
+│   └── ...
+└── (other assets, flattened)
+```
+
+When `images_as_url=true`, the result is a single `result.md` with public image URLs (cached 30 days) and `images_dir = null`.