@aiquants/html-to-markdown 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # @aiquants/html-to-markdown
 
-A tool to dynamically fetch a web page from a given URL and convert it to Markdown.
+A tool to dynamically fetch a web page from a given URL and convert it to Markdown. Now with Model Context Protocol (MCP) server support!
 
 This tool fetches the fully rendered HTML after JavaScript execution and converts it to Markdown. It supports complex pages, including footnotes and table structures.
 
@@ -10,7 +10,9 @@ This tool fetches the fully rendered HTML after JavaScript execution and convert
 - **High-Fidelity Conversion**: Performs powerful AST (Abstract Syntax Tree)-based conversion using `rehype` and `remark`.
 - **Preserves Table Content**: Retains HTML tags within table cells (`<td>`, `<th>`) as much as possible to maintain rich formatting.
 - **Link Normalization**: Automatically converts relative links on the page to absolute links to prevent broken links.
-- **Dual Interface**: Usable as both a Node.js library and a command-line tool.
+- **Multiple Interfaces**: Usable as a Node.js library, command-line tool, and MCP server.
+- **MCP Server Support**: Provides Model Context Protocol server functionality for AI assistants.
+- **Streamable MCP Support**: Supports streamable MCP protocols for real-time progress updates.
 
 ## Installation
 
@@ -73,6 +75,83 @@ async function main() {
 main();
 ```
 
+### As an MCP Server
+
+This package can be used as a Model Context Protocol (MCP) server, allowing AI assistants and MCP-compatible applications to convert web pages to Markdown.
+
+#### MCP Server Configuration
+
+**For VS Code with MCP extension, add to your `mcp.json`:**
+
+```json
+{
+  "html-to-md": {
+    "command": "npx",
+    "args": [
+      "aiq-html2md-mcp"
+    ],
+    "type": "stdio"
+  },
+  "html-to-md-streamable": {
+    "url": "http://127.0.0.1:4001/mcp",
+    "type": "http",
+    "_comment": "Note: You need to start the streamable MCP server separately using 'npx aiq-html2md-mcp-stream'"
+  }
+}
+```
+
+**For Claude Desktop or other MCP clients, add to your configuration file:**
+
+```json
+{
+  "mcpServers": {
+    "html-to-markdown": {
+      "command": "npx",
+      "args": ["aiq-html2md-mcp"],
+      "description": "Convert HTML content from URLs to Markdown format"
+    }
+  }
+}
+```
+
+**Note:** The streamable MCP server runs as an HTTP server on port 4001 and needs to be started separately:
+
+```bash
+# Start the streamable MCP server (requires global installation)
+npm install -g @aiquants/html-to-markdown
+aiq-html2md-mcp-stream
+```
+
+Alternatively, you can use npx to run without global installation:
+
+```bash
+# Using npx with the streamable server binary
+npx aiq-html2md-mcp-stream
+```
+
+#### MCP Tools Available
+
+- **html_to_markdown**: Convert HTML content from a URL to Markdown format
+  - `url` (required): The URL of the web page to convert
+  - `locale` (optional): Browser locale (`en-US` or `ja-JP`, defaults to `en-US`)
+  - `output_format` (optional): Output format (`markdown`, `html`, or `both`, defaults to `markdown`)
+
+- **html_to_markdown_streamable**: Same as above but with streamable MCP support for progress updates
+
+### Using MCP Server Programmatically
+
+```typescript
+import { createMcpServer, createStreamableMcpServer } from '@aiquants/html-to-markdown';
+
+// Create standard MCP server
+const mcpServer = createMcpServer();
+await mcpServer.start(8000);  // Port 8000
+
+// Create streamable MCP server
+const streamableMcpServer = createStreamableMcpServer();
+await streamableMcpServer.start(8000);  // Port 8000
+```
+
 ## API
 
 ### `htmlToMarkdown(url, options?)`
@@ -113,22 +192,25 @@ This tool follows these steps for conversion:
 
 This project is built upon the following open-source software. We are grateful to the developers of these libraries.
 
-| Package                  | License    |
-| ------------------------ | ---------- |
-| github-slugger           | MIT        |
-| happy-dom                | MIT        |
-| hast                     | MIT        |
-| hast-util-to-html        | MIT        |
-| playwright               | Apache-2.0 |
-| rehype-parse             | MIT        |
-| rehype-raw               | MIT        |
-| rehype-remark            | MIT        |
-| rehype-slug              | MIT        |
-| remark-gfm               | MIT        |
-| remark-stringify         | MIT        |
-| unified                  | MIT        |
-| unist-util-visit         | MIT        |
-| yargs-parser             | ISC        |
+| Package                    | License    |
+| -------------------------- | ---------- |
+| @modelcontextprotocol/sdk  | MIT        |
+| cors                       | MIT        |
+| express                    | MIT        |
+| github-slugger             | ISC        |
+| happy-dom                  | MIT        |
+| hast                       | MIT        |
+| hast-util-to-html          | MIT        |
+| playwright                 | Apache-2.0 |
+| rehype-parse               | MIT        |
+| rehype-raw                 | MIT        |
+| rehype-remark              | MIT        |
+| rehype-slug                | MIT        |
+| remark-gfm                 | MIT        |
+| remark-stringify           | MIT        |
+| unified                    | MIT        |
+| unist-util-visit           | MIT        |
+| yargs-parser               | ISC        |
 
 *This list is generated based on the `dependencies` in `package.json`. For the most accurate and up-to-date license information, please refer to the individual packages.*