refactor(using-markitdown): rewrite MCP→CLI, drop Docker section v1.0.1

Replace all mcp__markitdown__convert_to_markdown invocations with the
native `markitdown <path|url>` CLI (v0.1.6, on PATH). Outputs to stdout
or `-o <file>`; sees the full host filesystem, so the Docker bind-mount
caveat (host→container file:// translation, [Errno 2] /c:/Users/...) is
gone and that whole section is removed. Updated the ingest pattern (-o
straight into .wiki/raw/), gotchas table (command-not-found → check
`markitdown --version`), and contrast table header (CLI, not MCP).
Description triggers unchanged. PATCH bump 1.0.0→1.0.1; dist artifact
rebuilt.

Decommissioned the Docker MCP containers: no container is named
`markitdown-mcp` (the server spawns anonymous ones from
markitdown-mcp:latest, 3 had piled up); removed all by image ancestor.
Left mcpServers.markitdown in ~/.claude.json untouched (out of scope) —
flagged as a follow-up in the concept page.

Wiki: concepts/using-markitdown-cli-migration.md + index + log.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-09 20:48:18 +03:00
parent d812944b0e
commit fdc94e08cf
5 changed files with 81 additions and 24 deletions

View File

@@ -0,0 +1,58 @@
---
title: using-markitdown — MCP → CLI migration
type: concept
updated: 2026-06-09
---
# using-markitdown — MCP → CLI migration
`using-markitdown` v1.0.0 → v1.0.1 (PATCH). Rewrote the skill from the Docker-based
`mcp__markitdown__convert_to_markdown` MCP tool to the native `markitdown` CLI (v0.1.6,
on `PATH`).
## Why
The MCP path ran markitdown inside a Docker container with a single host directory
bind-mounted (`-v C:\Users\vitya:/workdir`). That forced a brittle host→container path
translation for every local file (`file:///workdir/...`), and the failure mode
(`[Errno 2] No such file or directory: '/c:/Users/...'`) was a recurring foot-gun. The
container also could not see files outside its one mount.
The CLI is a normal local process: it sees the full host filesystem, takes a plain path
or URL as its positional arg, and writes markdown to stdout (or to a file with `-o`). No
mount, no path rewriting, no `file://` URIs. The whole "Docker-mount caveat (READ FIRST)"
section of the skill became dead weight and was removed.
## CLI contract
```
markitdown <path|url> # → markdown to stdout
markitdown <path|url> -o out.md # → write to a file
cat file.pdf | markitdown -x pdf # → stdin + format hint
```
Verified on this machine: `markitdown 0.1.6`; URL fetch (`markitdown https://example.com`)
and stdout conversion both work.
## Container cleanup gotcha
The task asked to run `docker stop markitdown-mcp && docker rm markitdown-mcp`. There was
**no container named `markitdown-mcp`** — the MCP server spawns a fresh anonymously-named
container from the `markitdown-mcp:latest` image per session, and three had piled up
(`sharp_jones`, `boring_goldberg`, `admiring_kowalevski`, ages 47s28h). The correct
decommission is by image ancestor, not by name:
```
docker rm -f $(docker ps -aq --filter "ancestor=markitdown-mcp:latest")
```
(Stopping them races with the server's own `--rm` cleanup, briefly leaving "Dead"
containers that finish removing themselves — re-checking the filter confirms none remain.)
## Out of scope / follow-up
The `markitdown` **MCP server registration** in `~/.claude.json` was left untouched (the
task scoped only the running container, and editing user-global config is cross-cutting).
While that entry remains, a new container will respawn on the next session that loads the
MCP. A full decommission would deregister `mcpServers.markitdown` from `~/.claude.json`
recommended as a separate, explicitly-confirmed step.