@noedgeai-org/doc2x-mcp 0.1.3-dev.2.2 → 0.1.3-dev.4.1

package/dist/config/index.d.ts

@@ -0,0 +1,15 @@
+export declare const RESOLVED_KEY: {
+    apiKey: string;
+    source: "inline" | "env" | "missing";
+};
+export declare const CONFIG: Readonly<{
+    baseUrl: string;
+    apiKey: string;
+    httpTimeoutMs: number;
+    pollIntervalMs: number;
+    maxWaitMs: number;
+    parsePdfMaxOutputChars: number;
+    parsePdfMaxOutputPages: number;
+}>;
+export declare function parseDownloadUrlAllowlist(): string[];
+export declare function isHostAllowedByAllowlist(hostname: string, allowlist: string[]): boolean;

package/dist/doc2x/client.d.ts

@@ -0,0 +1,15 @@
+import { type HttpMethod } from '#doc2x/http';
+export declare function normalizeUrl(u: string): string;
+export declare function isRetryableDoc2xBusinessCode(code: string): boolean;
+export declare function doc2xHeaders(extra?: Record<string, string>): {
+    Authorization: string;
+};
+type Doc2xRequestOpts = {
+    query?: Record<string, string>;
+    body?: unknown;
+    raw_body?: BodyInit;
+    headers?: Record<string, string>;
+};
+export declare function doc2xRequestJson<TData = Record<string, unknown>>(method: HttpMethod, pathname: string, opts?: Doc2xRequestOpts): Promise<TData>;
+export declare function putToSignedUrl(signedUrl: string, filePath: string): Promise<void>;
+export {};

package/dist/doc2x/client.js

@@ -1,25 +1,39 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import { CONFIG } from '#config';
-import { ToolError } from '#errors';
-import { TOOL_ERROR_CODE_INVALID_JSON, TOOL_ERROR_CODE_MISSING_API_KEY, httpErrorCode, putFailedCode, } from '#errorCodes';
+import { ToolError, coerceToolError, isRetryableError } from '#errors';
+import { TOOL_ERROR_CODE_INTERNAL_ERROR, TOOL_ERROR_CODE_INVALID_JSON, TOOL_ERROR_CODE_MISSING_API_KEY, httpErrorCode, putFailedCode, } from '#errorCodes';
 import { jitteredBackoffMs, sleep } from '#utils';
 import { DOC2X_API_CODE_SUCCESS } from '#doc2x/constants';
 import { HTTP_METHOD_PUT } from '#doc2x/http';
+function asJsonObject(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return null;
+    return v;
+}
 async function fetchJson(url, init, timeoutMs) {
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), timeoutMs);
     try {
-        const res = await fetch(url, { ...init, signal: ctrl.signal });
-        const text = await res.text();
-        let json;
         try {
-            json = text ? JSON.parse(text) : null;
+            const res = await fetch(url, { ...init, signal: ctrl.signal });
+            const text = await res.text();
+            let json;
+            try {
+                json = text ? asJsonObject(JSON.parse(text)) : null;
+            }
+            catch {
+                json = null;
+            }
+            return { res, text, json };
         }
-        catch {
-            json = null;
+        catch (e) {
+            throw coerceToolError(e, {
+                defaultCode: TOOL_ERROR_CODE_INTERNAL_ERROR,
+                defaultRetryable: true,
+                defaultMessage: 'Doc2x request failed',
+            });
         }
-        return { res, text, json };
     }
     finally {
         clearTimeout(t);
@@ -44,7 +58,7 @@ export function doc2xHeaders(extra) {
     if (!CONFIG.apiKey) {
         throw new ToolError({
             code: TOOL_ERROR_CODE_MISSING_API_KEY,
-            message: 'Doc2x API key is not configured (set INLINE_DOC2X_API_KEY in src/config.ts or provide DOC2X_API_KEY env).',
+            message: 'Doc2x API key is not configured (set INLINE_DOC2X_API_KEY in src/config/index.ts or provide DOC2X_API_KEY env).',
             retryable: false,
         });
     }
@@ -69,7 +83,19 @@ export async function doc2xRequestJson(method, pathname, opts) {
     }
     let attempt = 0;
     while (true) {
-        const { res, json, text } = await fetchJson(url.toString(), init, CONFIG.httpTimeoutMs);
+        let res;
+        let json;
+        let text;
+        try {
+            ({ res, json, text } = await fetchJson(url.toString(), init, CONFIG.httpTimeoutMs));
+        }
+        catch (e) {
+            if (isRetryableError(e)) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            throw e;
+        }
         if (res.status === 429) {
             await sleep(jitteredBackoffMs(attempt++));
             continue;
@@ -89,16 +115,18 @@ export async function doc2xRequestJson(method, pathname, opts) {
                 retryable: false,
             });
         }
-        if (json.code !== DOC2X_API_CODE_SUCCESS) {
-            const code = String(json.code || 'doc2x_error');
+        const envelope = json;
+        const apiCode = String(envelope.code || '');
+        if (apiCode !== DOC2X_API_CODE_SUCCESS) {
+            const code = String(envelope.code || 'doc2x_error');
             const retryable = isRetryableDoc2xBusinessCode(code);
             if (retryable) {
                 await sleep(jitteredBackoffMs(attempt++));
                 continue;
             }
-            throw new ToolError({ code, message: String(json.msg || 'Doc2x error'), retryable });
+            throw new ToolError({ code, message: String(envelope.msg || 'Doc2x error'), retryable });
         }
-        return json.data;
+        return envelope.data;
     }
 }
 export async function putToSignedUrl(signedUrl, filePath) {
@@ -107,16 +135,27 @@ export async function putToSignedUrl(signedUrl, filePath) {
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), CONFIG.httpTimeoutMs);
     try {
-        const res = await fetch(signedUrl, {
-            method: HTTP_METHOD_PUT,
-            body: body,
-            duplex: 'half',
-            headers: {
-                'Content-Type': 'application/pdf',
-                'Content-Length': String(stat.size),
-            },
-            signal: ctrl.signal,
-        });
+        let res;
+        try {
+            const putInit = {
+                method: HTTP_METHOD_PUT,
+                body: body,
+                duplex: 'half',
+                headers: {
+                    'Content-Type': 'application/pdf',
+                    'Content-Length': String(stat.size),
+                },
+                signal: ctrl.signal,
+            };
+            res = await fetch(signedUrl, putInit);
+        }
+        catch (e) {
+            throw coerceToolError(e, {
+                defaultCode: TOOL_ERROR_CODE_INTERNAL_ERROR,
+                defaultRetryable: true,
+                defaultMessage: 'PUT to signed url failed',
+            });
+        }
         if (!res.ok) {
             const txt = await res.text().catch(() => '');
             throw new ToolError({

package/dist/doc2x/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const DOC2X_API_CODE_SUCCESS: "success";
+export declare const DOC2X_TASK_STATUS_SUCCESS: "success";
+export declare const DOC2X_TASK_STATUS_FAILED: "failed";

package/dist/doc2x/convert.d.ts

@@ -0,0 +1,32 @@
+type ExportFilenameMode = 'auto' | 'raw';
+export declare const CONVERT_FORMULA_LEVELS: readonly [0, 1, 2];
+export type ConvertFormulaLevel = (typeof CONVERT_FORMULA_LEVELS)[number];
+export declare function convertExportSubmit(args: {
+    uid: string;
+    to: 'md' | 'tex' | 'docx';
+    formula_mode: 'normal' | 'dollar';
+    formula_level?: ConvertFormulaLevel;
+    filename?: string;
+    merge_cross_page_forms?: boolean;
+    filename_mode?: ExportFilenameMode;
+}): Promise<{
+    uid: string;
+    status: string;
+    url: string;
+}>;
+export declare function convertExportResult(uid: string): Promise<{
+    uid: string;
+    status: string;
+    url: string;
+}>;
+export declare function convertExportWaitByUid(args: {
+    uid: string;
+    to: 'md' | 'tex' | 'docx';
+    poll_interval_ms?: number;
+    max_wait_ms?: number;
+}): Promise<{
+    uid: string;
+    status: string;
+    url: string;
+}>;
+export {};

package/dist/doc2x/convert.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { CONFIG } from '#config';
-import { ToolError } from '#errors';
+import { ToolError, isRetryableError } from '#errors';
 import { TOOL_ERROR_CODE_CONVERT_FAILED, TOOL_ERROR_CODE_TIMEOUT } from '#errorCodes';
 import { jitteredBackoffMs, sleep } from '#utils';
 import { doc2xRequestJson, normalizeUrl } from '#doc2x/client';
@@ -72,7 +72,7 @@ export async function convertExportWaitByUid(args) {
             attempt = 0;
         }
         catch (e) {
-            if (e instanceof ToolError && e.retryable) {
+            if (isRetryableError(e)) {
                 await sleep(jitteredBackoffMs(attempt++));
                 continue;
             }

package/dist/doc2x/download.d.ts

@@ -0,0 +1,7 @@
+export declare function downloadUrlToFile(args: {
+    url: string;
+    output_path: string;
+}): Promise<{
+    output_path: string;
+    bytes_written: number;
+}>;

package/dist/doc2x/download.js

@@ -3,8 +3,8 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { Readable } from 'node:stream';
 import { CONFIG, isHostAllowedByAllowlist, parseDownloadUrlAllowlist } from '#config';
-import { ToolError } from '#errors';
-import { TOOL_ERROR_CODE_EMPTY_BODY, TOOL_ERROR_CODE_INVALID_URL, TOOL_ERROR_CODE_UNSAFE_URL, httpErrorCode, } from '#errorCodes';
+import { ToolError, coerceToolError } from '#errors';
+import { TOOL_ERROR_CODE_EMPTY_BODY, TOOL_ERROR_CODE_INTERNAL_ERROR, TOOL_ERROR_CODE_INVALID_URL, TOOL_ERROR_CODE_UNSAFE_URL, httpErrorCode, } from '#errorCodes';
 import { HTTP_METHOD_GET } from '#doc2x/http';
 import { normalizeUrl } from '#doc2x/client';
 export async function downloadUrlToFile(args) {
@@ -40,7 +40,18 @@ export async function downloadUrlToFile(args) {
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), CONFIG.httpTimeoutMs);
     try {
-        const res = await fetch(normalizedUrl, { method: HTTP_METHOD_GET, signal: ctrl.signal });
+        let res;
+        try {
+            res = await fetch(normalizedUrl, { method: HTTP_METHOD_GET, signal: ctrl.signal });
+        }
+        catch (e) {
+            throw coerceToolError(e, {
+                defaultCode: TOOL_ERROR_CODE_INTERNAL_ERROR,
+                defaultRetryable: true,
+                defaultMessage: 'download failed',
+                details: { url: parsed.hostname },
+            });
+        }
         if (!res.ok) {
             throw new ToolError({
                 code: httpErrorCode(res.status),
@@ -55,13 +66,23 @@ export async function downloadUrlToFile(args) {
                 retryable: true,
             });
         const file = fs.createWriteStream(outPath);
-        await new Promise((resolve, reject) => {
-            file.on('error', reject);
-            file.on('finish', resolve);
-            Readable.fromWeb(res.body)
-                .on('error', reject)
-                .pipe(file);
-        });
+        try {
+            await new Promise((resolve, reject) => {
+                file.on('error', reject);
+                file.on('finish', resolve);
+                Readable.fromWeb(res.body)
+                    .on('error', reject)
+                    .pipe(file);
+            });
+        }
+        catch (e) {
+            throw coerceToolError(e, {
+                defaultCode: TOOL_ERROR_CODE_INTERNAL_ERROR,
+                defaultRetryable: false,
+                defaultMessage: 'download failed while writing file',
+                details: { output_path: outPath },
+            });
+        }
         const stat = await fsp.stat(outPath);
         return { output_path: outPath, bytes_written: stat.size };
     }

package/dist/doc2x/http.d.ts

@@ -0,0 +1,4 @@
+export declare const HTTP_METHOD_GET: "GET";
+export declare const HTTP_METHOD_POST: "POST";
+export declare const HTTP_METHOD_PUT: "PUT";
+export type HttpMethod = typeof HTTP_METHOD_GET | typeof HTTP_METHOD_POST | typeof HTTP_METHOD_PUT;

package/dist/doc2x/image.d.ts

@@ -0,0 +1,23 @@
+export declare function parseImageLayoutSync(imagePath: string): Promise<{
+    uid: string;
+    result: unknown;
+    convert_zip: {} | null;
+}>;
+export declare function parseImageLayoutSubmit(imagePath: string): Promise<{
+    uid: string;
+}>;
+export declare function parseImageLayoutStatus(uid: string): Promise<{
+    uid: string;
+    status: string;
+    result: {} | null;
+    convert_zip: {} | null;
+}>;
+export declare function parseImageLayoutWaitTextByUid(args: {
+    uid: string;
+    poll_interval_ms?: number;
+    max_wait_ms?: number;
+}): Promise<{
+    uid: string;
+    status: "success";
+    text: string;
+}>;

package/dist/doc2x/image.js

@@ -1,7 +1,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { CONFIG } from '#config';
-import { ToolError } from '#errors';
+import { ToolError, isRetryableError } from '#errors';
 import { TOOL_ERROR_CODE_FILE_TOO_LARGE, TOOL_ERROR_CODE_INVALID_ARGUMENT, TOOL_ERROR_CODE_PARSE_FAILED, TOOL_ERROR_CODE_TIMEOUT, } from '#errorCodes';
 import { jitteredBackoffMs, sleep } from '#utils';
 import { doc2xRequestJson } from '#doc2x/client';
@@ -70,14 +70,15 @@ export async function parseImageLayoutWaitTextByUid(args) {
             attempt = 0;
         }
         catch (e) {
-            if (e instanceof ToolError && e.retryable) {
+            if (isRetryableError(e)) {
                 await sleep(jitteredBackoffMs(attempt++));
                 continue;
             }
             throw e;
         }
         if (st.status === DOC2X_TASK_STATUS_SUCCESS) {
-            const md = String(st?.result?.pages?.[0]?.md || '');
+            const result = st.result ?? null;
+            const md = String(result?.pages?.[0]?.md || '');
             return { uid, status: DOC2X_TASK_STATUS_SUCCESS, text: md };
         }
         if (st.status === DOC2X_TASK_STATUS_FAILED)

package/dist/doc2x/materialize.d.ts

@@ -0,0 +1,8 @@
+export declare function materializeConvertZip(args: {
+    convert_zip_base64: string;
+    output_dir: string;
+}): Promise<{
+    output_dir: string;
+    zip_path: string;
+    extracted: boolean;
+}>;

package/dist/doc2x/paths.d.ts

@@ -0,0 +1,2 @@
+export declare const DOC2X_API_V2_PREFIX = "/api/v2";
+export declare function v2(pathname: string): string;

package/dist/doc2x/pdf.d.ts

@@ -0,0 +1,29 @@
+export declare const PARSE_PDF_MODELS: readonly ["v3-2026"];
+export type ParsePdfModel = (typeof PARSE_PDF_MODELS)[number];
+export declare function parsePdfSubmit(pdfPath: string, opts?: {
+    model?: ParsePdfModel;
+}): Promise<{
+    uid: string;
+}>;
+export declare function parsePdfStatus(uid: string): Promise<{
+    uid: string;
+    status: string;
+    progress: number;
+    detail: string;
+    result: {} | null;
+}>;
+export declare function parsePdfWaitTextByUid(args: {
+    uid: string;
+    poll_interval_ms?: number;
+    max_wait_ms?: number;
+    join_with?: string;
+    max_output_chars?: number;
+    max_output_pages?: number;
+}): Promise<{
+    text: string;
+    truncated: boolean;
+    returnedPages: number;
+    totalPages: number;
+    uid: string;
+    status: "success";
+}>;

package/dist/doc2x/pdf.js

@@ -2,7 +2,7 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import _ from 'lodash';
 import { CONFIG } from '#config';
-import { ToolError } from '#errors';
+import { ToolError, isRetryableError } from '#errors';
 import { TOOL_ERROR_CODE_INVALID_ARGUMENT, TOOL_ERROR_CODE_PARSE_FAILED, TOOL_ERROR_CODE_TIMEOUT, } from '#errorCodes';
 import { jitteredBackoffMs, sleep } from '#utils';
 import { doc2xRequestJson, putToSignedUrl } from '#doc2x/client';
@@ -11,7 +11,9 @@ import { HTTP_METHOD_GET, HTTP_METHOD_POST } from '#doc2x/http';
 import { v2 } from '#doc2x/paths';
 export const PARSE_PDF_MODELS = ['v3-2026'];
 function mergePagesToTextWithLimit(result, joinWith, limits) {
-    const pages = _.sortBy(_.isArray(result?.pages) ? result.pages : [], (p) => Number(p?.page_idx ?? 0));
+    const parsed = result ?? null;
+    const sourcePages = _.isArray(parsed?.pages) ? parsed.pages : [];
+    const pages = _.sortBy(sourcePages, (p) => Number(p?.page_idx ?? 0));
     const maxPages = (limits?.maxOutputPages ?? 0) > 0 ? Number(limits?.maxOutputPages) : Number.POSITIVE_INFINITY;
     const maxChars = (limits?.maxOutputChars ?? 0) > 0 ? Number(limits?.maxOutputChars) : Number.POSITIVE_INFINITY;
     const parts = [];
@@ -66,7 +68,7 @@ async function preuploadPdfWithRetry(model) {
             return { uid: String(data.uid), url: String(data.url) };
         }
         catch (e) {
-            if (e instanceof ToolError && e.retryable) {
+            if (isRetryableError(e)) {
                 await sleep(jitteredBackoffMs(attempt++));
                 continue;
             }
@@ -88,7 +90,9 @@ export async function parsePdfSubmit(pdfPath, opts) {
     try {
         await putToSignedUrl(String(data.url), p);
     }
-    catch {
+    catch (e) {
+        if (!isRetryableError(e))
+            throw e;
         data = await preuploadPdfWithRetry(model);
         await putToSignedUrl(String(data.url), p);
     }
@@ -135,7 +139,7 @@ export async function parsePdfWaitTextByUid(args) {
             attempt = 0;
         }
         catch (e) {
-            if (e instanceof ToolError && e.retryable) {
+            if (isRetryableError(e)) {
                 await sleep(jitteredBackoffMs(attempt++));
                 continue;
             }

package/dist/errors/error.d.ts

@@ -0,0 +1,34 @@
+export type Retryable = boolean;
+type ToolErrorDetails = Record<string, unknown>;
+export declare class ToolError extends Error {
+    readonly code: string;
+    readonly retryable: Retryable;
+    readonly uid?: string;
+    readonly details?: ToolErrorDetails;
+    constructor(args: {
+        code: string;
+        message: string;
+        retryable: Retryable;
+        uid?: string;
+        details?: ToolErrorDetails;
+        cause?: unknown;
+    });
+    toPayload(): {
+        error: {
+            code: string;
+            message: string;
+            retryable: Retryable;
+            uid?: string;
+            details?: ToolErrorDetails;
+        };
+    };
+}
+export declare function isRetryableError(e: unknown): boolean;
+export declare function coerceToolError(e: unknown, opts?: {
+    defaultCode: string;
+    defaultRetryable: Retryable;
+    defaultMessage: string;
+    uid?: string;
+    details?: ToolErrorDetails;
+}): ToolError;
+export {};

package/dist/errors/error.js

@@ -0,0 +1,61 @@
+import { TOOL_ERROR_CODE_INTERNAL_ERROR, TOOL_ERROR_CODE_TIMEOUT } from '#errorCodes';
+export class ToolError extends Error {
+    code;
+    retryable;
+    uid;
+    details;
+    constructor(args) {
+        super(args.message, args.cause === undefined ? undefined : { cause: args.cause });
+        this.name = 'ToolError';
+        this.code = args.code;
+        this.retryable = args.retryable;
+        this.uid = args.uid;
+        this.details = args.details;
+    }
+    toPayload() {
+        const error = { code: this.code, message: this.message, retryable: this.retryable };
+        if (this.uid)
+            error.uid = this.uid;
+        if (this.details && Object.keys(this.details).length > 0)
+            error.details = this.details;
+        return {
+            error,
+        };
+    }
+}
+function stringMessageOf(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+function isAbortLikeError(e) {
+    const name = e instanceof Error ? e.name : '';
+    return name === 'AbortError' || name === 'TimeoutError';
+}
+export function isRetryableError(e) {
+    return e instanceof ToolError && e.retryable;
+}
+export function coerceToolError(e, opts) {
+    if (e instanceof ToolError)
+        return e;
+    if (isAbortLikeError(e)) {
+        return new ToolError({
+            code: TOOL_ERROR_CODE_TIMEOUT,
+            message: opts?.defaultMessage ? `${opts.defaultMessage}: request timeout` : 'request timeout',
+            retryable: true,
+            uid: opts?.uid,
+            details: opts?.details,
+            cause: e,
+        });
+    }
+    return new ToolError({
+        code: opts?.defaultCode ?? TOOL_ERROR_CODE_INTERNAL_ERROR,
+        message: opts?.defaultMessage
+            ? `${opts.defaultMessage}: ${stringMessageOf(e)}`
+            : stringMessageOf(e),
+        retryable: opts?.defaultRetryable ?? false,
+        uid: opts?.uid,
+        details: opts?.details,
+        cause: e,
+    });
+}

package/dist/errors/errorCodes.d.ts

@@ -0,0 +1,13 @@
+export declare const TOOL_ERROR_CODE_CONVERT_FAILED: "convert_failed";
+export declare const TOOL_ERROR_CODE_EMPTY_BODY: "empty_body";
+export declare const TOOL_ERROR_CODE_FILE_TOO_LARGE: "file_too_large";
+export declare const TOOL_ERROR_CODE_INTERNAL_ERROR: "internal_error";
+export declare const TOOL_ERROR_CODE_INVALID_ARGUMENT: "invalid_argument";
+export declare const TOOL_ERROR_CODE_INVALID_JSON: "invalid_json";
+export declare const TOOL_ERROR_CODE_INVALID_URL: "invalid_url";
+export declare const TOOL_ERROR_CODE_MISSING_API_KEY: "missing_api_key";
+export declare const TOOL_ERROR_CODE_PARSE_FAILED: "parse_failed";
+export declare const TOOL_ERROR_CODE_TIMEOUT: "timeout";
+export declare const TOOL_ERROR_CODE_UNSAFE_URL: "unsafe_url";
+export declare function httpErrorCode(status: number): string;
+export declare function putFailedCode(status: number): string;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -23,7 +23,12 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+function formatFatalError(e) {
+    if (e instanceof Error)
+        return e.stack || `${e.name}: ${e.message}`;
+    return String(e);
+}
 main().catch((e) => {
-    process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), err: String(e?.stack || e) }) + os.EOL);
+    process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), err: formatFatalError(e) }) + os.EOL);
     process.exitCode = 1;
 });

package/dist/mcp/registerConvertTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type RegisterToolsContext } from '#mcp/registerToolsShared';
+export declare function registerConvertTools(server: McpServer, ctx: RegisterToolsContext): void;

package/dist/mcp/registerConvertTools.js

@@ -0,0 +1,65 @@
+import { convertExportResult, convertExportSubmit, convertExportWaitByUid, } from '#doc2x/convert';
+import { asJsonResult } from '#mcp/results';
+import { convertFilenameModeSchema, convertFilenameSchema, convertFormulaLevelValueSchema, convertFormulaModeSchema, convertToSchema, makeConvertSubmitKey, optionalBooleanSchema, parsePdfUidSchema, positiveIntMsSchema, runConvertSubmitAtomically, withToolErrorHandling, } from '#mcp/registerToolsShared';
+export function registerConvertTools(server, ctx) {
+    const submitConvertWithDedup = async (args, opts) => {
+        const key = makeConvertSubmitKey(args);
+        return await runConvertSubmitAtomically(ctx, {
+            key,
+            skipIfSubmitted: opts?.skipIfSubmitted,
+            submit: () => convertExportSubmit(args),
+        });
+    };
+    server.registerTool('doc2x_convert_export_submit', {
+        description: 'Start an export (convert) job for a parsed PDF uid. After this, poll with doc2x_convert_export_wait or doc2x_convert_export_result. Do NOT call doc2x_convert_export_submit twice for the same uid+format in parallel.',
+        inputSchema: {
+            uid: parsePdfUidSchema,
+            to: convertToSchema,
+            formula_mode: convertFormulaModeSchema,
+            formula_level: convertFormulaLevelValueSchema
+                .optional()
+                .describe('Optional formula degradation level. Effective only when source parse uses model=v3-2026 (ignored by v2). 0: keep formulas, 1: degrade inline formulas, 2: degrade inline and block formulas.'),
+            filename: convertFilenameSchema
+                .describe("Optional output filename (for md/tex only). Tip: pass a basename WITHOUT extension to avoid getting 'name.md.md' / 'name.tex.tex'."),
+            filename_mode: convertFilenameModeSchema
+                .describe("How to treat filename. 'auto' strips common extensions for the target format; 'raw' passes basename as-is.")
+                .optional(),
+            merge_cross_page_forms: optionalBooleanSchema,
+        },
+    }, withToolErrorHandling(async (args) => asJsonResult(await submitConvertWithDedup(args))));
+    server.registerTool('doc2x_convert_export_result', {
+        description: 'Get the latest export (convert) result for a parsed PDF uid (may contain an escaped URL).',
+        inputSchema: {
+            uid: parsePdfUidSchema,
+        },
+    }, withToolErrorHandling(async ({ uid }) => asJsonResult(await convertExportResult(uid))));
+    server.registerTool('doc2x_convert_export_wait', {
+        description: 'Wait for an export job to finish. Prefer calling doc2x_convert_export_submit first, then wait with uid+to. For backward compatibility, if formula_mode is provided and this job was not submitted in-process, this tool will submit once then wait.',
+        inputSchema: {
+            uid: parsePdfUidSchema,
+            to: convertToSchema.describe('Expected target format. Used to verify the result URL.'),
+            formula_mode: convertFormulaModeSchema.optional(),
+            formula_level: convertFormulaLevelValueSchema
+                .optional()
+                .describe('Optional formula degradation level used when this tool auto-submits export (formula_mode must be provided). Effective only when source parse uses model=v3-2026 (ignored by v2).'),
+            filename: convertFilenameSchema,
+            filename_mode: convertFilenameModeSchema.optional(),
+            merge_cross_page_forms: optionalBooleanSchema,
+            poll_interval_ms: positiveIntMsSchema.optional(),
+            max_wait_ms: positiveIntMsSchema.optional(),
+        },
+    }, withToolErrorHandling(async (args) => {
+        if (args.formula_mode) {
+            await submitConvertWithDedup({
+                uid: args.uid,
+                to: args.to,
+                formula_mode: args.formula_mode,
+                formula_level: args.formula_level,
+                filename: args.filename,
+                filename_mode: args.filename_mode,
+                merge_cross_page_forms: args.merge_cross_page_forms,
+            }, { skipIfSubmitted: true });
+        }
+        return asJsonResult(await convertExportWaitByUid(args));
+    }));
+}

package/dist/mcp/registerImageTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type RegisterToolsContext } from '#mcp/registerToolsShared';
+export declare function registerImageTools(server: McpServer, ctx: RegisterToolsContext): void;