Skip to content

xberg-io/html-to-markdown / plugin/.cursor-plugin/skills/html-to-markdown-using-the-mcp-server

html-to-markdown-using-the-mcp-server

Verified

Use when converting HTML to Markdown or extracting metadata and tables through the html-to-markdown MCP server's tools, rather than shelling out to the CLI. Covers the tool surface, the auto-installing launcher, and when MCP beats the CLI or SDK.

FileKindSize
SKILL.mdskill md3.0 KB
index.mdmarkdown539 B
references/cli-reference.mdmarkdown18.5 KB
references/configuration.mdmarkdown18.8 KB
references/other-bindings.mdmarkdown12.3 KB
references/python-api.mdmarkdown8.0 KB
references/rust-api.mdmarkdown10.5 KB
references/typescript-api.mdmarkdown6.8 KB
---
description: Use when converting HTML to Markdown or extracting metadata and tables through the html-to-markdown MCP server's tools, rather than shelling out to the CLI. Covers the tool surface, the auto-installing launcher, and when MCP beats the CLI or SDK.
name: html-to-markdown-using-the-mcp-server
---

<!--
AI-RULEZ :: GENERATED FILE — DO NOT EDIT
Content-Hash: blake3:3c429c4ad8d72a902e49ab130b4956fe0192d6f9ca57e586494fba0d84eb7fef
Source-Hash: blake3:de6ae056e22a8c2f20286b578b846613c692a655e1ab843bb4d9e42221abd85b
Schema-Version: v1
-->

# Using the MCP Server

The `html-to-markdown` MCP server exposes the converter's conversion and
metadata-extraction capabilities as MCP tools, so an MCP-compatible client (Claude
Code, Claude Desktop) can convert HTML and pull structured metadata directly,
with no CLI invocation or glue code.

## Standalone skill installation

Installing this skill alone does not register an MCP server or include the plugin launcher.
Install the CLI (for example, `brew install xberg-io/tap/html-to-markdown`), then configure your MCP client with
`html-to-markdown mcp` as its stdio command. The full product plugin supplies registration where
the runtime supports MCP.

## How it runs in this plugin

The plugin auto-registers the server through its bundled MCP launcher, which execs
`html-to-markdown mcp`. On first run the
launcher resolves an `html-to-markdown` binary: it reuses one already on `PATH`
or cached in the plugin's `bin/`, then tries `npx`/`uvx`, then Homebrew, then
downloads a prebuilt from the tool's latest GitHub release. Override the channel
with `HTML_TO_MARKDOWN_LAUNCHER=auto|npx|uvx|brew|download`.

The `mcp` subcommand ships in a recent release of the tool. If an older
`html-to-markdown` is already on `PATH`, it may not expose `mcp` yet — upgrade
the binary (`brew upgrade`, re-download, or rebuild) to pick it up.

To run it manually:

```bash
html-to-markdown mcp        # for Claude Code / Claude Desktop (stdio)
```

## The tools

- **convert_html** — convert an HTML string to Markdown, Djot, or plain text.
  Takes `html` (the HTML string), an optional `config` object mirroring
  `ConversionOptions`, and an optional `json` flag. With `json: true` it returns
  the full `ConversionResult` (content, tables, metadata, document structure,
  inline images, warnings) instead of the bare converted text.
- **extract_metadata** — pull structured metadata (document info, Open
  Graph / Twitter / JSON-LD / Microdata, headers, links, images) from an HTML
  string. Takes only `html`.

Both tools accept an HTML **string** — the MCP server does not fetch URLs or read
files (that is CLI-only). The exact argument schemas come from the running
server; ask the client to list tools to see the live surface.

## When to prefer MCP over the CLI or SDK

- **Prefer MCP** inside an agent session: the agent calls the converter directly
  as a tool, with no shell-out and no process management.
- **Prefer the CLI** for one-shot conversions and shell pipelines (`… | jq`).
- **Prefer the SDK** when embedding conversion in application code.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall