html-reader-llm 0.0.2__tar.gz → 0.0.3__tar.gz

{html_reader_llm-0.0.2 → html_reader_llm-0.0.3}/AGENTS.md

@@ -2,16 +2,16 @@
 
 ## 基本信息
 
-- **项目**：htmlreader — 智能 HTML 解析与提取库
+- **项目**：html-reader-llm — 智能 HTML 解析与提取库
 - **阶段**：Phase 1（核心功能开发）
-- **技术栈**：Python 3.12+ / uv / httpx2 / selectolax
+- **技术栈**：Python 3.12+ / uv / selectolax / trafilatura / fastmcp-slim
 - **语言**：中文优先
 
 ## 常用命令
 
 ```bash
 uv venv && uv sync       # 安装依赖
-uv run htmlreader        # CLI
+uv run html-reader-llm   # CLI
 uv build                 # 构建
 ```
 
@@ -20,21 +20,23 @@ uv build                 # 构建
 ```
 输入 URL/HTML
   │
-  ├─ 自定义简化流程（后续参考草稿+开源代码）─→ minify-html ─→ LLM 分析结构
+  ├─ HTML 简化（7 步流水线）─→ LLM 友好格式
   │
   ├─ 普通请求 vs 浏览器渲染 ─→ 差异度计算 + 文本统计
   │
-  ├─ httpx2 请求 ─→ LLM（页面分类 / CSS 选择器规则生成）
-  │                 └─ tranfilatura 辅助元数据提取
+  ├─ urllib3 请求 ─→ LLM（页面分类 / CSS 选择器规则生成）
+  │                 └─ trafilatura 辅助元数据提取
+  │
+  ├─ MCP Server（--mcp）─→ stdio JSON-RPC ─→ 3 个工具
   │
   └─ 自定义 CSS 提取语法 ─→ 低代码提取工作流
 ```
 
-## 设计决策（探索阶段）
+## 设计决策
 
 ### HTML 简化
+- 7 步流水线：strip noise → media placeholders → clean attrs → truncate lists → truncate text → unwrap bare → normalize whitespace
 - minify-html 是喂给 LLM 之前的最后一步压缩
-- 中间有自定义简化步骤，后续提供草稿代码 + 大量开源代码学习后确定
 
 ### 浏览器渲染判断
 - 不用框架，用 Chrome 原生 `--dump-dom` 管道获取渲染后 HTML
@@ -42,23 +44,32 @@ uv build                 # 构建
 - 关键参数：
   - `--virtual-time-budget=` 预估等待 JS 异步加载
   - `--disable-gpu`
-  - `--run-all-compositor-stages-before-draw`
-  - `--user-agent="指定的 UA"`
   - `--headless`
   - `--timeout=毫秒数`
   - `--blink-settings=imagesEnabled=false` 禁用图片减少流量
   - `--user-data-dir=` 缓存用户数据，减少重复加载
+  - `--proxy-server=` 代理
 - 纯管道模式，不走 CDP 协议（后续可扩展）
-- 渲染后 HTML 与 httpx2 结果对比，统计文本差异度
+- 渲染后 HTML 与 HTTP 结果对比，统计文本差异度
+
+### LLM 通信
+- 使用 urllib3 发送 HTTP 请求与 LLM 通信（OpenAI 兼容 API）
+- python-dotenv 加载 .env 配置
 
-### CSS 提取语法（草稿）
+### CSS 提取语法
 - 三个核心字段：
   - `selector`：CSS 选择器
   - `value_mode`：取值方式
     - `$html`：取元素内部完整 HTML
     - `$text`：取纯文本（去标签）
     - `@attribute`：取指定属性值（如 `@href`、`@src`）
-- 交互形式（YAML / 链式 API / LLM 生成）后续再定
+- 交互形式：YAML / 链式 API / LLM 生成
+
+### MCP Server
+- 入口：`uvx html-reader-llm --mcp`
+- 协议：MCP stdio（JSON-RPC 2.0）
+- 工具只接收 HTML 字符串，不发起网络请求
+- 调用方负责获取 HTML
 
 ## 核心需求
 
@@ -73,14 +84,20 @@ uv build                 # 构建
 - 输出决策：`use_browser: bool`
 
 ### 3. LLM 驱动的智能分析
-- 使用 httpx2 发送 HTTP 请求与 LLM 通信
+- 使用 urllib3 发送 HTTP 请求与 LLM 通信
 - **页面分类**：识别 `list`（列表页）/ `detail`（详情页）
 - **CSS 选择器规则生成**：
-  - list 页：提取列表规则
-  - detail 页：提取正文 + 元数据规则
-- **tranfilatura 协作**：提取元数据作为 LLM 上下文，提高选择器准确度
+  - list 页：提取列表规则（title, link, pubtime）
+  - detail 页：提取正文 + 元数据规则（title, author, date, description, image, categories, tags, content）
+- **trafilatura 协作**：提取元数据作为 LLM 上下文，提高选择器准确度
+
+### 4. MCP 工具集成
+- `simplify_html`：7 步清洗 HTML
+- `prepare_analysis`：组装 system_prompt + user_prompt（不调 LLM）
+- `validate_selectors`：校验 CSS 选择器是否有效
+- `extract_data`：用规则提取数据（detail 返回字段值，list 返回条目列表）
 
-### 4. CSS 提取语法工作流
+### 5. CSS 提取语法工作流
 - 自定义一套文本化的 CSS 提取规则语法
 - 低代码方式描述网页内容提取逻辑
 - 支持组合、嵌套、条件选择
@@ -90,9 +107,11 @@ uv build                 # 构建
 
 | 依赖 | 用途 |
 |---|---|
-| `httpx2` | 异步 HTTP 客户端，用于下载页面及 LLM API 通信 |
 | `selectolax` | 高性能 HTML 解析（基于 Modest/Lexbor） |
+| `trafilatura` | HTTP fetch + 元数据提取 |
 | `minify-html` | HTML 极致压缩，缩短 LLM 提示词长度 |
+| `python-dotenv` | 加载 .env 配置 |
+| `fastmcp-slim[server]` | MCP stdio server |
 
 ## 关键概念
 
@@ -100,3 +119,4 @@ uv build                 # 构建
 - **差异度**：普通请求与浏览器渲染结果的 DOM/文本相似度
 - **提取规则**：文本化 CSS 选择器组合，描述从 HTML 中提取目标数据的逻辑
 - **简化格式**：去除样式噪声后的 HTML，保留结构语义供 LLM 理解
+- **MCP**：Model Context Protocol，LLM 工具集成协议

html_reader_llm-0.0.3/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: html-reader-llm
+Version: 0.0.3
+Summary: HTML simplification and intelligent extraction for LLM
+Author-email: Clericpy <clericpy@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp-slim[server]>=3.4.7
+Requires-Dist: minify-html>=0.18.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: selectolax>=0.4.7
+Requires-Dist: trafilatura>=2.2.0
+
+# html-reader-llm
+
+HTML simplification and intelligent extraction for LLM.
+
+## Features
+
+- **HTML Simplification** — 7-step pipeline to clean HTML for LLM consumption
+- **Render Detection** — Compare HTTP vs Chrome to decide if browser rendering is needed
+- **LLM Analysis** — Page classification (list/detail) + CSS selector rule generation
+- **CSS Selector Validation** — Verify selectors against actual HTML
+- **MCP Server** — Expose tools to LLM agents via stdio protocol
+
+## Installation
+
+```bash
+pip install html-reader-llm
+# or
+uv tool install html-reader-llm
+```
+
+## CLI Usage
+
+```bash
+# Simplify HTML
+html-reader-llm simplify < page.html
+html-reader-llm simplify --file page.html --stats
+
+# Detect if browser rendering is needed
+html-reader-llm detect https://example.com
+html-reader-llm detect https://example.com --proxy http://127.0.0.1:7890
+
+# Full analysis with LLM
+html-reader-llm analyze https://example.com
+html-reader-llm analyze https://example.com --dry-run
+html-reader-llm analyze https://example.com --base-url https://api.openai.com/v1 --api-key sk-xxx
+
+# Fetch HTML
+html-reader-llm fetch https://example.com
+html-reader-llm fetch https://example.com --chrome
+html-reader-llm fetch https://example.com --json --detect-only
+
+# Validate CSS selectors
+html-reader-llm validate https://example.com --rules-file selectors.json
+html-reader-llm validate --html-file page.html --rules-file selectors.json --json
+```
+
+## MCP Mode
+
+Expose tools to LLM agents via stdio protocol:
+
+```bash
+# Start MCP server
+uvx html-reader-llm --mcp
+```
+
+### MCP Client Configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "html-reader-llm": {
+      "command": "uvx",
+      "args": ["html-reader-llm", "--mcp"]
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "html-reader-llm": {
+      "command": "uvx",
+      "args": ["html-reader-llm", "--mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Input | Output |
+|---|---|---|
+| `simplify_html` | `html` | Simplified HTML + per-step stats |
+| `prepare_analysis` | `html, max_tokens?` | System prompt + user prompt for LLM analysis |
+| `validate_selectors` | `html, rules` | Per-selector validation results |
+| `extract_data` | `html, rules` | Extracted data (detail) or list of items (list) |
+
+All tools accept HTML strings directly — no network calls. The caller is responsible for fetching HTML.
+
+### Agent Workflow
+
+```
+Agent fetches HTML (browser tool, curl, etc.)
+  │
+  ├─ simplify_html(html)
+  │   → Cleaned HTML for analysis
+  │
+  ├─ prepare_analysis(html)
+  │   → System prompt + user prompt
+  │   → Agent analyzes page, generates extraction rules
+  │
+  ├─ validate_selectors(html, rules)
+  │   → Verify rules work against actual HTML
+  │
+  └─ extract_data(html, rules)
+      → Get extracted content (detail values or list items)
+```
+
+## Proxy Support
+
+All network-dependent commands support `--proxy`:
+
+```bash
+html-reader-llm fetch https://example.com --proxy http://127.0.0.1:7890
+html-reader-llm detect https://example.com --proxy http://127.0.0.1:7890
+html-reader-llm analyze https://example.com --proxy http://127.0.0.1:7890
+html-reader-llm validate https://example.com --rules-file rules.json --proxy http://127.0.0.1:7890
+```
+
+## License
+
+MIT
+

html_reader_llm-0.0.3/README.md

@@ -0,0 +1,125 @@
+# html-reader-llm
+
+HTML simplification and intelligent extraction for LLM.
+
+## Features
+
+- **HTML Simplification** — 7-step pipeline to clean HTML for LLM consumption
+- **Render Detection** — Compare HTTP vs Chrome to decide if browser rendering is needed
+- **LLM Analysis** — Page classification (list/detail) + CSS selector rule generation
+- **CSS Selector Validation** — Verify selectors against actual HTML
+- **MCP Server** — Expose tools to LLM agents via stdio protocol
+
+## Installation
+
+```bash
+pip install html-reader-llm
+# or
+uv tool install html-reader-llm
+```
+
+## CLI Usage
+
+```bash
+# Simplify HTML
+html-reader-llm simplify < page.html
+html-reader-llm simplify --file page.html --stats
+
+# Detect if browser rendering is needed
+html-reader-llm detect https://example.com
+html-reader-llm detect https://example.com --proxy http://127.0.0.1:7890
+
+# Full analysis with LLM
+html-reader-llm analyze https://example.com
+html-reader-llm analyze https://example.com --dry-run
+html-reader-llm analyze https://example.com --base-url https://api.openai.com/v1 --api-key sk-xxx
+
+# Fetch HTML
+html-reader-llm fetch https://example.com
+html-reader-llm fetch https://example.com --chrome
+html-reader-llm fetch https://example.com --json --detect-only
+
+# Validate CSS selectors
+html-reader-llm validate https://example.com --rules-file selectors.json
+html-reader-llm validate --html-file page.html --rules-file selectors.json --json
+```
+
+## MCP Mode
+
+Expose tools to LLM agents via stdio protocol:
+
+```bash
+# Start MCP server
+uvx html-reader-llm --mcp
+```
+
+### MCP Client Configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "html-reader-llm": {
+      "command": "uvx",
+      "args": ["html-reader-llm", "--mcp"]
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "html-reader-llm": {
+      "command": "uvx",
+      "args": ["html-reader-llm", "--mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Input | Output |
+|---|---|---|
+| `simplify_html` | `html` | Simplified HTML + per-step stats |
+| `prepare_analysis` | `html, max_tokens?` | System prompt + user prompt for LLM analysis |
+| `validate_selectors` | `html, rules` | Per-selector validation results |
+| `extract_data` | `html, rules` | Extracted data (detail) or list of items (list) |
+
+All tools accept HTML strings directly — no network calls. The caller is responsible for fetching HTML.
+
+### Agent Workflow
+
+```
+Agent fetches HTML (browser tool, curl, etc.)
+  │
+  ├─ simplify_html(html)
+  │   → Cleaned HTML for analysis
+  │
+  ├─ prepare_analysis(html)
+  │   → System prompt + user prompt
+  │   → Agent analyzes page, generates extraction rules
+  │
+  ├─ validate_selectors(html, rules)
+  │   → Verify rules work against actual HTML
+  │
+  └─ extract_data(html, rules)
+      → Get extracted content (detail values or list items)
+```
+
+## Proxy Support
+
+All network-dependent commands support `--proxy`:
+
+```bash
+html-reader-llm fetch https://example.com --proxy http://127.0.0.1:7890
+html-reader-llm detect https://example.com --proxy http://127.0.0.1:7890
+html-reader-llm analyze https://example.com --proxy http://127.0.0.1:7890
+html-reader-llm validate https://example.com --rules-file rules.json --proxy http://127.0.0.1:7890
+```
+
+## License
+
+MIT

{html_reader_llm-0.0.2 → html_reader_llm-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "html-reader-llm"
-version = "0.0.2"
+version = "0.0.3"
 description = "HTML simplification and intelligent extraction for LLM"
 readme = "README.md"
 authors = [
@@ -8,6 +8,7 @@ authors = [
 ]
 requires-python = ">=3.12"
 dependencies = [
+    "fastmcp-slim[server]>=3.4.7",
     "minify-html>=0.18.1",
     "python-dotenv>=1.2.2",
     "selectolax>=0.4.7",

{html_reader_llm-0.0.2 → html_reader_llm-0.0.3}/src/html_reader_llm/__init__.py

@@ -19,7 +19,13 @@ from html_reader_llm.browser import (
     get_browser_path,
     validate_browser_path,
 )
-from html_reader_llm.llm import AnalysisResult, analyze_page
+from html_reader_llm.llm import (
+    AnalysisResult,
+    PreparedPrompt,
+    analyze_page,
+    prepare_analysis_from_html,
+    prepare_analysis_prompt,
+)
 from html_reader_llm.render_detect import RenderDetectResult, detect_render
 from html_reader_llm.selector_validator import SelectorValidator, validate_url_selectors
 from html_reader_llm.simplify import simplify_html
@@ -27,13 +33,23 @@ from html_reader_llm.simplify import simplify_html
 __all__ = [
     "AnalysisResult",
     "BrowserNotFoundError",
+    "PreparedPrompt",
     "RenderDetectResult",
     "SelectorValidator",
     "analyze_page",
     "detect_browser_paths",
     "detect_render",
     "get_browser_path",
+    "prepare_analysis_from_html",
+    "prepare_analysis_prompt",
     "simplify_html",
     "validate_browser_path",
     "validate_url_selectors",
 ]
+
+
+def run_mcp_server() -> None:
+    """Start the MCP stdio server for LLM tool integration."""
+    from html_reader_llm.mcp_server import run_stdio
+
+    run_stdio()

{html_reader_llm-0.0.2 → html_reader_llm-0.0.3}/src/html_reader_llm/cli.py

@@ -1,9 +1,14 @@
 """html-reader-llm — HTML simplification and intelligent extraction for LLM.
 
-Provides three subcommands:
+Provides five subcommands:
 - simplify: Clean and shorten HTML for LLM consumption
 - detect:   Compare HTTP vs Chrome rendering to decide if browser is needed
-- analyze:  Full pipeline — fetch, simplify, extract metadata, LLM classification + rules
+- analyze:  Full pipeline — fetch, simplify, metadata, LLM classification + rules
+- fetch:    Download HTML from a URL
+- validate: Validate CSS selectors against a URL or HTML file
+
+MCP mode:
+- --mcp: Start MCP stdio server (for LLM tool integration via uvx html-reader-llm --mcp)
 
 Output:
 - simplify: cleaned HTML to stdout, stats to stderr (--stats)
@@ -74,6 +79,7 @@ def cmd_detect(args: argparse.Namespace) -> None:
         url=args.url,
         chrome_path=args.chrome_path,
         user_data_dir=args.user_data_dir,
+        proxy=getattr(args, "proxy", None),
     )
 
     summary = {k: v for k, v in result.items() if k not in ("http_html", "chrome_html")}
@@ -104,6 +110,7 @@ def cmd_analyze(args: argparse.Namespace) -> None:
         api_key=args.api_key,
         model=args.model,
         use_cache=not args.no_cache,
+        proxy=getattr(args, "proxy", None),
     )
 
     output = {k: v for k, v in result.items() if k != "raw_llm_response"}
@@ -116,48 +123,40 @@ def cmd_analyze(args: argparse.Namespace) -> None:
 
 def cmd_analyze_dry_run(args: argparse.Namespace) -> None:
     """Show the prompt that would be sent to LLM, without calling LLM."""
-    from html_reader_llm import settings
-    from html_reader_llm.llm import _extract_metadata, _trim_to_budget
-    from html_reader_llm.render_detect import _fetch_http, detect_render
-    from html_reader_llm.simplify import simplify_html
+    from html_reader_llm.llm import prepare_analysis_prompt
 
-    _max_tokens = args.max_tokens or settings.LLM_MAX_TOKENS
+    proxy = getattr(args, "proxy", None)
 
-    status, raw_html = _fetch_http(args.url, use_cache=not args.no_cache)
-    if not raw_html:
-        print(f"Error: failed to fetch {args.url}", file=sys.stderr)
+    try:
+        prepared = prepare_analysis_prompt(
+            url=args.url,
+            max_tokens=args.max_tokens,
+            use_cache=not args.no_cache,
+            proxy=proxy,
+        )
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
         sys.exit(1)
 
-    render_result = detect_render(args.url, use_cache=not args.no_cache)
-    use_browser = render_result["use_browser"]
-    chrome_html = render_result["chrome_html"]
-    llm_source = chrome_html if (use_browser and chrome_html) else raw_html
-
-    metadata = _extract_metadata(raw_html)
-    simplified = simplify_html(llm_source)["html"]
-    trimmed = _trim_to_budget(simplified, _max_tokens)
-
-    meta_str = (
-        json.dumps(metadata, ensure_ascii=False, indent=2) if metadata else "None"
-    )
-    user_prompt = f"Metadata (from trafilatura):\n{meta_str}\n\nHTML:\n{trimmed}"
-
     print(f"=== Dry Run: {args.url} ===", file=sys.stderr)
     print(
-        f"use_browser={use_browser}, source={'chrome' if llm_source is chrome_html else 'http'}",
+        f"use_browser={prepared['use_browser']}, source={'chrome' if prepared['use_browser'] else 'http'}",
+        file=sys.stderr,
+    )
+    print(
+        f"raw_html={len(prepared['raw_html'])} chars",
         file=sys.stderr,
     )
     print(
-        f"raw_html={len(raw_html)} chars, simplified={len(simplified)} chars",
+        f"prompt={len(prepared['user_prompt'])} chars, est_tokens={len(prepared['user_prompt']) // 3}",
         file=sys.stderr,
     )
     print(
-        f"prompt={len(user_prompt)} chars, est_tokens={len(user_prompt) // 3}",
+        f"max_tokens={prepared['max_tokens']}, budget={prepared['max_tokens'] // 2}",
         file=sys.stderr,
     )
-    print(f"max_tokens={_max_tokens}, budget={_max_tokens // 2}", file=sys.stderr)
     print(file=sys.stderr)
-    print(user_prompt)
+    print(prepared["user_prompt"])
 
 
 def cmd_validate(args: argparse.Namespace) -> None:
@@ -175,14 +174,17 @@ def cmd_validate(args: argparse.Namespace) -> None:
     elif args.url:
         from html_reader_llm.render_detect import _fetch_chrome, _fetch_http
 
+        proxy = getattr(args, "proxy", None)
         if args.chrome:
-            html = _fetch_chrome(args.url)
+            html = _fetch_chrome(args.url, proxy=proxy)
             if not html:
                 print("Error: Chrome dump-dom failed", file=sys.stderr)
                 sys.exit(1)
             print(f"Fetched via Chrome: {len(html)} chars", file=sys.stderr)
         else:
-            status, html = _fetch_http(args.url, use_cache=not args.no_cache)
+            status, html = _fetch_http(
+                args.url, use_cache=not args.no_cache, proxy=proxy
+            )
             if not html:
                 print(f"Error: HTTP fetch failed (status={status})", file=sys.stderr)
                 sys.exit(1)
@@ -257,6 +259,7 @@ def cmd_fetch(args: argparse.Namespace) -> None:
 
     use_chrome = args.chrome is not None  # --chrome or --chrome=<path>
     chrome_path = args.chrome if use_chrome and args.chrome != "auto" else None
+    proxy = getattr(args, "proxy", None)
 
     if args.json or args.detect_only:
         # JSON mode: run full detection and output structured result
@@ -264,6 +267,7 @@ def cmd_fetch(args: argparse.Namespace) -> None:
             args.url,
             chrome_path=chrome_path,
             use_cache=not args.no_cache,
+            proxy=proxy,
         )
 
         output: dict[str, object] = {
@@ -292,7 +296,7 @@ def cmd_fetch(args: argparse.Namespace) -> None:
         print(json.dumps(output, indent=2, ensure_ascii=False))
     elif use_chrome:
         # Chrome mode (explicit --chrome)
-        html = _fetch_chrome(args.url, chrome_path=chrome_path)
+        html = _fetch_chrome(args.url, chrome_path=chrome_path, proxy=proxy)
         if not html:
             print("Error: Chrome dump-dom failed", file=sys.stderr)
             sys.exit(1)
@@ -300,7 +304,7 @@ def cmd_fetch(args: argparse.Namespace) -> None:
         print(f"Fetched via Chrome: {len(html)} chars", file=sys.stderr)
     else:
         # Default HTTP mode (trafilatura)
-        status, html = _fetch_http(args.url, use_cache=not args.no_cache)
+        status, html = _fetch_http(args.url, use_cache=not args.no_cache, proxy=proxy)
         if not html:
             print(f"Error: HTTP fetch failed (status={status})", file=sys.stderr)
             sys.exit(1)
@@ -315,6 +319,11 @@ def main() -> None:
         epilog="stdout: programmatic output (HTML/JSON). stderr: logs/diagnostics.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
+    parser.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Start MCP stdio server (for LLM tool integration)",
+    )
     sub = parser.add_subparsers(dest="command")
 
     # --- simplify ---
@@ -377,6 +386,10 @@ output: JSON to stdout:
     )
     p_detect.add_argument("--output-http", help="Save HTTP-fetched HTML to file")
     p_detect.add_argument("--output-chrome", help="Save Chrome-rendered HTML to file")
+    p_detect.add_argument(
+        "--proxy",
+        help="Proxy URL for HTTP/Chrome requests (e.g. 'http://127.0.0.1:7890')",
+    )
 
     # --- analyze ---
     p_analyze = sub.add_parser(
@@ -432,6 +445,10 @@ output: JSON to stdout:
     p_analyze.add_argument(
         "--raw", action="store_true", help="Print raw LLM response to stderr"
     )
+    p_analyze.add_argument(
+        "--proxy",
+        help="Proxy URL for HTTP/Chrome requests (e.g. 'http://127.0.0.1:7890')",
+    )
 
     # --- fetch ---
     p_fetch = sub.add_parser(
@@ -470,6 +487,10 @@ output: raw HTML to stdout (default)
         help="Custom header (repeatable), format: 'Name: Value'",
     )
     p_fetch.add_argument("--timeout", type=int, help="Request timeout in seconds")
+    p_fetch.add_argument(
+        "--proxy",
+        help="Proxy URL for HTTP/Chrome requests (e.g. 'http://127.0.0.1:7890')",
+    )
     p_fetch.add_argument(
         "--chrome",
         nargs="?",
@@ -539,9 +560,19 @@ output: validation report to stderr
     p_validate.add_argument(
         "--no-cache", action="store_true", help="Bypass HTTP response cache"
     )
+    p_validate.add_argument(
+        "--proxy",
+        help="Proxy URL for HTTP/Chrome requests (e.g. 'http://127.0.0.1:7890')",
+    )
 
     args = parser.parse_args()
 
+    if args.mcp:
+        from html_reader_llm.mcp_server import run_stdio
+
+        run_stdio()
+        return
+
     if args.command == "simplify":
         cmd_simplify(args)
     elif args.command == "detect":