markitai

Convert many local files and/or URLs in the background; returns a job id at once. Items run concurrently and each writes under output_dir/batch-<job_id>/<item number>/ (0001, 0002, ...), so sources with the same name cannot overwrite each other. Poll job_status with the returned job_id for progress and the per-item results. All items share one LLM runtime, so llm.concurrency bounds the job's model requests as a whole. Jobs live in this server process only: a restart forgets them, but the written files remain. Args: sources: A nonempty list (at most 10,000) of absolute local file paths and/or http(s) URLs. A relative path is rejected before the job starts; a missing file or a failed conversion fails only its item, and the others continue. output_dir: Absolute parent directory for all outputs (created if missing). Omit, null or "" for a new markitai-mcp-* temporary directory; its path is returned. llm: LLM enhancement (clean-up and front matter). Omit or null to follow the server's configuration (llm.enabled, off by default); false forces it off; true enables it for this call, which may incur provider charges. It needs a model: MODEL (with its provider's API key) in the server's env block, a signed-in subscription runtime, or llm.model_list in the configuration; without one the call fails with setup guidance. ocr: Local OCR for scanned PDF pages and images (macOS Vision, or the portable PaddleOCR models `markitai doctor --fix` installs). Omit to follow the configuration. screenshot: Page screenshots (PDF pages; Office documents through LibreOffice when it is installed; web pages through the isolated Chromium). Omit to follow the configuration. alt: LLM alt text for pictures (needs llm enabled). desc: LLM picture descriptions (needs llm enabled). profile: Shape the output for a consumer: "rag", "obsidian" or "okf". Omit or null to follow the configuration. Omitted or null flags follow the server's configuration, reloaded for every cal…

Convert one local document to Markdown. Handles PDF, Word, PowerPoint and Excel (and their legacy and OpenDocument formats), EPUB, HTML, CSV/JSON, e-mail, notebooks, plain text and Markdown, and images, among others. Returns the Markdown plus the paths of everything written to disk. Args: path: Absolute path to one local file (~ is expanded). Directories are rejected (a .numbers package is one document); pass files individually or use batch_convert. output_dir: Absolute directory to write the outputs into (created if missing). Omit, null or "" for a new markitai-mcp-* temporary directory, which stays on disk; its path is returned. llm: LLM enhancement (clean-up and front matter). Omit or null to follow the server's configuration (llm.enabled, off by default); false forces it off; true enables it for this call, which may incur provider charges. It needs a model: MODEL (with its provider's API key) in the server's env block, a signed-in subscription runtime, or llm.model_list in the configuration; without one the call fails with setup guidance. ocr: Local OCR for scanned PDF pages and images (macOS Vision, or the portable PaddleOCR models `markitai doctor --fix` installs). Omit to follow the configuration. screenshot: Page screenshots (PDF pages; Office documents through LibreOffice when it is installed; web pages through the isolated Chromium). Omit to follow the configuration. alt: LLM alt text for pictures (needs llm enabled). desc: LLM picture descriptions (needs llm enabled). profile: Shape the output for a consumer: "rag", "obsidian" or "okf". Omit or null to follow the configuration. Omitted or null flags follow the server's configuration, reloaded for every call; a feature this build or machine cannot provide fails explicitly instead of being skipped. Returns: source; markdown: the enhanced Markdown when there is one, else the base Markdown, or a 2,000-character preview with truncated=true when it exceeds 40,000 characte…

Fetch a web page and convert it to clean Markdown. Uses markitai's fetch strategy (fetch.strategy, auto by default: a static HTTP fetch with main-content extraction, then the local Chromium, when installed, for pages that need JavaScript) and returns the main content as Markdown. A PDF or another document the URL serves is converted like a local file. A remote reader service (Jina, Defuddle, Cloudflare) is used only when the configuration selects one; auto never falls back to one here. Args: url: The http:// or https:// URL to fetch and convert. output_dir: Absolute directory to write the outputs into (created if missing). Omit, null or "" for a new markitai-mcp-* temporary directory, which stays on disk; its path is returned. llm: LLM enhancement (clean-up and front matter). Omit or null to follow the server's configuration (llm.enabled, off by default); false forces it off; true enables it for this call, which may incur provider charges. It needs a model: MODEL (with its provider's API key) in the server's env block, a signed-in subscription runtime, or llm.model_list in the configuration; without one the call fails with setup guidance. ocr: Local OCR for scanned PDF pages and images (macOS Vision, or the portable PaddleOCR models `markitai doctor --fix` installs). Omit to follow the configuration. screenshot: Page screenshots (PDF pages; Office documents through LibreOffice when it is installed; web pages through the isolated Chromium). Omit to follow the configuration. alt: LLM alt text for pictures (needs llm enabled). desc: LLM picture descriptions (needs llm enabled). profile: Shape the output for a consumer: "rag", "obsidian" or "okf". Omit or null to follow the configuration. Omitted or null flags follow the server's configuration, reloaded for every call; a feature this build or machine cannot provide fails explicitly instead of being skipped. Returns: The same shape as convert_document: source, markdown (or a previe…

Report the progress and results of a batch_convert job. Args: job_id: The id batch_convert returned. Returns: job_id; status: "running" until every item ended, then "completed" (also when items failed), or "cancelled" when the server shut down before every item started; total; done: items that succeeded, as in markitai serve; failed: items that failed; finished: done + failed, every item that ended (use it for progress); output_dir; results: one entry per finished item, {source, status: "ok", markdown_file, cost_usd, warnings} or {source, status: "error", error}, either with diagnostics and pricing when a model was called; and, when any item has pricing, the job's pricing and summed cost_usd. Poll until status is not "running", then read the markdown_file paths. Results keep the caller's order: once status is "completed", results[i] answers sources[i]; a running or cancelled job omits unfinished items, so match each result by its source then. Failure modes: an unknown job_id (jobs live in server memory and are lost when the server restarts) or a job that finished and was forgotten (the server keeps the 100 most recent finished jobs); the two errors say which, and the output files remain on disk.