@aiquants/html-to-markdown 0.2.6 → 0.4.0

package/README.md

@@ -136,12 +136,31 @@ npx --package=@aiquants/html-to-markdown aiq-html2md-mcp-stream
   - `url` (required*): The URL of the web page to convert
   - `html_content` (required*): HTML content as a string to convert (alternative to URL)
   - `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`)
-  - `save_path` (optional): Full path (including filename) where to save the converted content
-  - `save_directory` (optional): Directory path where to save the converted content with auto-generated filename
 
   *Either `url` or `html_content` is required
 
+- **save_content_to_file**: Save text content to a file with specified path or directory
+  - `content` (required): Text content to save to file (will be saved as Markdown format)
+  - `save_path` (optional): Complete file path including filename to save content
+  - `save_directory` (optional): Directory path to save content with auto-generated filename
+  - `filename` (optional): Base filename to use when save_directory is specified (extension .md will be added automatically)
+
+- **url_to_markdown_file**: Convert web pages or HTML strings directly to Markdown files (combines conversion and file saving)
+  - `url` (required*): The URL of the web page to convert and save
+  - `html_content` (required*): HTML content as a string to convert and save (alternative to URL)
+  - `locale` (optional): Browser locale (`en-US` or `ja-JP`, defaults to `en-US`)
+  - `save_path` (optional): Complete file path including filename to save the converted content
+  - `save_directory` (optional): Directory path to save the converted content with auto-generated filename
+  - `filename` (optional): Base filename to use when save_directory is specified (extension .md will be added automatically)
+
+  *Either `url` or `html_content` is required, and either `save_path` or `save_directory` is required
+
+**Streamable MCP Tools (for real-time progress updates):**
+
+- **html_to_markdown_streamable**: Same as `html_to_markdown` but with real-time progress updates
+- **save_content_to_file**: Same file saving functionality as in standard MCP
+- **url_to_markdown_file_streamable**: Same as `url_to_markdown_file` but with real-time progress updates and streaming support
+
 **File Saving Options:**
 
 - **`save_path`**: Specify the complete file path including filename and extension where you want to save the content.
@@ -157,13 +176,75 @@ npx --package=@aiquants/html-to-markdown aiq-html2md-mcp-stream
 
 **File Saving Behavior:**
 
-- When `output_format` is `markdown`: Only a `.md` file is saved
-- When `output_format` is `html`: Only a `.html` file is saved
-- When `output_format` is `both`: Both `.md` and `.html` files are saved
-  - With `save_path`: Files are saved as `path.md` and `path.html`
-  - With `save_directory`: Files are saved as `filename.md` and `filename.html`
+- All content is saved as Markdown format (`.md` files)
+- The directory will be created automatically if it doesn't exist
+- With `save_path`: File is saved to the exact specified path
+- With `save_directory`: File is saved with auto-generated filename based on the URL or custom filename if provided
+
+#### MCP Usage Examples
+
+##### Example 1: Basic HTML to Markdown conversion
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "html_to_markdown",
+    "arguments": {
+      "url": "https://example.com",
+      "locale": "en-US"
+    }
+  }
+}
+```
+
+##### Example 2: Save content to a specific file
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "save_content_to_file",
+    "arguments": {
+      "content": "# My Content\n\nThis is my markdown content.",
+      "save_path": "/path/to/my-file.md"
+    }
+  }
+}
+```
+
+##### Example 3: Convert URL directly to Markdown file (One-step operation)
 
-- **html_to_markdown_streamable**: Same as above but with streamable MCP support for progress updates
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "url_to_markdown_file",
+    "arguments": {
+      "url": "https://example.com/article",
+      "save_directory": "/path/to/output/",
+      "filename": "my-article",
+      "locale": "en-US"
+    }
+  }
+}
+```
+
+##### Example 4: Streamable conversion with real-time progress
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "url_to_markdown_file_streamable",
+    "arguments": {
+      "url": "https://example.com/large-page",
+      "save_path": "/path/to/large-page.md",
+      "locale": "ja-JP"
+    }
+  }
+}
+```
 
 ### Using MCP Server Programmatically
 

package/dist/index.cjs

@@ -1 +1 @@
-const e=new(require("happy-dom").Window);Object.assign(global,{document:e.document,window:e,self:e}),Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./core-D2dlEt1l.cjs"),t=require("./mcp-server-Bo_mCvzz.cjs"),c=require("./mcp-server-streamable-Cc4QsZQe.cjs");exports.getMessage=r.getMessage,exports.htmlToMarkdown=r.htmlToMarkdown,exports.createMcpServer=t.createMcpServer,exports.runMcpServer=t.runMcpServer,exports.createStreamableMcpServer=c.createStreamableMcpServer,exports.runStreamableMcpServer=c.runStreamableMcpServer;
+const e=new(require("happy-dom").Window);Object.assign(global,{document:e.document,window:e,self:e}),Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./core-D2dlEt1l.cjs"),t=require("./mcp-server-Co1kuNGX.cjs"),c=require("./mcp-server-streamable-BNn6Kd9b.cjs");exports.getMessage=r.getMessage,exports.htmlToMarkdown=r.htmlToMarkdown,exports.createMcpServer=t.createMcpServer,exports.runMcpServer=t.runMcpServer,exports.createStreamableMcpServer=c.createStreamableMcpServer,exports.runStreamableMcpServer=c.runStreamableMcpServer;

package/dist/index.js

@@ -6,8 +6,8 @@ Object.assign(global, {
   self: window
 });
 import { g, h } from "./core-CouDTni-.js";
-import { c, r } from "./mcp-server-B8hz3lXI.js";
-import { c as c2, r as r2 } from "./mcp-server-streamable-3B3B1fuS.js";
+import { c, r } from "./mcp-server-DzB_5cTs.js";
+import { c as c2, r as r2 } from "./mcp-server-streamable-CcZ7Lsel.js";
 export {
   c as createMcpServer,
   c2 as createStreamableMcpServer,

package/dist/mcp-server-Co1kuNGX.cjs

@@ -0,0 +1 @@
+const e=new(require("happy-dom").Window);Object.assign(global,{document:e.document,window:e,self:e});const t=require("./version-dpS3SSul.cjs"),r=require("node:process"),a=require("./core-D2dlEt1l.cjs");class n{append(e){this._buffer=this._buffer?Buffer.concat([this._buffer,e]):e}readMessage(){if(!this._buffer)return null;const e=this._buffer.indexOf("\n");if(-1===e)return null;const r=this._buffer.toString("utf8",0,e).replace(/\r$/,"");return this._buffer=this._buffer.subarray(e+1),function(e){return t.JSONRPCMessageSchema.parse(JSON.parse(e))}(r)}clear(){this._buffer=void 0}}class s{constructor(e=r.stdin,t=r.stdout){this._stdin=e,this._stdout=t,this._readBuffer=new n,this._started=!1,this._ondata=e=>{this._readBuffer.append(e),this.processReadBuffer()},this._onerror=e=>{var t;null===(t=this.onerror)||void 0===t||t.call(this,e)}}async start(){if(this._started)throw new Error("StdioServerTransport already started! If using Server class, note that connect() calls start() automatically.");this._started=!0,this._stdin.on("data",this._ondata),this._stdin.on("error",this._onerror)}processReadBuffer(){for(var e,t;;)try{const t=this._readBuffer.readMessage();if(null===t)break;null===(e=this.onmessage)||void 0===e||e.call(this,t)}catch(r){null===(t=this.onerror)||void 0===t||t.call(this,r)}}async close(){var e;this._stdin.off("data",this._ondata),this._stdin.off("error",this._onerror);0===this._stdin.listenerCount("data")&&this._stdin.pause(),this._readBuffer.clear(),null===(e=this.onclose)||void 0===e||e.call(this)}send(e){return new Promise(t=>{const r=function(e){return JSON.stringify(e)+"\n"}(e);this._stdout.write(r)?t():this._stdout.once("drain",t)})}}class o{constructor(){this.version=t.getPackageVersion(),this.server=new t.Server({name:"@aiquants/html-to-markdown",version:this.version,description:"Convert web pages and HTML to Markdown with JavaScript dynamic content support and table structure preservation. Includes separate file saving tool."},{capabilities:{tools:{}}}),this.setupToolHandlers()}setupToolHandlers(){this.server.setRequestHandler(t.ListToolsRequestSchema,async()=>({tools:[{name:"html_to_markdown",description:"Convert web pages or HTML strings to Markdown format. Handles JavaScript-rendered dynamic content and preserves table structures.",inputSchema:t.MCP_TOOL_SCHEMAS.htmlToMarkdown},{name:"save_content_to_file",description:"Save text content to a file with specified path or directory. Supports automatic filename generation and format detection.",inputSchema:t.MCP_TOOL_SCHEMAS.saveContentToFile},{name:"url_to_markdown_file",description:"Convert web pages or HTML strings directly to Markdown files. Combines HTML-to-Markdown conversion and file saving in one step. Handles JavaScript-rendered dynamic content.",inputSchema:t.MCP_TOOL_SCHEMAS.urlToMarkdownFile}]})),this.server.setRequestHandler(t.CallToolRequestSchema,async e=>{switch(e.params.name){case"html_to_markdown":return await this.handleHtmlToMarkdown(e.params.arguments);case"save_content_to_file":return await this.handleSaveContentToFile(e.params.arguments);case"url_to_markdown_file":return await this.handleUrlToMarkdownFile(e.params.arguments);default:throw new Error(`Unknown tool: ${e.params.name}`)}})}async handleHtmlToMarkdown(e){try{const r=t.parseHtmlToMarkdownArgs(e),{url:n,html_content:s,locale:o="en-US"}=r;if(n)try{new URL(n)}catch{throw new Error(`Invalid URL: ${n}`)}const i=(await a.htmlToMarkdown(n||"direct-html-input",{locale:o,htmlContent:s})).markdown;return t.createSuccessResult(i)}catch(r){return t.createErrorResult(r)}}async handleSaveContentToFile(e){try{const r=t.parseSaveContentArgs(e),{content:a,save_path:n,save_directory:s,filename:o}=r,i=`File saved successfully to: ${await t.saveContentToFile(a,n,s,o)}`;return t.createSuccessResult(i)}catch(r){return t.createErrorResult(r)}}async handleUrlToMarkdownFile(e){try{const r=t.parseUrlToMarkdownFileArgs(e),{url:n,html_content:s,locale:o="en-US",save_path:i,save_directory:c,filename:l}=r;if(n)try{new URL(n)}catch{throw new Error(`Invalid URL: ${n}`)}const d=(await a.htmlToMarkdown(n||"direct-html-input",{locale:o,htmlContent:s})).markdown;let u=l;!u&&n&&(u=this.generateFilenameFromUrl(n));const h=`URL successfully converted to Markdown and saved to: ${await t.saveContentToFile(d,i,c,u)}`;return t.createSuccessResult(h)}catch(r){return t.createErrorResult(r)}}generateFilenameFromUrl(e){try{let t=new URL(e).pathname.split("/").pop()||"page";return t=t.replace(/\.[^.]*$/,""),t=t.replace(/[<>:"/\\|?*]/g,"_"),t&&!t.match(/^\.+$/)||(t="page"),t}catch{return"page"}}async start(){const e=new s;await this.server.connect(e)}}const i=()=>new o;exports.createMcpServer=i,exports.runMcpServer=async()=>{const e=i();await e.start()};

package/dist/mcp-server-DzB_5cTs.js

@@ -0,0 +1,267 @@
+import { Window } from "happy-dom";
+const window = new Window();
+Object.assign(global, {
+  document: window.document,
+  window,
+  self: window
+});
+import { J as JSONRPCMessageSchema, g as getPackageVersion, S as Server, L as ListToolsRequestSchema, M as MCP_TOOL_SCHEMAS, C as CallToolRequestSchema, p as parseHtmlToMarkdownArgs, c as createSuccessResult, a as createErrorResult, b as parseSaveContentArgs, s as saveContentToFile, d as parseUrlToMarkdownFileArgs } from "./version-BSh9aXhF.js";
+import process from "node:process";
+import { h as htmlToMarkdown } from "./core-CouDTni-.js";
+class ReadBuffer {
+  append(chunk) {
+    this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
+  }
+  readMessage() {
+    if (!this._buffer) {
+      return null;
+    }
+    const index = this._buffer.indexOf("\n");
+    if (index === -1) {
+      return null;
+    }
+    const line = this._buffer.toString("utf8", 0, index).replace(/\r$/, "");
+    this._buffer = this._buffer.subarray(index + 1);
+    return deserializeMessage(line);
+  }
+  clear() {
+    this._buffer = void 0;
+  }
+}
+function deserializeMessage(line) {
+  return JSONRPCMessageSchema.parse(JSON.parse(line));
+}
+function serializeMessage(message) {
+  return JSON.stringify(message) + "\n";
+}
+class StdioServerTransport {
+  constructor(_stdin = process.stdin, _stdout = process.stdout) {
+    this._stdin = _stdin;
+    this._stdout = _stdout;
+    this._readBuffer = new ReadBuffer();
+    this._started = false;
+    this._ondata = (chunk) => {
+      this._readBuffer.append(chunk);
+      this.processReadBuffer();
+    };
+    this._onerror = (error) => {
+      var _a;
+      (_a = this.onerror) === null || _a === void 0 ? void 0 : _a.call(this, error);
+    };
+  }
+  /**
+   * Starts listening for messages on stdin.
+   */
+  async start() {
+    if (this._started) {
+      throw new Error("StdioServerTransport already started! If using Server class, note that connect() calls start() automatically.");
+    }
+    this._started = true;
+    this._stdin.on("data", this._ondata);
+    this._stdin.on("error", this._onerror);
+  }
+  processReadBuffer() {
+    var _a, _b;
+    while (true) {
+      try {
+        const message = this._readBuffer.readMessage();
+        if (message === null) {
+          break;
+        }
+        (_a = this.onmessage) === null || _a === void 0 ? void 0 : _a.call(this, message);
+      } catch (error) {
+        (_b = this.onerror) === null || _b === void 0 ? void 0 : _b.call(this, error);
+      }
+    }
+  }
+  async close() {
+    var _a;
+    this._stdin.off("data", this._ondata);
+    this._stdin.off("error", this._onerror);
+    const remainingDataListeners = this._stdin.listenerCount("data");
+    if (remainingDataListeners === 0) {
+      this._stdin.pause();
+    }
+    this._readBuffer.clear();
+    (_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
+  }
+  send(message) {
+    return new Promise((resolve) => {
+      const json = serializeMessage(message);
+      if (this._stdout.write(json)) {
+        resolve();
+      } else {
+        this._stdout.once("drain", resolve);
+      }
+    });
+  }
+}
+class HtmlToMarkdownMcpServer {
+  constructor() {
+    this.version = getPackageVersion();
+    this.server = new Server(
+      {
+        name: "@aiquants/html-to-markdown",
+        version: this.version,
+        description: "Convert web pages and HTML to Markdown with JavaScript dynamic content support and table structure preservation. Includes separate file saving tool."
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.setupToolHandlers();
+  }
+  /**
+   * Setup tool handlers for the MCP server.
+   * MCP サーバーのツールハンドラーを設定
+   */
+  setupToolHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: [
+          {
+            name: "html_to_markdown",
+            description: "Convert web pages or HTML strings to Markdown format. Handles JavaScript-rendered dynamic content and preserves table structures.",
+            inputSchema: MCP_TOOL_SCHEMAS.htmlToMarkdown
+          },
+          {
+            name: "save_content_to_file",
+            description: "Save text content to a file with specified path or directory. Supports automatic filename generation and format detection.",
+            inputSchema: MCP_TOOL_SCHEMAS.saveContentToFile
+          },
+          {
+            name: "url_to_markdown_file",
+            description: "Convert web pages or HTML strings directly to Markdown files. Combines HTML-to-Markdown conversion and file saving in one step. Handles JavaScript-rendered dynamic content.",
+            inputSchema: MCP_TOOL_SCHEMAS.urlToMarkdownFile
+          }
+        ]
+      };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      switch (request.params.name) {
+        case "html_to_markdown": {
+          return await this.handleHtmlToMarkdown(request.params.arguments);
+        }
+        case "save_content_to_file": {
+          return await this.handleSaveContentToFile(request.params.arguments);
+        }
+        case "url_to_markdown_file": {
+          return await this.handleUrlToMarkdownFile(request.params.arguments);
+        }
+        default:
+          throw new Error(`Unknown tool: ${request.params.name}`);
+      }
+    });
+  }
+  /**
+   * Handle HTML to Markdown conversion tool call.
+   * HTML から Markdown への変換ツール呼び出しを処理
+   */
+  async handleHtmlToMarkdown(args) {
+    try {
+      const validatedArgs = parseHtmlToMarkdownArgs(args);
+      const { url, html_content, locale = "en-US" } = validatedArgs;
+      if (url) {
+        try {
+          new URL(url);
+        } catch {
+          throw new Error(`Invalid URL: ${url}`);
+        }
+      }
+      const result = await htmlToMarkdown(url || "direct-html-input", {
+        locale,
+        htmlContent: html_content
+      });
+      const responseText = result.markdown;
+      return createSuccessResult(responseText);
+    } catch (error) {
+      return createErrorResult(error);
+    }
+  }
+  /**
+   * Handle save content to file tool call.
+   * ファイル保存ツール呼び出しを処理
+   */
+  async handleSaveContentToFile(args) {
+    try {
+      const validatedArgs = parseSaveContentArgs(args);
+      const { content, save_path, save_directory, filename } = validatedArgs;
+      const savedPath = await saveContentToFile(content, save_path, save_directory, filename);
+      const responseText = `File saved successfully to: ${savedPath}`;
+      return createSuccessResult(responseText);
+    } catch (error) {
+      return createErrorResult(error);
+    }
+  }
+  /**
+   * Handle URL to Markdown file conversion tool call.
+   * URL から Markdown ファイルへの変換ツール呼び出しを処理
+   */
+  async handleUrlToMarkdownFile(args) {
+    try {
+      const validatedArgs = parseUrlToMarkdownFileArgs(args);
+      const { url, html_content, locale = "en-US", save_path, save_directory, filename } = validatedArgs;
+      if (url) {
+        try {
+          new URL(url);
+        } catch {
+          throw new Error(`Invalid URL: ${url}`);
+        }
+      }
+      const result = await htmlToMarkdown(url || "direct-html-input", {
+        locale,
+        htmlContent: html_content
+      });
+      const markdownContent = result.markdown;
+      let finalFilename = filename;
+      if (!finalFilename && url) {
+        finalFilename = this.generateFilenameFromUrl(url);
+      }
+      const savedPath = await saveContentToFile(markdownContent, save_path, save_directory, finalFilename);
+      const responseText = `URL successfully converted to Markdown and saved to: ${savedPath}`;
+      return createSuccessResult(responseText);
+    } catch (error) {
+      return createErrorResult(error);
+    }
+  }
+  /**
+   * Generate filename from URL.
+   * URL からファイル名を生成
+   */
+  generateFilenameFromUrl(url) {
+    try {
+      const urlObj = new URL(url);
+      let filename = urlObj.pathname.split("/").pop() || "page";
+      filename = filename.replace(/\.[^.]*$/, "");
+      filename = filename.replace(/[<>:"/\\|?*]/g, "_");
+      if (!filename || filename.match(/^\.+$/)) {
+        filename = "page";
+      }
+      return filename;
+    } catch {
+      return "page";
+    }
+  }
+  /**
+   * Start the MCP server.
+   * MCP サーバーを開始
+   */
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.info("HTML to Markdown MCP server started");
+  }
+}
+const createMcpServer = () => {
+  return new HtmlToMarkdownMcpServer();
+};
+const runMcpServer = async () => {
+  const server = createMcpServer();
+  await server.start();
+};
+export {
+  createMcpServer as c,
+  runMcpServer as r
+};