{ "canonical_name": "vasylenko/markfetch", "compilation_id": "pack_8d2e4620b31444bb8fd36fadb9de2b1c", "created_at": "2026-05-15T08:31:11.494735+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm i -g markfetch` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm i -g markfetch", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_68d591c3193f451280c23122928ef2c6" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_f2a92ee4f0af5e4010add90875cdae99", "canonical_name": "vasylenko/markfetch", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/vasylenko/markfetch", "slug": "markfetch", "source_packet_id": "phit_a4fc82107707459d877159657cf79a72", "source_validation_id": "dval_340184719b7f4ddea815de0bc4647491" }, "merchandising": { "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户", "github_forks": 0, "github_stars": 0, "one_liner_en": "Tiny CLI and MCP server: fetch an URL -- return clean markdown. Built for AI agents.", "one_liner_zh": "Tiny CLI and MCP server: fetch an URL -- return clean markdown. Built for AI agents.", "primary_category": { "category_id": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "matched_keywords:mcp, server, github" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "markfetch", "title_zh": "markfetch 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Page Observation and Action Planning", "label_zh": "页面观察与动作规划", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-page-observation-and-action-planning", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_a4fc82107707459d877159657cf79a72", "page_model": { "artifacts": { "artifact_slug": "markfetch", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm i -g markfetch", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/vasylenko/markfetch#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "页面观察与动作规划", "评测体系" ], "eyebrow": "工具连接与集成", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要工具连接与集成能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Tiny CLI and MCP server: fetch an URL -- return clean markdown. Built for AI agents." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.1", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_749b65614f7b40e0b524f4e932cd4aca | https://github.com/vasylenko/markfetch/releases/tag/v0.4.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.4.1", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1234238440 | https://github.com/vasylenko/markfetch | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1234238440 | https://github.com/vasylenko/markfetch | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:1234238440 | https://github.com/vasylenko/markfetch | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1234238440 | https://github.com/vasylenko/markfetch | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1234238440 | https://github.com/vasylenko/markfetch | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1234238440 | https://github.com/vasylenko/markfetch | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v0.4.1。", "title": "踩坑日志" }, "snapshot": { "contributors": 1, "forks": 0, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 0 }, "source_url": "https://github.com/vasylenko/markfetch", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Tiny CLI and MCP server: fetch an URL -- return clean markdown. Built for AI agents.", "title": "markfetch 能力包", "trial_prompt": "# markfetch - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 markfetch 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Tiny CLI and MCP server: fetch an URL -- return clean markdown. Built for AI agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction。围绕“Introduction”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：Quick Start Guide。围绕“Quick Start Guide”模拟一次用户任务，不展示安装或运行结果。\n3. processing-pipeline：Processing Pipeline。围绕“Processing Pipeline”模拟一次用户任务，不展示安装或运行结果。\n4. http-fingerprinting：HTTP/2 Fingerprinting。围绕“HTTP/2 Fingerprinting”模拟一次用户任务，不展示安装或运行结果。\n5. cli-usage：CLI Usage。围绕“CLI Usage”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“Quick Start Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. processing-pipeline\n输入：用户提供的“Processing Pipeline”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. http-fingerprinting\n输入：用户提供的“HTTP/2 Fingerprinting”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. cli-usage\n输入：用户提供的“CLI Usage”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“Quick Start Guide”形成一个小中间产物，并等待用户确认。\n- Step 3 / processing-pipeline：Step 3 必须围绕“Processing Pipeline”形成一个小中间产物，并等待用户确认。\n- Step 4 / http-fingerprinting：Step 4 必须围绕“HTTP/2 Fingerprinting”形成一个小中间产物，并等待用户确认。\n- Step 5 / cli-usage：Step 5 必须围绕“CLI Usage”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/vasylenko/markfetch\n- https://github.com/vasylenko/markfetch#readme\n- README.md\n- src/index.ts\n- package.json\n- src/core.ts\n- src/cli.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 markfetch 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_release: v0.4.1（https://github.com/vasylenko/markfetch/releases/tag/v0.4.1）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_release", "source": "github", "title": "v0.4.1", "url": "https://github.com/vasylenko/markfetch/releases/tag/v0.4.1" } ], "status": "已收录 1 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "工具连接与集成", "desc": "Tiny CLI and MCP server: fetch an URL -- return clean markdown. Built for AI agents.", "effort": "安装已验证", "forks": 0, "icon": "link", "name": "markfetch 能力包", "risk": "需复核", "slug": "markfetch", "stars": 0, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "页面观察与动作规划", "评测体系" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/vasylenko/markfetch 项目说明书\n\n生成时间：2026-05-15 08:07:16 UTC\n\n## 目录\n\n- [Introduction](#introduction)\n- [Quick Start Guide](#quickstart)\n- [Processing Pipeline](#processing-pipeline)\n- [HTTP/2 Fingerprinting](#http-fingerprinting)\n- [CLI Usage](#cli-usage)\n- [MCP Server Integration](#mcp-server)\n- [Environment Variables](#environment-variables)\n- [Write Sandbox Security](#write-sandbox)\n- [Error Handling](#error-handling)\n- [Development Guide](#development)\n\n\n\n## Introduction\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quickstart), [Processing Pipeline](#processing-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/vasylenko/markfetch/blob/main/CHANGELOG.md)\n- [src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts)\n- [src/cli.ts](https://github.com/vasylenko/markfetch/blob/main/src/cli.ts)\n- [src/mcp.ts](https://github.com/vasylenko/markfetch/blob/main/src/mcp.ts)\n- [src/sandbox.ts](https://github.com/vasylenko/markfetch/blob/main/src/sandbox.ts)\n
\n\n# Introduction\n\n## What is markfetch?\n\n**markfetch** is a Node.js tool that fetches public HTTP/S URLs and returns clean, readable markdown — indistinguishable from what a human would get by running \"Save as Markdown\" in a browser. It is designed to provide high-quality content extraction for language models, with a focus on producing output that LLM clients can actually consume reliably.\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n## Core Design Philosophy\n\nmarkfetch is built around several key principles that differentiate it from generic fetching solutions:\n\n| Principle | Description |\n|-----------|-------------|\n| **Single-channel output** | Returns markdown in `content[0].text` only — no `structuredContent` that some LLM clients drop |\n| **Real-browser fingerprint** | Uses HTTP/2 transport with a coherent Chrome header set and `Sec-CH-UA-*` client hints |\n| **Reader-View extraction** | Leverages Mozilla's Readability library to extract the main article content |\n| **Zero-config defaults** | Works out of the box with sensible defaults |\n| **Deterministic errors** | 8 structured error codes for reliable error handling |\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n## Architecture Overview\n\nmarkfetch follows an adapter pattern with a unified core:\n\n```mermaid\ngraph TD\n A[User / LLM Client] --> B[Adapter Layer]\n B --> C{Invocation Mode}\n C -->|CLI args| D[cli.ts]\n C -->|MCP stdio| E[mcp.ts]\n D --> F[core.ts - fetchMarkdown]\n E --> F\n F --> G[HTTP Fetch - undici]\n G --> H[Readability Extraction]\n H --> I[Turndown Conversion]\n I --> J[Markdown Output]\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| **Core Pipeline** | `src/core.ts` | URL fetching, HTML parsing, content extraction, markdown conversion, error throwing |\n| **CLI Adapter** | `src/cli.ts` | Command-line argument parsing, stdout/stderr output |\n| **MCP Adapter** | `src/mcp.ts` | Model Context Protocol stdio server, tool registration |\n| **Write Sandbox** | `src/sandbox.ts` | Path validation for file saves |\n\n资料来源：[src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts), [src/cli.ts](https://github.com/vasylenko/markfetch/blob/main/src/cli.ts), [src/mcp.ts](https://github.com/vasylenko/markfetch/blob/main/src/mcp.ts)\n\n## Two Operating Modes\n\n### CLI Mode\n\nThe command-line interface accepts a URL and outputs markdown to stdout:\n\n```bash\nmarkfetch https://en.wikipedia.org/wiki/Markdown\n```\n\nOptions include:\n- `-o, --output ` — Save markdown to a file\n- `-V, --version` — Print version\n- `-h, --help` — Print usage\n\nThe CLI respects the same environment variables as the MCP mode and resolves relative output paths against the current working directory.\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md), [src/cli.ts](https://github.com/vasylenko/markfetch/blob/main/src/cli.ts)\n\n### MCP Mode\n\nThe Model Context Protocol server provides a single tool `fetch_markdown(url, savePath?)` for integration with LLM clients like Claude Code, Cursor, or Goose:\n\n```json\n{\n \"mcpServers\": {\n \"markfetch\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"markfetch\"]\n }\n }\n}\n```\n\nThe MCP mode has additional security features:\n- **Write sandbox**: File saves are restricted to allowed write roots\n- **Lazy loading**: The CLI adapter is never loaded in MCP mode, ensuring `console.log` is never reachable\n\n资料来源：[src/mcp.ts](https://github.com/vasylenko/markfetch/blob/main/src/mcp.ts), [src/cli.ts](https://github.com/vasylenko/markfetch/blob/main/src/cli.ts)\n\n## Content Extraction Pipeline\n\nThe markdown conversion process involves several stages:\n\n```mermaid\ngraph LR\n A[HTML Response] --> B[Decode Encoded Tags]\n B --> C[Ensure Base Href]\n C --> D[Rewrite for Readability]\n D --> E[Readability Parse]\n E --> F[Turndown Convert]\n F --> G[Prune Empty Headings]\n G --> H[Clean Markdown]\n```\n\n### Extraction Details\n\n1. **Encoded Tag Decoding**: Handles HTML entities like `<code>` in code blocks\n2. **Base Href Injection**: Ensures relative URLs become absolute using the canonical URL\n3. **Pre-processing Rewrites**: Handles footnotes, `
` elements, and MediaWiki-specific structures\n4. **Readability Parsing**: Extracts main article content using Mozilla Readability with `keepClasses: true` to preserve language hints on code blocks\n5. **Markdown Conversion**: Uses Turndown with a custom escape function to avoid noisy backslash escapes\n6. **Heading Pruning**: Removes empty headings left by stripped interactive widgets\n\n资料来源：[src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts)\n\n## Error Handling\n\nmarkfetch provides 8 deterministic error codes:\n\n| Error Code | Meaning |\n|------------|---------|\n| `network_error` | DNS, TCP, TLS failure, or unexpected fetcher error |\n| `http_error` | Non-2xx status from upstream |\n| `timeout` | Request exceeded `MARKFETCH_TIMEOUT_MS` |\n| `unsupported_content_type` | Response is not `text/html` or `application/xhtml+xml` |\n| `extraction_failed` | Readability found no article content (typical for SPAs) |\n| `too_large` | Content exceeded `MARKFETCH_MAX_BYTES` |\n| `save_failed` | File write failed (permission, missing directory) |\n| `save_forbidden` | `savePath` resolves outside allowed write roots |\n\nAll errors are thrown uniformly from `core.ts` as `MarkfetchError` and caught by adapters for translation to their respective output formats.\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `MARKFETCH_TIMEOUT_MS` | `30000` | Per-request timeout in milliseconds |\n| `MARKFETCH_MAX_BYTES` | `5000000` | Cap on response body and extracted markdown |\n| `MARKFETCH_USER_AGENT` | Chrome 130 string | Browser fingerprint; must be Chrome UA |\n| `MARKFETCH_ALLOWED_WRITE_ROOTS` | `os.tmpdir()` + `process.cwd()` | MCP-only; allowed file save paths |\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n## What markfetch Is Not\n\nUnderstanding the boundaries helps set correct expectations:\n\n| Limitation | Explanation |\n|------------|-------------|\n| **Not a crawler** | One URL in, one document out. No recursion, `robots.txt` parsing, or rate limiting. |\n| **Not authenticated** | Anonymous fetch only. Pages behind login walls return public content or `http_error`. |\n| **Not a JS renderer** | Pure client-rendered SPAs with no static HTML return `extraction_failed`. SPAs with server-rendered content will extract what they ship. |\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n## Requirements\n\n- **Node.js ≥ 24**\n- **npm** for installation\n\n## Quick Start\n\n```bash\n# Install globally\nnpm i -g markfetch\n\n# Fetch a URL\nmarkfetch https://en.wikipedia.org/wiki/Markdown\n\n# Save to file\nmarkfetch https://example.com/article -o output.md\n```\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.6.0 | 2026-05-13 | Write sandbox, `save_forbidden` error, CI matrix expansion |\n| 0.5.0 | 2026-05-12 | CLI mode with lazy-loading dispatcher |\n| 0.4.0 | 2026-05-10 | MCP server with single `fetch_markdown` tool |\n| 0.4.1 | 2026-05-11 | Bug fixes and documentation improvements |\n\n资料来源：[CHANGELOG.md](https://github.com/vasylenko/markfetch/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction](#introduction), [CLI Usage](#cli-usage), [MCP Server Integration](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n- [package.json](https://github.com/vasylenko/markfetch/blob/main/package.json)\n- [src/cli.ts](https://github.com/vasylenko/markfetch/blob/main/src/cli.ts)\n- [src/mcp.ts](https://github.com/vasylenko/markfetch/blob/main/src/mcp.ts)\n
\n\n# Quick Start Guide\n\nmarkfetch is a tool that fetches URLs and returns clean markdown output. It operates as both a CLI command and an MCP (Model Context Protocol) server, making it suitable for AI agents like Claude Code, Codex, and Gemini CLI.\n\n## Installation\n\n### Prerequisites\n\n- Node.js ≥ 24 资料来源：[package.json:8]()\n\n### CLI Installation (Global)\n\n```bash\nnpm i -g markfetch\n```\n\nAfter installation, the `markfetch` command is available globally. 资料来源：[README.md:38]()\n\n### CLI Installation (npx)\n\nFor one-off usage without global installation:\n\n```bash\nnpx -y markfetch \n```\n\n### MCP Server Setup\n\nAdd markfetch to your MCP client configuration. The setup varies by client.\n\n#### Claude Code\n\n```bash\nclaude mcp add --scope user markfetch -- npx -y markfetch\n```\n\n#### Codex\n\n```json\n{\n \"mcpServers\": {\n \"markfetch\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"markfetch\"]\n }\n }\n}\n```\n\n#### Gemini CLI\n\n```bash\ngemini mcp add -s user markfetch npx -y markfetch\n```\n\n#### Cursor / Goose / Other stdio-MCP Clients\n\n```json\n{\n \"mcpServers\": {\n \"markfetch\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"markfetch\"]\n }\n }\n}\n```\n\n资料来源：[README.md:46-69]()\n\n## CLI Usage\n\n### Basic Fetch\n\n```bash\nmarkfetch \n```\n\nThe fetched markdown is printed to stdout. 资料来源：[src/cli.ts:18]()\n\n### Save to File\n\n```bash\nmarkfetch -o \n```\n\nUse `-o` or `--output` to save markdown to a file. Relative paths resolve against the current working directory. 资料来源：[src/cli.ts:12-15]()\n\nExample:\n\n```bash\nmarkfetch https://en.wikipedia.org/wiki/Markdown -o output.md\n```\n\n### Help and Version\n\n```bash\nmarkfetch --help\nmarkfetch --version\n```\n\n## MCP Tool Usage\n\n### Tool Name\n\n`fetch_markdown`\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `url` | string | Yes | Absolute http(s) URL to fetch. The server follows redirects automatically. No authentication headers, cookies, or session state are sent. |\n| `savePath` | string | No | Absolute filesystem path. When provided, the fetched markdown is written to this path instead of returned in the response. |\n\n资料来源：[src/mcp.ts:22-33]()\n\n### Return Value\n\nThe tool returns markdown content in `content[0].text`. No `structuredContent` field is used — this ensures compatibility with MCP clients that forward only `structuredContent` to the model. 资料来源：[README.md:18-21]()\n\n## Environment Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `MARKFETCH_TIMEOUT_MS` | `30000` | Per-request timeout in milliseconds |\n| `MARKFETCH_MAX_BYTES` | `5000000` | Cap on response body and extracted markdown (5MB) |\n| `MARKFETCH_USER_AGENT` | Pinned Chrome 130 string | Override the User-Agent header. Must be a Chrome UA string. |\n| `MARKFETCH_ALLOWED_WRITE_ROOTS` | `os.tmpdir()` + `process.cwd()` | MCP-only. Colon-delimited (POSIX) or semicolon-delimited (Windows) list of absolute paths permitted for `savePath` writes. |\n\n资料来源：[README.md:99-103]()\n\n### Passing Environment Variables to MCP\n\n```json\n{\n \"mcpServers\": {\n \"markfetch\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"markfetch\"],\n \"env\": {\n \"MARKFETCH_TIMEOUT_MS\": \"60000\"\n }\n }\n }\n}\n```\n\n## Error Handling\n\nErrors are returned with deterministic codes in the format `[code] message`:\n\n| Code | Meaning |\n|------|---------|\n| `network_error` | DNS, TCP, or TLS failure |\n| `http_error` | Upstream returned a non-2xx status |\n| `timeout` | Request exceeded `MARKFETCH_TIMEOUT_MS` |\n| `unsupported_content_type` | Response was not `text/html` or `application/xhtml+xml` |\n| `extraction_failed` | Readability found no article content (typical for pure client-rendered SPAs) |\n| `too_large` | Response body or extracted markdown exceeded `MARKFETCH_MAX_BYTES` |\n| `save_failed` | `writeFile` failed (missing directory, permission denied) |\n| `save_forbidden` | `savePath` resolves outside the allowed write roots |\n\nErrors go to stderr with non-zero exit status in CLI mode. 资料来源：[README.md:72-85]()\n\n## Quick Workflow\n\n```mermaid\ngraph TD\n A[Start markfetch] --> B{Arguments provided?}\n B -->|Yes, URL argument| C[CLI Mode]\n B -->|No arguments| D[MCP Server Mode]\n C --> E[Fetch URL]\n D --> F[Wait for MCP request]\n E --> G{Output path specified?}\n F --> H[Receive fetch_markdown request]\n G -->|No| I[Print to stdout]\n G -->|Yes, -o path| J[Write to file]\n H --> I\n J --> K[Return confirmation]\n I --> L[Return markdown content]\n K --> L\n```\n\n## Use Cases\n\n| Use Case | Recommended Mode | Command/Config |\n|----------|-------------------|----------------|\n| One-time URL fetch in shell | CLI | `markfetch ` |\n| Batch processing with shell scripts | CLI + `-o` | `markfetch -o out.md` |\n| AI agent web content retrieval | MCP | Configure in client |\n| Large document bypass inline limits | MCP + `savePath` | Set `savePath` to local file |\n\n## Limitations\n\n- **Not a crawler**: No recursion, no `robots.txt` parsing. One URL in, one document out. 资料来源：[README.md:89-91]()\n- **Not authenticated**: Anonymous fetch only. Pages behind login walls return whatever the public response is. 资料来源：[README.md:93-95]()\n- **Not a JS renderer**: Pure client-rendered SPAs with no static HTML return `extraction_failed`. 资料来源：[README.md:97-99]()\n\n---\n\n\n\n## Processing Pipeline\n\n### 相关页面\n\n相关主题：[Introduction](#introduction), [HTTP/2 Fingerprinting](#http-fingerprinting), [Error Handling](#error-handling)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts)\n- [src/cli.ts](https://github.com/vasylenko/markfetch/blob/main/src/cli.ts)\n- [src/mcp.ts](https://github.com/vasylenko/markfetch/blob/main/src/mcp.ts)\n- [src/sandbox.ts](https://github.com/vasylenko/markfetch/blob/main/src/sandbox.ts)\n- [package.json](https://github.com/vasylenko/markfetch/blob/main/package.json)\n- [README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n
\n\n# Processing Pipeline\n\n## Overview\n\nThe Processing Pipeline is the core data flow engine in markfetch. It transforms raw HTML fetched from a URL into clean, readable markdown suitable for consumption by AI agents and language models. The pipeline is intentionally single-purpose — one URL in, one markdown document out — with no recursion, pagination, or client-side JavaScript rendering.\n\nThe pipeline operates identically whether invoked via CLI or MCP adapter, ensuring consistent behavior across both interfaces.\n\n资料来源：[src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts)\n\n## Architecture\n\nThe pipeline is composed of three primary stages executed sequentially:\n\n```mermaid\ngraph TD\n A[URL Input] --> B[HTTP Fetch]\n B --> C{HTML Valid?}\n C -->|No| D[Error: network_error / http_error / timeout]\n C -->|Yes| E[Content-Type Check]\n E -->|Non-HTML| F[Error: unsupported_content_type]\n E -->|HTML| G[Extract Article]\n G -->|No Content| H[Error: extraction_failed]\n G -->|Extracted| I[Convert to Markdown]\n I --> J{Size Check}\n J -->|Exceeds Limit| K[Error: too_large]\n J -->|Valid| L{Save Path?}\n L -->|Yes| M[Write to File / Error: save_forbidden / save_failed]\n L -->|No| N[Return Markdown]\n```\n\nEach stage performs validation and may abort with a deterministic error code, ensuring failures are predictable and actionable.\n\n资料来源：[src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts)\n\n## Stage 1: HTTP Fetch\n\nThe fetch stage retrieves raw HTML from the target URL using Node.js `fetch` with a real-browser fingerprint.\n\n### Transport Configuration\n\n| Setting | Value | Purpose |\n|---------|-------|---------|\n| Protocol | HTTP/2 | Modern web fingerprint |\n| User-Agent | Chrome 130 (pinned) | Realistic browser identification |\n| Client Hints | Sec-CH-UA-* headers | Derived from User-Agent at startup |\n| Timeout | `MARKFETCH_TIMEOUT_MS` (default: 30000ms) | Per-request budget |\n\nThe User-Agent string is validated at startup. Non-Chrome strings fail fast to prevent fingerprint inconsistencies that could trigger bot detection.\n\n资料来源：[README.md](https://github.com/vasylenko/markfetch/blob/main/README.md)\n\n### Error Conditions\n\n| Code | Trigger |\n|------|---------|\n| `network_error` | DNS failure, TCP failure, TLS error, unexpected fetcher error |\n| `http_error` | Non-2xx HTTP status code |\n| `timeout` | Response exceeds `MARKFETCH_TIMEOUT_MS` |\n\nRedirects are followed automatically by the underlying HTTP client.\n\n## Stage 2: Article Extraction\n\nArticle extraction identifies and isolates the main content from the fetched HTML, stripping navigation, sidebars, footers, and other boilerplate.\n\n### Technology Stack\n\n| Component | Library | Purpose |\n|-----------|---------|---------|\n| HTML Parser | `linkedom` | Parses HTML into a DOM-like structure |\n| Extraction | `readability` (Mozilla) | Identifies main article content |\n| Configuration | `keepClasses: true` | Preserves code block language hints |\n\nThe `linkedom` parser is chosen over native `DOMParser` to ensure consistent behavior across Node.js versions and environments.\n\n资料来源：[src/core.ts](https://github.com/vasylenko/markfetch/blob/main/src/core.ts)\n\n### Pre-Extraction Rewrites\n\nBefore Readability processes the document, the pipeline applies targeted HTML rewrites to normalize content and improve extraction quality:\n\n```typescript\nfunction rewriteForReadability(document: Document): void {\n // Normalize code blocks (pre and code elements)\n // Convert aside elements to sections\n // Expand details/summary elements\n // Flatten MediaWiki heading wrappers\n}\n```\n\nSpecific transformations include:\n\n| Transform | Target | Action |\n|-----------|--------|--------|\n| Code block normalization | `
`, `` | Standardize encoding artifacts |\n| Base href injection | `` / `` | Ensure absolute URLs after redirects |\n| Aside conversion | `