{ "markdown": "# parse-mcp\n\n\n\n\n

\n \"License\"\n \"GitHub\n \"Last\n \"Open\n \"PyPI\n \"PyPI\n \"Built\n

\n\n\n\nOne MCP, many parsers. Default markitdown (free, fast, MIT). Escalate to Docling (table-heavy, scanned PDFs) or LlamaParse (cloud, BYOK) when markitdown's quality isn't enough. Plus an `interpret` tool that pipes parsed markdown into Claude for \"summarize / extract X\" so you stop juggling parsers and anthropic skills.\n\n## Install\n\nOpen Claude Code, paste:\n\n /plugin marketplace add adelaidasofia/parse-mcp\n /plugin install parse-mcp@parse-mcp\n\n
Legacy install\n\nManual install (pre-plugin-marketplace). See `SETUP.md` for full details.\n\n```bash\npip3 install --break-system-packages -r requirements.txt\npip3 install --break-system-packages 'markitdown[pdf,docx,pptx,xlsx]'\n```\n\nThen register the server in your client's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"parse\": {\n \"command\": \"python3\",\n \"args\": [\"/absolute/path/to/parse-mcp/server.py\"]\n }\n }\n}\n```\n\n
\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `parse(source, backend?, hints?)` | File path or http(s) URL to markdown. Router picks backend, falls back on empty/error. Returns markdown plus a chain of every backend attempted. |\n| `parse_url(url, backend?)` | Shortcut for HTTP(S) inputs. Same return shape as `parse`. |\n| `parse_to_vault(source, vault_folder?, backend?, overwrite?)` | Parse + write the result as a markdown note in the vault. Default folder: `/📥 Inbox/Converted/`. Frontmatter records source, format, backend, latency, bytes_in. Replaces the standalone `markitdown_to_vault.py` shell script. |\n| `interpret(source, instruction, backend?, model?, max_tokens?)` | Parse first, then ask Claude over the parsed markdown. Cache hits reuse parsed text for free input tokens. |\n| `list_backends()` | Which backends are installed + which are missing. Diagnostic. |\n| `benchmark(source)` | Run every available backend on the same input. Compare latency + output side by side. |\n| `chunk_text(text, doc_type?, target_tokens?, max_tokens?, min_tokens?)` | Chunk parsed markdown into retrieval-ready pieces using a doc-type-aware chunker. `doc_type=\"auto\"` (default) runs structural detection and picks one of paper / book / manual / qa / resume / table / default. Each chunker honors document shape (e.g., `paper` keeps the abstract whole; `manual` never merges across numbered sections; `qa` pairs each question with its answer). Returns chunks + the resolved doc_type. See `chunkers/` package. |\n| `detect_doc_type(text)` | Diagnostic. Run structural heuristics over markdown and return the doc_type that `chunk_text` would pick. |\n\n## Backends (priority order)\n\n1. **markitdown** (default, MIT, base install). PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPub, ZIP. Fast, deterministic.\n2. **docling** (optional, `pip install docling`). Best for complex tables (97.9% on benchmark) + scanned PDFs. Downloads model weights on first run.\n3. **llamaparse** (optional, BYOK, `pip install llama-cloud-services` + `LLAMA_CLOUD_API_KEY`). Cloud, cleanest output on visually-complex PDFs.\n\n## Routing strategy\n\n- `parse(source)` with no `backend` arg: router picks based on file format, falls back if backend errors or returns empty.\n- `parse(source, backend=\"docling\")`: force a specific backend, no fallback. Diagnostic mode.\n- Unavailable backends are skipped (logged in the chain), never errored.\n\n## Parse-fidelity eval\n\nThe routing table above used to be a guess. `tests/eval/` turns it into data: a\nsynthetic fixture corpus (16 documents across digital PDF, scanned/image-only\nPDF, table-heavy, multi-column, and raster image classes) with derived\nground-truth markdown, scored against each backend's output on three\nOmniDocBench / PubTabNet metrics — text edit distance, table **TEDS**\n(tree-edit-distance similarity), and reading-order. All scores are quality in\n[0, 1], higher is better.\n\nHeadline result (full table: [`tests/eval/parse_fidelity_matrix.md`](tests/eval/parse_fidelity_matrix.md)):\n\n| doc-class | markitdown (text) | docling (text) |\n|---|---|---|\n| digital_pdf | 0.95 | 0.97 |\n| table_heavy | 0.93 | 0.89 |\n| scanned_pdf | **0.00** | 0.87 |\n| image | **0.00** | 0.90 |\n| multicolumn | 0.35 | 1.00 |\n\nmarkitdown is great on clean digital text and digital tables (free, fast,\ndeterministic) but has **no OCR** — it scores zero on scanned PDFs and images —\nand it interleaves multi-column layouts. docling wins every class via OCR +\nlayout analysis, at the cost of model-weight downloads. That is the evidence\nbehind the format-preference chain (escalate image/scanned/multi-column to\ndocling first).\n\nRun it:\n\n```bash\npip install docling # the escalation backend under test\npython tests/eval/generate_fixtures.py # rebuild the corpus (needs fpdf2 + Pillow)\nmake eval # -> parse_fidelity_matrix.{md,json}\n```\n\nThe matrix records its **provenance** (backend + python versions + a fixture-set\nhash), so a stale result is visible — regenerate with `make eval` whenever a\nparse backend is upgraded or retuned. It also reports **median latency** per\nbackend (the cost axis): the highest-fidelity backend (docling) is far slower\nthan the default, so the router escalates to it rather than defaulting to it.\n\nThe scorer's metric tests are pure-Python and backend-free, so `pytest tests/`\ngates them in CI with only the base (markitdown) install — a routing regression\nthat breaks the \"markitdown has no OCR\" assumption fails the build.\n\n## Architecture\n\nFastMCP v3.2.3+, stdio transport, Python 3.13+. Registered in `[VAULT_ROOT]/.mcp.json`. No daemons, no listeners, no model weights downloaded by default.\n\nSee `SETUP.md` for install + per-backend opt-in.\n\n## Related MCPs\n\nSame author, same architecture pattern (FastMCP, draft+confirm on writes, vault auto-export where applicable):\n\n- [slack-mcp](https://github.com/adelaidasofia/slack-mcp) — multi-workspace Slack\n- [imessage-mcp](https://github.com/adelaidasofia/imessage-mcp) — macOS iMessage\n- [whatsapp-mcp](https://github.com/adelaidasofia/whatsapp-mcp) — WhatsApp via whatsmeow\n- [apollo-mcp](https://github.com/adelaidasofia/apollo-mcp) — Apollo.io CRM + sequences\n- [google-workspace-mcp](https://github.com/adelaidasofia/google-workspace-mcp) — Gmail / Calendar / Drive / Docs / Sheets\n- [substack-mcp](https://github.com/adelaidasofia/substack-mcp) — Substack writing + analytics\n\n\n## Telemetry\n\nThis plugin sends a single anonymous install signal to `myceliumai.co` the first time it loads in a Claude Code session on a given machine.\n\n**What is sent:**\n- Plugin name (e.g. `slack-mcp`)\n- Plugin version (e.g. `0.1.0`)\n\n**What is NOT sent:**\n- No user identifiers, names, emails, tokens, or API keys\n- No file paths, message content, or anything from your work\n- No IP address is stored after dedup processing\n\n**Why:** Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.\n\n**Opt out:** Set the environment variable `MYCELIUM_NO_PING=1` before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at `~/.mycelium/onboarded-` — delete it if you want to reset state.\n\n## License\n\nMIT. See `LICENSE`.\n\n---\n\nFull install or team version at [diazroa.com](https://diazroa.com).\n", "bytes": 8519, "sha": "d0c6eb7b34670ac1059f7876d3cf176878ccfebf8a8ff84a547f411002ec6f7b", "repo_slug": "adelaidasofia/parse-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_adelaidasofia_parse_mcp_0936e4e2/readme" }