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.

View File

@@ -47,6 +47,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
- [using-system-snapshot-design.md](concepts/using-system-snapshot-design.md) — `using-system-snapshot` v0.1.0 — thin read-only skill wrapping the single `mcp__projects-meta__meta_system_snapshot` call (poller + local docker + cached task summary); replaces scattered `tasklist`/`docker ps`/manual `meta_status`; core rule = no liveness claim without calling the tool this turn; three-line output; defers deep docker to [[using-vds-ops]] and precise tasks to [[using-projects-meta]]
- [using-tasks-status-archival.md](concepts/using-tasks-status-archival.md) — `using-tasks` v1.3.0 done-task archival rule (≥10 🟢 → `.tasks/archive/YYYY-MM.md`) fixes STATUS.md bloat; documents why `tasks_get_status` (single-task, by slug) / `tasks_aggregate` (cross-project cache) can't replace the orientation board-read, so the literal task instruction was not followed
- [delegate-task-negative-trigger-fp.md](concepts/delegate-task-negative-trigger-fp.md) — `delegate-task` v0.2.1 FP fix: «создать задачу себе» stem-matched the «создать задачу на агента» positive trigger; abstract "does NOT apply when doing the work yourself" carve-out loses to literal stem-match under the 1%-rule → made the negative literal + routed (→ using-tasks). Verified pos 5/5, neg 4/5 (was 0/5)
- [using-markitdown-cli-migration.md](concepts/using-markitdown-cli-migration.md) — `using-markitdown` v1.0.0→v1.0.1 (PATCH): rewrote from the Docker-based `mcp__markitdown__convert_to_markdown` MCP tool to the native `markitdown` CLI (0.1.6, on PATH); dropped the host→container `file://` mount caveat; container decommission is by image ancestor (`--filter ancestor=markitdown-mcp:latest`), not by the non-existent name `markitdown-mcp`
## Packages

View File

@@ -74,3 +74,4 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
## [2026-06-09] decision | using-tasks-session-break — `using-tasks` 1.1.0→1.2.0 (MINOR): added the `session_break` marker. Task author sets `session_break: true | "<hint>"` in task frontmatter (mirrored as `**Session break:**` on the local board); after the task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim line `🔚 SESSION BOUNDARY — [slug] закрыта. Рекомендую завершить текущую сессию. Следующий трек: [value | "см. STATUS.md"]` and stops instead of chaining the next task. Absent → behaviour unchanged. Enforced in Task completion step 6 + Rules bullet + format docs. Marker not heuristic: the stop-point is an authoring choice, not a runner guess.
## [2026-06-09] review | using-tasks-status-archival v1.3.0 — VERDICT PASS 3/3 (using-tasks-status-read-perf-review). Criterion «ориентация через `tasks_get_status`, не Read» is satisfied by a **validated deviation**, not a literal swap: re-verified against the live tool schema that `tasks_get_status(target_project, slug)→{status, found}` takes a required slug and returns ONE task — it cannot enumerate the board, so it cannot drive orientation; the implementer correctly rejected the impossible instruction and fixed the real problem (bloat→archival). No regression: orientation still reads local STATUS.md (Session start §2) and the «what's next» flow still reads the board — change is purely additive. Archival rule clear & complete (≥10 threshold, two trigger points, monthly append-only archive, verbatim blocks, dedicated commit, cross-referenced). One informational non-blocking note: this repo's own STATUS.md (>10 🟢) would itself trip the rule — dogfooding tracked separately as tasks-board-cleanup-2026-05. No follow-up tasks. Verdict appended to concepts/using-tasks-status-archival.md.
## [2026-06-09] decision | delegate-task-review-weight — `delegate-task` 0.2.2→0.2.3 (PATCH): Step 5 (paired `<slug>-review` task) now sets an explicit `weight`, inherited from the impl-task with a `needs-claude` floor (impl `needs-human`→review `needs-human`; `needs-claude`→`needs-claude`; `cheap-ok`→`needs-claude`). Root cause of commit `c0af151` ("add Weight: needs-claude to 4 review tasks — reconciler was skipping them"): the authoring skill omitted `weight` on review tasks, making them invisible to fleet routing. Floor (not pure inheritance) chosen to stay internally consistent with the skill's own "What NOT to do" bullet that forbids `cheap-ok` for review tasks — a `cheap-ok` impl would otherwise propagate a forbidden `cheap-ok` review. Added a What-NOT-to-do bullet against weightless review tasks. Concept page concepts/delegate-task-review-weight.md + index. TDD N/A (markdown policy artifact).
## [2026-06-09] decision | using-markitdown-cli-migration — `using-markitdown` 1.0.0→1.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). Tool block now `markitdown <path|url>` → stdout (or `-o file`); removed the whole "Docker-mount caveat (READ FIRST)" section (host→container `file://` translation + `[Errno 2] /c:/Users/...` symptom are gone — CLI sees the full host FS). Updated the ingest pattern (use `-o` straight into `.wiki/raw/`), the gotchas table (`command not found` → check `markitdown --version`, install `pip install markitdown[all]`; dropped the MCP "tool not available / ToolSearch" row), and the contrast-table header (CLI, not MCP). Description frontmatter (the WHEN-to-use triggers) left unchanged. Container decommission: the task's literal `docker stop/rm markitdown-mcp` had no target — no container is named that; the MCP spawns anonymously-named containers from `markitdown-mcp:latest` per session (3 had piled up). Removed all by image ancestor (`docker rm -f $(docker ps -aq --filter "ancestor=markitdown-mcp:latest")`), verified none remain. Left the `mcpServers.markitdown` entry in `~/.claude.json` untouched (out of scope; a container will respawn next session until it's deregistered — flagged as a follow-up). Concept page concepts/using-markitdown-cli-migration.md + index. TDD N/A (markdown skill).