npm - @noedgeai-org/doc2x-mcp - Versions diffs - 0.1.3-dev.5.1 → 0.1.3 - Mend

@noedgeai-org/doc2x-mcp 0.1.3-dev.5.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +156 -57
package/README_EN.md +158 -59
package/dist/config/index.js +0 -1
package/package.json +1 -1
package/skills/doc2x-mcp/SKILL.md +10 -6

package/README.md CHANGED Viewed

@@ -1,29 +1,47 @@
 # Doc2x MCP Server
+[![CI](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/ci.yml)
+[![Publish](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/%40noedgeai-org%2Fdoc2x-mcp)](https://www.npmjs.com/package/@noedgeai-org/doc2x-mcp)
 简体中文 | [English](./README_EN.md)
-本项目提供一个基于 stdio 的 MCP Server，把 Doc2x v2 的 PDF/图片接口封装成语义化 tools。
+将 Doc2x v2 PDF/图片能力封装为基于 stdio 的 MCP Server，提供稳定、可组合的语义化 tools。
+## 目录
+- [项目定位](#项目定位)
+- [版本与环境](#版本与环境)
+- [快速开始](#快速开始)
+- [配置参考](#配置参考)
+- [Tool API 总览](#tool-api-总览)
+- [常见工作流](#常见工作流)
+- [本地开发](#本地开发)
+- [CI / 发布流水线](#ci--发布流水线)
+- [如何发布](#如何发布)
+- [安装本仓库 Skill（可选）](#安装本仓库-skill可选)
+- [安全与排错](#安全与排错)
+- [问题反馈](#问题反馈)
+- [License](#license)
-## 1) 运行环境
+## 项目定位
-- Node.js >= 18
+- 面向 MCP 客户端（Codex CLI / Claude Code / 自定义 Agent）提供 Doc2x 能力。
+- 以 submit/status/wait 统一异步任务模型，便于自动化编排。
+- 提供可控超时、轮询、下载白名单等运行时安全边界。
-## 2) 配置
+## 版本与环境
-通过环境变量配置：
+- 本地运行：Node.js `>=18` 即可。
+- CI 校验：Node.js `18`、`20` 都会跑构建。
+- 发布环境：GitHub Actions 中发布任务使用 Node.js `24`。
+- 包管理器：统一用 pnpm（锁文件 `pnpm-lock.yaml`）。
-- `DOC2X_API_KEY`：必填（形如 `sk-xxx`）
-- `DOC2X_BASE_URL`：可选，默认 `https://v2.doc2x.noedgeai.com`
-- `DOC2X_HTTP_TIMEOUT_MS`：可选，默认 `60000`
-- `DOC2X_POLL_INTERVAL_MS`：可选，默认 `2000`
-- `DOC2X_MAX_WAIT_MS`：可选，默认 `600000`
-- `DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS`：可选，默认 `5000`；限制 `doc2x_parse_pdf_wait_text` 返回文本的最大字符数，避免大模型上下文超限（设为 `0` 表示不限制）
-- `DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES`：可选，默认 `10`；限制 `doc2x_parse_pdf_wait_text` 合并的最大页数（设为 `0` 表示不限制）
-- `DOC2X_DOWNLOAD_URL_ALLOWLIST`：可选，默认 `".amazonaws.com.cn,.aliyuncs.com,.noedgeai.com"`；设为 `*` 可允许任意 host（不推荐）
+## 快速开始
-## 3) 启动
+### 方式 A：通过 npx（推荐）
-### 方式 A：通过 npx
+在 MCP client 配置中添加：
 ```json
 {
@@ -40,11 +58,13 @@
 ```bash
 cd doc2x-mcp
-npm install
-npm run build
-DOC2X_API_KEY=sk-xxx npm start
+pnpm install --frozen-lockfile
+pnpm run build
+DOC2X_API_KEY=sk-xxx pnpm start
 ```
+MCP client 指向本地构建产物：
 ```json
 {
   "command": "node",
@@ -56,27 +76,34 @@ DOC2X_API_KEY=sk-xxx npm start
 }
 ```
-## 4) Tools
-- `doc2x_parse_pdf_submit`
-- `doc2x_parse_pdf_status`
-- `doc2x_parse_pdf_wait_text`
-- `doc2x_convert_export_submit`
-- `doc2x_convert_export_result`
-- `doc2x_convert_export_wait`
-- `doc2x_download_url_to_file`
-- `doc2x_parse_image_layout_sync`
-- `doc2x_parse_image_layout_submit`
-- `doc2x_parse_image_layout_status`
-- `doc2x_parse_image_layout_wait_text`
-- `doc2x_materialize_convert_zip`
-- `doc2x_debug_config`
+## 配置参考
+| 环境变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `DOC2X_API_KEY` | 是 | - | Doc2x API Key（`sk-xxx`） |
+| `DOC2X_BASE_URL` | 否 | `https://v2.doc2x.noedgeai.com` | Doc2x API 基础地址 |
+| `DOC2X_HTTP_TIMEOUT_MS` | 否 | `60000` | 单次 HTTP 超时（毫秒） |
+| `DOC2X_POLL_INTERVAL_MS` | 否 | `2000` | 轮询间隔（毫秒） |
+| `DOC2X_MAX_WAIT_MS` | 否 | `600000` | wait 类工具最大等待时长（毫秒） |
+| `DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS` | 否 | `5000` | `doc2x_parse_pdf_wait_text` 最大返回字符数；`0`=不限制 |
+| `DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES` | 否 | `10` | `doc2x_parse_pdf_wait_text` 最大合并页数；`0`=不限制 |
+| `DOC2X_DOWNLOAD_URL_ALLOWLIST` | 否 | `.amazonaws.com.cn,.aliyuncs.com,.noedgeai.com` | 下载 URL 白名单；`*` 允许任意 host（不推荐） |
+## Tool API 总览
+| 阶段 | Tools | 说明 |
+| --- | --- | --- |
+| PDF 解析 | `doc2x_parse_pdf_submit` / `doc2x_parse_pdf_status` / `doc2x_parse_pdf_wait_text` | 提交任务、查询状态、等待并取文本 |
+| 结果导出 | `doc2x_convert_export_submit` / `doc2x_convert_export_result` / `doc2x_convert_export_wait` | 发起导出、查结果、等待导出完成 |
+| 下载落盘 | `doc2x_download_url_to_file` / `doc2x_materialize_convert_zip` | 下载 URL 到本地、解包 convert zip |
+| 图片版面解析 | `doc2x_parse_image_layout_sync` / `doc2x_parse_image_layout_submit` / `doc2x_parse_image_layout_status` / `doc2x_parse_image_layout_wait_text` | 同步/异步图片 OCR 与版面解析 |
+| 诊断 | `doc2x_debug_config` | 返回配置解析与 API key 来源，便于排错 |
 ### PDF 解析模型（`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_wait_text`）
 - 可选参数：`model`
-- 可选值：仅 `v3-2026`（最新模型）
-- 说明：不传 `model` 时默认使用 `v2`；若想体验最新模型，传：
+- 可选值：`v3-2026`（最新模型）
+- 不传时默认 `v2`
 ```json
 {
@@ -87,19 +114,84 @@ DOC2X_API_KEY=sk-xxx npm start
 ### 导出公式参数（`doc2x_convert_export_submit` / `doc2x_convert_export_wait`）
 - 必选参数：`formula_mode`（`normal` / `dollar`）
-- 可选参数：`formula_level`（`int32`，仅源解析任务为 `model=v3-2026` 时生效，`v2` 下无效）
+- 可选参数：`formula_level`（仅源解析任务为 `model=v3-2026` 时生效）
 - 取值说明：
-  - `0`：不退化公式（保留原始 Markdown）
-  - `1`：行内公式变为普通文本（退化 `\\(...\\)` 和 `$...$`）
-  - `2`：全部公式变为普通文本（退化 `\\(...\\)`、`$...$`、`\\[...\\]`、`$$...$$`）
+  - `0`：保留公式
+  - `1`：仅退化行内公式（`\\(...\\)`、`$...$`）
+  - `2`：退化全部公式（`\\(...\\)`、`$...$`、`\\[...\\]`、`$$...$$`）
-## 5) 协议
+## 常见工作流
-MIT License，详见 `LICENSE`。
+### 工作流 1：PDF -> Markdown 本地文件
+1. `doc2x_parse_pdf_submit` 提交 PDF 解析。
+2. `doc2x_convert_export_wait` 等待导出（`to=md`，并指定 `formula_mode`）。
+3. `doc2x_convert_export_result` 获取下载 URL。
+4. `doc2x_download_url_to_file` 下载到目标路径。
+### 工作流 2：图片版面 OCR 快速结果
+1. `doc2x_parse_image_layout_sync` 直接同步解析。
+2. 若需要稳态轮询，改用 submit/status/wait 组合。
+## 本地开发
+### 环境要求
+- Node.js `>=18`
+- pnpm（与仓库锁文件一致）
+### 常用命令
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+pnpm run test
+pnpm run format:check
+```
+运行服务：
+```bash
+DOC2X_API_KEY=sk-xxx pnpm start
+```
+## CI / 发布流水线
+仓库使用 GitHub Actions：
+- CI：`.github/workflows/ci.yml`
+  - 触发：`push` 到 `main`、`pull_request`、`workflow_dispatch`、每周一 UTC `03:17`
+  - 文档-only 变更（`**/*.md`、`LICENSE`）自动跳过
+  - 任务：
+    - `dependency-review`（仅 PR）
+    - `build`（Node.js `18/20` 矩阵）
+    - `package-smoke`（`npm pack --dry-run`）
+    - `security-audit`（仅手动/定时）
+- Publish：`.github/workflows/publish.yml`
+  - `dev` 分支 push：发布 npm `dev` tag
+  - `v*.*.*` tag push：发布 npm `latest`
+  - 发布前校验 tag 版本与 `package.json` 版本一致
+  - 发布命令：`npm publish --provenance`
+建议提交前本地对齐：
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+npm pack --dry-run
+pnpm audit --prod --audit-level high
+```
-## 6) 安装本仓库 Skill（可选）
+## 如何发布
-用于给 Codex CLI / Claude Code 增加一个“教大模型如何使用 doc2x-mcp tools 的 Skill”（便于按固定工作流调用 tools、导出与下载、以及排错）。
+- 开发预发布（`dev`）：push 到 `dev` 分支后自动发布到 npm `dev` tag。版本会自动改成 `x.y.z-dev.<run>.<attempt>`。
+- 正式发布（`latest`）：push `v*.*.*` tag 后发布到 npm `latest`。tag 版本必须和 `package.json` 版本一致。
+## 安装本仓库 Skill（可选）
+用于给 Codex CLI / Claude Code 增加一个“教大模型如何使用 doc2x-mcp tools 的 Skill”。
 不需要 clone 仓库的一键安装（推荐）：
@@ -107,28 +199,35 @@ MIT License，详见 `LICENSE`。
 curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh
 ```
-重复执行同一条命令即可覆盖安装（默认会覆盖已存在目录）。
 在本仓库源码目录安装：
 ```bash
-npm run skill:install
+pnpm run skill:install
 ```
-默认安装到：
+默认安装目录：
-脚本默认安装到：
-- Codex CLI：`~/.codex/skills/public/doc2x-mcp`（用 `CODEX_HOME` 覆盖）
-- Claude Code：`~/.claude/skills/doc2x-mcp`（用 `CLAUDE_HOME` 覆盖）
+- Codex CLI：`~/.codex/skills/public/doc2x-mcp`（可用 `CODEX_HOME` 覆盖）
+- Claude Code：`~/.claude/skills/doc2x-mcp`（可用 `CLAUDE_HOME` 覆盖）
 说明：
-- `--target auto`（默认）会同时安装到 Codex + Claude；如只想装其中一个，用 `--target codex|claude`。
-- PowerShell 7+ 一键安装：`irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
-- Windows PowerShell 5.1 一键安装：`irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex`
+- `--target auto`（默认）会同时安装到 Codex + Claude。
+- PowerShell 7+：`irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
+- Windows PowerShell 5.1：`irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex`
+## 安全与排错
-覆盖安装目录示例：
+- 不要在仓库提交真实 `DOC2X_API_KEY`。
+- 白名单默认限制下载域名；如需放开，评估风险后再使用 `DOC2X_DOWNLOAD_URL_ALLOWLIST=*`。
+- 配置异常时优先调用 `doc2x_debug_config` 定位环境变量来源与解析结果。
-- mac/linux：`CODEX_HOME=/custom/.codex curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh -s -- --target codex`
-- Windows：`$env:CODEX_HOME="C:\\path\\.codex"; irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
+## 问题反馈
+- 使用问题或缺陷反馈：GitHub Issues
+  [https://github.com/NoEdgeAI/doc2x-mcp/issues](https://github.com/NoEdgeAI/doc2x-mcp/issues)
+- 建议在 issue 中附上最小复现输入、触发的 tool 名称、以及 `doc2x_debug_config` 结果（可脱敏）。
+## License
+MIT License，详见 `LICENSE`。

package/README_EN.md CHANGED Viewed

@@ -1,34 +1,52 @@
 # Doc2x MCP Server
+[![CI](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/ci.yml)
+[![Publish](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/NoEdgeAI/doc2x-mcp/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/%40noedgeai-org%2Fdoc2x-mcp)](https://www.npmjs.com/package/@noedgeai-org/doc2x-mcp)
 English | [简体中文](./README.md)
-This project provides a stdio-based MCP Server that wraps Doc2x v2 PDF/image APIs into semantic tools.
+A stdio-based MCP Server that wraps Doc2x v2 PDF/image capabilities into stable, composable semantic tools.
+## Table of Contents
+- [Project Scope](#project-scope)
+- [Runtime Quick Facts](#runtime-quick-facts)
+- [Quick Start](#quick-start)
+- [Configuration Reference](#configuration-reference)
+- [Tool API Overview](#tool-api-overview)
+- [Common Workflows](#common-workflows)
+- [Local Development](#local-development)
+- [CI / Release Pipelines](#ci--release-pipelines)
+- [Publishing Flow](#publishing-flow)
+- [Install Repo Skill (Optional)](#install-repo-skill-optional)
+- [Security and Troubleshooting](#security-and-troubleshooting)
+- [Getting Help](#getting-help)
+- [License](#license)
-## 1) Requirements
+## Project Scope
-- Node.js >= 18
+- Exposes Doc2x capabilities to MCP clients (Codex CLI / Claude Code / custom agents).
+- Uses a unified async contract (`submit/status/wait`) for predictable automation.
+- Provides runtime safety boundaries (timeouts, polling controls, download allowlist).
-## 2) Configuration
+## Runtime Quick Facts
-Configure via environment variables:
+- Local run: Node.js `>=18` is enough.
+- CI checks: builds run on Node.js `18` and `20`.
+- Release environment: publish jobs run on Node.js `24` in GitHub Actions.
+- Package manager: pnpm with lockfile `pnpm-lock.yaml`.
-- `DOC2X_API_KEY`: required (e.g. `sk-xxx`)
-- `DOC2X_BASE_URL`: optional, default `https://v2.doc2x.noedgeai.com`
-- `DOC2X_HTTP_TIMEOUT_MS`: optional, default `60000`
-- `DOC2X_POLL_INTERVAL_MS`: optional, default `2000`
-- `DOC2X_MAX_WAIT_MS`: optional, default `600000`
-- `DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS`: optional, default `5000`; limit the returned text size of `doc2x_parse_pdf_wait_text` (set `0` for unlimited)
-- `DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES`: optional, default `10`; limit merged pages of `doc2x_parse_pdf_wait_text` (set `0` for unlimited)
-- `DOC2X_DOWNLOAD_URL_ALLOWLIST`: optional, default `".amazonaws.com.cn,.aliyuncs.com,.noedgeai.com"`; set to `*` to allow any host (not recommended)
+## Quick Start
-## 3) Run
+### Option A: via npx (recommended)
-### Option A: via npx
+Add this in your MCP client config:
 ```json
 {
   "command": "npx",
-  "args": ["-y", "@noedgeai-org/doc2x-mcp"],
+  "args": ["-y", "@noedgeai-org/doc2x-mcp@latest"],
   "env": {
     "DOC2X_API_KEY": "sk-xxx",
     "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
@@ -40,11 +58,13 @@ Configure via environment variables:
 ```bash
 cd doc2x-mcp
-npm install
-npm run build
-DOC2X_API_KEY=sk-xxx npm start
+pnpm install --frozen-lockfile
+pnpm run build
+DOC2X_API_KEY=sk-xxx pnpm start
 ```
+Point MCP client to your local build output:
 ```json
 {
   "command": "node",
@@ -56,27 +76,34 @@ DOC2X_API_KEY=sk-xxx npm start
 }
 ```
-## 4) Tools
-- `doc2x_parse_pdf_submit`
-- `doc2x_parse_pdf_status`
-- `doc2x_parse_pdf_wait_text`
-- `doc2x_convert_export_submit`
-- `doc2x_convert_export_result`
-- `doc2x_convert_export_wait`
-- `doc2x_download_url_to_file`
-- `doc2x_parse_image_layout_sync`
-- `doc2x_parse_image_layout_submit`
-- `doc2x_parse_image_layout_status`
-- `doc2x_parse_image_layout_wait_text`
-- `doc2x_materialize_convert_zip`
-- `doc2x_debug_config`
+## Configuration Reference
+| Environment Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `DOC2X_API_KEY` | Yes | - | Doc2x API key (`sk-xxx`) |
+| `DOC2X_BASE_URL` | No | `https://v2.doc2x.noedgeai.com` | Doc2x API base URL |
+| `DOC2X_HTTP_TIMEOUT_MS` | No | `60000` | Per-request HTTP timeout in ms |
+| `DOC2X_POLL_INTERVAL_MS` | No | `2000` | Polling interval in ms |
+| `DOC2X_MAX_WAIT_MS` | No | `600000` | Max wait duration for wait tools in ms |
+| `DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS` | No | `5000` | Max returned chars for `doc2x_parse_pdf_wait_text`; `0` = unlimited |
+| `DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES` | No | `10` | Max merged pages for `doc2x_parse_pdf_wait_text`; `0` = unlimited |
+| `DOC2X_DOWNLOAD_URL_ALLOWLIST` | No | `.amazonaws.com.cn,.aliyuncs.com,.noedgeai.com` | URL host allowlist for downloads; `*` allows any host (not recommended) |
+## Tool API Overview
+| Stage | Tools | Purpose |
+| --- | --- | --- |
+| PDF parse | `doc2x_parse_pdf_submit` / `doc2x_parse_pdf_status` / `doc2x_parse_pdf_wait_text` | Submit parse tasks, check status, wait and fetch text |
+| Export | `doc2x_convert_export_submit` / `doc2x_convert_export_result` / `doc2x_convert_export_wait` | Start export, read export result, wait for completion |
+| Download | `doc2x_download_url_to_file` / `doc2x_materialize_convert_zip` | Download export URL to local path, materialize convert zip |
+| Image layout parse | `doc2x_parse_image_layout_sync` / `doc2x_parse_image_layout_submit` / `doc2x_parse_image_layout_status` / `doc2x_parse_image_layout_wait_text` | Sync/async OCR and layout parse for images |
+| Diagnostics | `doc2x_debug_config` | Show resolved config and API key source |
 ### PDF Parse Model (`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_wait_text`)
 - Optional parameter: `model`
-- Supported values: only `v3-2026` (latest model)
-- Notes: omit `model` to use default `v2`; to try the latest model, pass:
+- Supported value: `v3-2026` (latest model)
+- Default (when omitted): `v2`
 ```json
 {
@@ -86,20 +113,85 @@ DOC2X_API_KEY=sk-xxx npm start
 ### Export Formula Parameters (`doc2x_convert_export_submit` / `doc2x_convert_export_wait`)
-- Required parameter: `formula_mode` (`normal` / `dollar`)
-- Optional parameter: `formula_level` (`int32`, effective only when the source parse task uses `model=v3-2026`; ignored by `v2`)
+- Required: `formula_mode` (`normal` / `dollar`)
+- Optional: `formula_level` (effective only when source parse used `model=v3-2026`)
 - Value mapping:
-  - `0`: keep formulas as-is (preserve original Markdown)
-  - `1`: degrade inline formulas to plain text (`\\(...\\)` and `$...$`)
-  - `2`: degrade all formulas to plain text (`\\(...\\)`, `$...$`, `\\[...\\]`, `$$...$$`)
+  - `0`: keep formulas
+  - `1`: degrade inline formulas (`\\(...\\)`, `$...$`)
+  - `2`: degrade all formulas (`\\(...\\)`, `$...$`, `\\[...\\]`, `$$...$$`)
-## 5) License
+## Common Workflows
-MIT License. See `LICENSE`.
+### Workflow 1: PDF -> Markdown local file
+1. Submit parse via `doc2x_parse_pdf_submit`.
+2. Wait export via `doc2x_convert_export_wait` (`to=md` and `formula_mode` required).
+3. Read result URL via `doc2x_convert_export_result`.
+4. Download to local path via `doc2x_download_url_to_file`.
+### Workflow 2: Fast image OCR/layout result
+1. Use `doc2x_parse_image_layout_sync` for direct parse.
+2. For robust polling behavior, switch to submit/status/wait flow.
+## Local Development
+### Requirements
+- Node.js `>=18`
+- pnpm (aligned with lockfile)
+### Common commands
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+pnpm run test
+pnpm run format:check
+```
+Run server:
+```bash
+DOC2X_API_KEY=sk-xxx pnpm start
+```
+## CI / Release Pipelines
+This repository uses GitHub Actions:
+- CI: `.github/workflows/ci.yml`
+  - Triggers: `push` to `main`, `pull_request`, `workflow_dispatch`, weekly on Monday at UTC `03:17`
+  - Doc-only changes (`**/*.md`, `LICENSE`) are skipped
+  - Jobs:
+    - `dependency-review` (PR only)
+    - `build` (Node.js `18/20` matrix)
+    - `package-smoke` (`npm pack --dry-run`)
+    - `security-audit` (manual/scheduled only)
+- Publish: `.github/workflows/publish.yml`
+  - Push to `dev`: publish npm package with `dev` tag
+  - Push tag `v*.*.*`: publish npm package as `latest`
+  - Verifies tag version matches `package.json` version before publish
+  - Publish command: `npm publish --provenance`
+Recommended local parity checks before pushing:
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+npm pack --dry-run
+pnpm audit --prod --audit-level high
+```
-## 6) Install Repo Skill (Optional)
+## Publishing Flow
-Installs a tool-use skill for Codex CLI / Claude Code (teaches the LLM how to use doc2x-mcp tools with a standard workflow: submit/status/wait/export/download).
+- Dev pre-release (`dev`): push to `dev` branch to publish npm `dev` tag. Version is auto rewritten to `x.y.z-dev.<run>.<attempt>`.
+- Production release (`latest`): push `v*.*.*` tag to publish npm `latest`. Tag version must match `package.json`.
+## Install Repo Skill (Optional)
+Installs a reusable skill for Codex CLI / Claude Code to guide tool usage with the standard `submit/status/wait/export/download` workflow.
 One-command install without cloning (recommended):
@@ -107,28 +199,35 @@ One-command install without cloning (recommended):
 curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh
 ```
-Re-run the same command to overwrite (default behavior overwrites an existing destination directory).
 Install from this repo source directory:
 ```bash
-npm run skill:install
+pnpm run skill:install
 ```
-Default destination:
+Default destinations:
-The script installs to:
-- Codex CLI: `~/.codex/skills/public/doc2x-mcp` (override via `CODEX_HOME`)
-- Claude Code: `~/.claude/skills/doc2x-mcp` (override via `CLAUDE_HOME`)
+- Codex CLI: `~/.codex/skills/public/doc2x-mcp` (override with `CODEX_HOME`)
+- Claude Code: `~/.claude/skills/doc2x-mcp` (override with `CLAUDE_HOME`)
 Notes:
-- `--target auto` (default) installs to both Codex + Claude; use `--target codex|claude` to install only one.
-- PowerShell 7+ one-command install: `irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
-- Windows PowerShell 5.1 one-command install: `irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex`
+- `--target auto` (default) installs to both Codex + Claude.
+- PowerShell 7+: `irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
+- Windows PowerShell 5.1: `irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex`
+## Security and Troubleshooting
-Override install dir examples:
+- Never commit real `DOC2X_API_KEY` to the repository.
+- The download allowlist is restrictive by default; evaluate risk before using `DOC2X_DOWNLOAD_URL_ALLOWLIST=*`.
+- Use `doc2x_debug_config` first when diagnosing config/environment issues.
-- mac/linux: `CODEX_HOME=/custom/.codex curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh -s -- --target codex`
-- Windows: `$env:CODEX_HOME="C:\\path\\.codex"; irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
+## Getting Help
+- Usage questions or bug reports: GitHub Issues
+  [https://github.com/NoEdgeAI/doc2x-mcp/issues](https://github.com/NoEdgeAI/doc2x-mcp/issues)
+- Include minimal reproduction input, affected tool name, and sanitized `doc2x_debug_config` output when possible.
+## License
+MIT License. See `LICENSE`.

package/dist/config/index.js CHANGED Viewed

@@ -3,7 +3,6 @@ function parseDoc2xApiKey(raw) {
     const v = String(raw).trim();
     if (!v)
         return '';
-    // Common misconfig: Alma/Codex passes literal "${DOC2X_API_KEY}" without expansion.
     if (v.includes('${') && v.includes('}'))
         return '';
     const bearerPrefix = /^bearer\s+/i;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@noedgeai-org/doc2x-mcp",
-  "version": "0.1.3-dev.5.1",
+  "version": "0.1.3",
   "description": "Doc2x MCP server (stdio, MCP SDK).",
   "license": "MIT",
   "engines": {

package/skills/doc2x-mcp/SKILL.md CHANGED Viewed

@@ -21,7 +21,8 @@ description: 使用 Doc2x MCP 工具完成文档解析与转换：对 PDF/扫描
    `doc2x_parse_pdf_submit.pdf_path` 必须以 `.pdf` 结尾；图片解析使用 `png/jpg`。
 3. 不要并发重复提交导出
-   同一个 `uid` 对同一种导出配置（`to + formula_mode + formula_level (+ filename + filename_mode + merge_cross_page_forms...)`）不要并行重复 submit。
+   同一个 `uid` 对同一种导出配置（`to + formula_mode + formula_level (+ filename + filename_mode + merge_cross_page_forms...)`）不要并行重复 submit。
+   补充：同一 `uid + to` 的导出结果可能会被后一次覆盖；做“多档对比”（如 `formula_level=0/1/2`）时，必须按 **导出成功 → 立即下载落盘 → 再导出下一档** 的顺序执行。
 4. 不要泄露密钥
    永远不要回显/记录 `DOC2X_API_KEY`。排错只用 `doc2x_debug_config` 的 `apiKeyLen/apiKeyPrefix/apiKeySource`。
@@ -38,7 +39,7 @@ description: 使用 Doc2x MCP 工具完成文档解析与转换：对 PDF/扫描
   - 可选 `model: "v3-2026"`；不传则默认 `v2`。
 - `doc2x_convert_export_submit` / `doc2x_convert_export_wait`
   - `formula_mode`：`"normal"` 或 `"dollar"`（关键参数，建议总是显式传入）。
-  - `formula_level`：`0 | 1 | 2`（可选）
+  - `formula_level`：`0 | 1 | 2`（可选，**数字类型**，不要传字符串 `"0"|"1"|"2"`）
     - `0`：不退化公式（保留原始 Markdown）
     - `1`：行内公式退化为普通文本（`\(...\)`、`$...$`）
     - `2`：行内 + 块级公式全部退化为普通文本（`\(...\)`、`$...$`、`\[...\]`、`$$...$$`）
@@ -91,6 +92,7 @@ description: 使用 Doc2x MCP 工具完成文档解析与转换：对 PDF/扫描
 - 需要做公式退化时显式传 `formula_level`（`0/1/2`）；若不需要退化，建议显式传 `0`，避免调用端默认值歧义
 - `filename`/`filename_mode` 主要用于 `md/tex`：传不带扩展名的 basename，并配合 `filename_mode: "auto"`（避免 `name.md.md` / `name.tex.tex`）
 - 对同一个 `uid` 做多格式导出时，先确定顺序（例如先 md 再 docx），逐个完成再进行下一个格式
+- 对同一个 `uid` 的同一格式做“多档参数对比”（如 `formula_level`），每一档都要先下载再进行下一档，避免覆盖导致误判
 **批量下载（并行）**
@@ -138,12 +140,14 @@ description: 使用 Doc2x MCP 工具完成文档解析与转换：对 PDF/扫描
 如果返回包含截断提示（`[doc2x-mcp] Output truncated ...`），应切换到“工作流 B”导出 md 获取完整内容。
-### 工作流 D：PDF → LaTeX / DOCX
+### 工作流 D：PDF 导出格式（MD / TEX / DOCX）
-- LaTeX：把 `to` 设为 `"tex"`
-- Word：把 `to` 设为 `"docx"`
-- 调用链同“工作流 A / B”（先解析 → 再导出 → 再下载），仅替换 `to`（以及必要时调整 `formula_mode/formula_level/filename`）
+- Markdown：`to="md"`（完整 Markdown 导出优先参考“工作流 B”）
+- LaTeX：`to="tex"`
+- Word：`to="docx"`
+- 调用链同“工作流 A / B”（先解析 → 再导出 → 再下载），按目标格式调整 `to`（并按需设置 `formula_mode/formula_level/filename`）
 - 注意：`doc2x_convert_export_submit.formula_mode` 必填（`"normal"` 或 `"dollar"`）；`formula_level` 可选（`0/1/2`）
+- 若需要对比不同 `formula_level`，请按顺序执行并在每次导出成功后立即下载，再进行下一档，避免后一次结果覆盖前一次。
 ### 工作流 E：图片 → Markdown（版面解析）