{"id":"48b6a4f8-f81c-4657-b784-9dd8bef2a880","slug":"md-anything","kind":"skill","name":"md-anything","summary":"Local-first CLI + MCP server: Any file → AI-ready Markdown + JSON","owner":"ojspace","repoUrl":"https://github.com/ojspace/md-anything","license":"MIT","licenseTier":"permissive","trust":"community","stars":49,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-03-12T20:08:00.000Z","addedAt":"2026-10-14T05:42:34.225Z","logoUrl":"https://avatars.githubusercontent.com/u/28633507?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","search","cloud-infra"],"tags":["ai-agents","claude","cursor","document-processing","markdown","pdf-conversion","rag","vscode"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T06:26:32.603Z","sample":false,"url":"https://conduits.dev/tools/md-anything","language":"TypeScript","transports":["stdio"],"install":{"npm":"md-anything"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# md-anything\n\nConvert files, URLs, and media into honest Markdown for terminal workflows and MCP-powered agents.\n\n`md-anything` currently ships two surfaces:\n\n- a local-first CLI: `mda`\n- a stdio MCP server: `md-anything-mcp`\n\n[![npm version](https://img.shields.io/npm/v/md-anything.svg)](https://www.npmjs.com/package/md-anything) [![npm downloads](https://img.shields.io/npm/dm/md-anything.svg)](https://www.npmjs.com/package/md-anything) [![CI](https://github.com/ojspace/md-anything/actions/workflows/ci.yml/badge.svg)](https://github.com/ojspace/md-anything/actions/workflows/ci.yml) [![GitHub stars](https://img.shields.io/github/stars/ojspace/md-anything.svg?style=social)](https://github.com/ojspace/md-anything/stargazers) ![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ojspace/md-anything/main/install.sh | bash\n```\n\nOr install globally with Bun or npm:\n\n```bash\nbun install -g md-anything\nnpm install -g md-anything\n```\n\nQuick sanity check:\n\n```bash\nmda --help\nmda doctor\n```\n\n## Quick start\n\n```bash\n# Convert one file or URL\nmda tests/fixtures/sample.txt\nmda convert report.pdf\nmda convert \"https://example.com/article\"\n\n# Batch-convert a folder\nmda ingest ./notes -o ./output -r\n\n# Check optional tool availability\nmda doctor\n\n# Copy-paste examples\nmda examples\nmda demo\n```\n\n## What is supported\n\n`md-anything` uses three support levels:\n\n- `strong`: works well out of the box\n- `best-effort`: useful, but quality depends on content and local tools\n- `optional`: requires extra tools or an opt-in remote fallback\n\n| Input | Support | Notes |\n|---|---|---|\n| `.txt`, `.md`, `.markdown`, `.json`, `.html`, `.htm` | strong | Native or straightforward extraction |\n| `http://` / `https://` URLs | strong | Fetch + HTML extraction |\n| `.pdf` | strong | `unpdf` by default, `pdftotext` can improve some files |\n| YouTube URLs | best-effort | Transcript-first, honest fallback when unavailable |\n| Images (`.png`, `.jpg`, `.webp`, `.gif`, etc.) | best-effort | Metadata-only by default, OCR with `tesseract`, richer remote fallback via OpenRouter |\n| `.epub` | best-effort | Extraction depends on `unzip`; `doctor` will tell you if it is missing |\n| `.mobi`, `.azw` | best-effort | Requires Calibre `ebook-convert` |\n| Audio (`.mp3`, `.wav`, etc.) | optional | Local `whisper-cpp` or `whisper`, optional OpenRouter fallback |\n| Video (`.mp4`, `.mov`, etc.) | optional | Requires `ffmpeg` plus `whisper-cpp` / `whisper`, optional OpenRouter fallback |\n\n## CLI reference\n\n```bash\n# Single input\nmda <input>\nmda convert <input>\n\n# Write Markdown to a file\nmda convert report.pdf -o report.md\n\n# Omit frontmatter\nmda convert report.pdf --no-frontmatter\n\n# Machine-readable JSON\nmda convert report.pdf --json\n\n# Batch-convert a folder\nmda ingest ./notes\nmda ingest ./notes -o ./output\nmda ingest ./vault -r -o ./output\n\n# Environment/capability checks\nmda doctor\n\n# Help and examples\nmda --help\nmda examples\nmda demo\n```\n\n### Flags\n\n| Flag | Description |\n|---|---|\n| `-o, --output <path>` | Output file for `convert` or output directory for `ingest` |\n| `--no-frontmatter` | Omit YAML frontmatter from generated Markdown |\n| `--json` | Return machine-readable JSON instead of Markdown |\n| `-r, --recursive` | Recurse into subdirectories during `ingest` |\n| `-h, --help` | Show help |\n\n### JSON output\n\n`convert --json` returns a stable machine-readable envelope:\n\n```bash\nmda convert report.pdf --json\n```\n\n```json\n{\n  \"input\": \"report.pdf\",\n  \"markdown\": \"# Report Title\\n...\",\n  \"kind\": \"pdf\",\n  \"supportLevel\": \"strong\",\n  \"chunks\": [],\n  \"metadata\": {\n    \"extraction\": \"unpdf\",\n    \"extraction_status\": \"ok\",\n    \"support_level\": \"strong\",\n    \"usefulness_score\": 0.85\n  },\n  \"provenance\": {\n    \"documentId\": \"...\"\n  },\n  \"warnings\": []\n}\n```\n\n`ingest --json` returns counts plus per-document metadata:\n\n```bash\nmda ingest ./notes --json\n```\n\n```json\n{\n  \"converted\": 12,\n  \"skipped\": 2,\n  \"failed\": 0,\n  \"docs\": [\n    {\n      \"fileName\": \"note.md\",\n      \"title\": \"My Note\",\n      \"summary\": \"This is a summary of the note.\",\n      \"sourceType\": \"pdf\",\n      \"source\": \"report.pdf\",\n      \"chunks\": [],\n      \"metadata\": {\n        \"extraction_status\": \"ok\"\n      },\n      \"provenance\": {\n        \"documentId\": \"...\"\n      }\n    }\n  ]\n}\n```\n\nArgument errors stay machine-readable too:\n\n```json\n{\n  \"error\": \"Missing input for convert command.\",\n  \"code\": \"missing_input\",\n  \"examples\": [\n    \"mda convert tests/fixtures/sample.txt\",\n    \"mda convert \\\"https://example.com/article\\\"\"\n  ]\n}\n```\n\n## MCP server\n\n### One-command setup\n\n```bash\nmda mcp install claude        # Claude Desktop\nmda mcp install claude-code   # Claude Code CLI\nmda mcp install cursor        # Cursor\nmda mcp install windsurf      # Windsurf\nmda mcp install vscode        # VS Code + GitHub Copilot (writes .vscode/mcp.json)\nmda mcp install antigravity   # Antigravity (writes .vscode/mcp.json)\nmda mcp install opencode      # OpenCode\n```\n\nRestart the client after install. For VS Code, open Command Palette → `MCP: List Servers` to verify.\n\n> **Requires Bun in PATH.** Install globally with `bun install -g md-anything` so `md-anything-mcp` is available.\n> If you used `install.sh`, only the `mda` binary is installed — use `bunx md-anything-mcp` in manual configs below.\n\n### Manual config\n\n**Claude Desktop / Claude Code / Cursor / Windsurf / OpenCode** (`mcpServers` format):\n\n```json\n{\n  \"mcpServers\": {\n    \"md-anything\": {\n      \"command\": \"md-anything-mcp\"\n    }\n  }\n}\n```\n\nConfig file locations:\n\n| Client | Config path |\n|---|---|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |\n| Claude Code | `~/.claude/settings.json` |\n| Cursor | `~/.cursor/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| OpenCode | `~/.config/opencode/config.json` |\n\n**VS Code / GitHub Copilot / Antigravity** — create `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"md-anything\": {\n      \"type\": \"stdio\",\n      \"command\": \"md-anything-mcp\"\n    }\n  }\n}\n```\n\n**Using `bunx` instead of a global install:**\n\n```json\n{\n  \"mcpServers\": {\n    \"md-anything\": {\n      \"command\": \"bunx\",\n      \"args\": [\"md-anything-mcp\"]\n    }\n  }\n}\n```\n\n### Tools\n\n| Tool | Description |\n|---|---|\n| `convert` | Convert a workspace file or safe remote URL to Markdown |\n| `ingest` | Batch-convert a workspace folder |\n| `doctor` | Report current capabilities and optional upgrades |\n\nThe server also exposes resources (`md-anything://doctor`, `md-anything://workspace/{path}`) and prompts (`analyze_document`, `summarize_document_chunks`).\n\n### MCP safety rules\n\n- local paths must stay inside the current workspace root\n- only `http://` and `https://` URLs are allowed\n- private, localhost, and link-local URLs are blocked by default\n- set `MDA_MCP_ALLOW_PRIVATE_URLS=1` to override (use with caution)\n\n## Optional local and remote upgrades\n\nThe default install stays lightweight. No models are bundled, and cloud fallbacks are opt-in.\n\nInstall only what you need:\n\n```bash\nbrew install poppler         # pdftotext for stronger PDF extraction\nbrew install tesseract       # OCR for images\nbrew install --cask calibre  # ebook-convert for MOBI/AZW\nbrew install ffmpeg          # media extraction for video/audio workflows\nbrew install whisper-cpp     # local transcription (preferred)\nwhisper-cpp --download-model base.en\n```\n\nAlso supported:\n\n- `unzip` for EPUB extraction\n- `whisper` (`pip install openai-whisper`) as a transcription fallback\n- `OPENROUTER_API_KEY` as an opt-in remote fallback for image, audio, and video workflows\n\nUse `mda doctor` to see exactly what your machine can do right now.\n\n## Vision\n\nThe goal is for md-anything to become the default open-source layer for document ingestion in agent pipelines — local-first, format-agnostic, and honest about what it can and can't extract. No SaaS lock-in, no cloud required for core workflows.\n\nRoadmap directions: DOCX/PPTX support, streaming output, semantic chunking, watch mode, Python/Go SDK wrappers.\n\n## Why it is built this way\n\n- **Local-first by default**: core workflows work without cloud APIs\n- **Graceful fallback**: weak extraction still returns honest Markdown instead of a hard failure\n- **Agent-ready**: CLI JSON output, chunk/provenance metadata, and an MCP server all share the same core pipeline\n- **Lightweight**: optional tools upgrade specific formats without turning the base install into a heavyweight bundle\n\n## Development\n\n```bash\ngit clone https://github.com/ojspace/md-anything\ncd md-anything\nbun install\n```\n\nValidate changes with:\n\n```bash\nbun run lint\nbun run build\nbun run test:required\n```\n\nOther useful commands:\n\n```bash\nbun test\nbun run test\nbun run test:fixtures\nbun run src/cli.ts doctor\n```\n\n### Project layout\n\n```text\nsrc/\n  cli.ts            CLI entry point\n  mcp.ts            MCP stdio server\n  mcp-support.ts    MCP path/url guardrails and structured content helpers\n  core/             shared conversion, ingest, runtime, chunks, usefulness\n  providers/        one provider per input kind\n  formatters/       final Markdown rendering\ntests/\n  unit/\n  integration/\n  fixtures/\n  generated-fixtures/\n```\n\n## License\n\nMIT\n"}