Why Fetch MCP needs a restart after npm fails
The Fetch MCP reference server, distributed as the Python package mcp-server-fetch, lets an AI assistant read web pages through the Model Context Protocol (MCP). It downloads HTML, extracts the main text, and returns Markdown. When Node.js is available, Fetch can use Mozilla’s Readability.js to extract that text. If the JavaScript packages are missing, the first request that needs them runs npm install to fetch them from a package registry.
The page can download successfully while the package install fails. In September 2026, contactkontey-dotcom reported running Fetch in a sandbox that could reach the target site but had no route to the npm registry. HTML conversion failed on that version. In October, the maintainers changed Fetch to fall back to its Python extractor when JavaScript setup fails. The tool can now return Markdown even after an install error. Deployment report · October fix
Restoring access to the registry does not trigger another setup attempt. Fetch remembers the failure until the server process restarts. In the fallback example below, the agent receives the words “Read the reference” but loses the URL attached to “reference.” A successful fetch can leave the agent without the link it needs to follow.
The source trace and reproductions below use mcp-server-fetch 2026.11.11, at commit e1dc4b18. The examples ran on macOS with Python 3.11.13 and the repository’s locked dependencies, including ReadabiliPy 0.3.0.
The first HTML request can start npm
The fetch tool registration accepts a URL and an optional raw boolean. With raw left at its default, false, the handler checks access, downloads the page, and passes an HTML response to extract_content_from_html. Extraction runs in a worker thread, so a slow subprocess does not occupy the server’s asynchronous request loop.
The JavaScript branch calls node_path(). On its first call, the function finds Node on PATH, the directories searched for executables, and checks its version. It then looks inside ReadabiliPy’s javascript/node_modules directory for the required packages. ReadabiliPy is the Python library supplying the extraction code and JavaScript package metadata.
When those packages are missing, the runner invokes npm install --no-audit --no-fund in that directory. The package directory must be writable, and a fresh install needs access to the registry to download packages. Installation and probe code
The runner caches the probe’s result in _node and marks _probed as true. It does that even when the result is None, meaning JavaScript extraction is unavailable. Later requests receive the cached None without checking Node or npm again. A lock prevents simultaneous first requests from each trying to install the dependencies.
That cache avoids repeatedly attempting a broken installation. It also means a repaired installation stays unused by an already-running process.
Reproduce the failed probe without a registry outage
The following experiment exercises the real readiness function with controlled stand-ins for node and npm. The fake npm initially exits unsuccessfully. Creating a marker then allows it to create the package files the readiness check expects. A second Python process represents restarting the server.
This checks setup and retry behavior; the stand-ins do not execute Readability.js or download packages. All fixture files live in a temporary directory. The example needs Git, uv, a Python environment manager, and a POSIX shell such as the one on macOS or Linux.
Install the exact source and locked Python dependencies in a scratch directory:
git clone https://github.com/modelcontextprotocol/servers.git fetch-probe
cd fetch-probe
git checkout e1dc4b18dbb948921da37f3d4224a628730b43b0
uv sync --project src/fetch --frozen --no-dev
Save this as probe.py in the checkout root. It records each subprocess invocation and prints whether the runner considers JavaScript ready:
import contextlib
import io
import os
from pathlib import Path
import subprocess
import sys
import tempfile
from unittest.mock import patch
from mcp_server_fetch import readability_js as js
def child(root, phase):
root = Path(root)
jsdir = root / "javascript"
bindir = root / "bin"
log = root / "calls"
def ready(label):
with contextlib.redirect_stderr(io.StringIO()):
available = js.node_path() is not None
calls = log.read_text().splitlines() if log.exists() else []
print(f"{label}: ready={available}, calls={calls}", flush=True)
with patch.object(js, "javascript_dir", return_value=jsdir), patch.object(
js.shutil, "which", side_effect=lambda name: str(bindir / name)
):
if phase == "first":
ready("first probe")
(jsdir / "permit-install").touch()
ready("same process after repair")
else:
ready("new process after repair")
if len(sys.argv) > 1:
child(sys.argv[1], sys.argv[2])
else:
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
(root / "bin").mkdir()
(root / "javascript").mkdir()
scripts = {
"node": 'echo node >> "$PROBE_LOG"\necho v24.0.0\n',
"npm": '''echo npm >> "$PROBE_LOG"
[ -f permit-install ] || exit 1
for name in @mozilla/readability jsdom minimist; do
mkdir -p "node_modules/$name"
echo '{}' > "node_modules/$name/package.json"
done
''',
}
for name, body in scripts.items():
path = root / "bin" / name
path.write_text("#!/bin/sh\n" + body)
path.chmod(0o700)
env = dict(os.environ, PROBE_LOG=str(root / "calls"))
for phase in ("first", "restart"):
subprocess.run(
[sys.executable, __file__, str(root), phase],
env=env,
check=True,
)
Run it with the installed environment:
src/fetch/.venv/bin/python probe.py
The observed output was:
first probe: ready=False, calls=['node', 'npm']
same process after repair: ready=False, calls=['node', 'npm']
new process after repair: ready=True, calls=['node', 'npm', 'node', 'npm']
The second line adds no subprocess calls. The environment is ready for another installation attempt, but the cached failure prevents one. Only the fresh process probes again and runs the now-successful installer. The script captures diagnostic output to keep this comparison readable; a real server writes the failure reason to standard error, its log stream.
There is a narrower boundary here than “any JavaScript error requires a restart.” Once setup succeeds, a failed extraction of one page falls back for that page. The runner keeps the successful Node path and can attempt JavaScript extraction on the next page. The persistent failure above belongs to the setup probe. Both paths are visible in extract_article.
A successful fallback can lose a link
In the source, an unavailable JavaScript extractor returns None. The caller then runs ReadabiliPy with use_readability=False and converts that result to Markdown. The tool can return the resulting content normally. A successful tool response alone therefore does not identify which extractor ran.
The Python extractor can preserve the words while dropping a link destination. Save this as fallback.py alongside probe.py to check that behavior with the same environment:
from mcp_server_fetch.server import extract_content_from_html
html = '''<html><body><article><p>
Read the <a href="https://example.com/reference">reference</a>
for a detailed explanation of this feature and its configuration.
</p></article></body></html>'''
text = extract_content_from_html(html, use_readability_js=False)
print("keeps link label:", "reference" in text)
print("keeps link URL:", "https://example.com/reference" in text)
Run the extraction directly:
src/fetch/.venv/bin/python fallback.py
It prints:
keeps link label: True
keeps link URL: False
An agent can read “reference” in this result but cannot follow the original destination from it. The upstream subprocess tests also exercise a timed-out Node process through an MCP client and check that the fallback returns successfully while omitting the link target. The local examples above isolate readiness and Python extraction; they do not compare the quality of the two extractors across websites.
Repair the environment, then restart the server process
For a deployment that needs Readability.js, install its JavaScript dependencies during environment setup, before serving requests. Use the Python environment that launches Fetch, locate ReadabiliPy’s javascript directory there, and follow the upstream preinstallation instructions. Preparing a different Python environment leaves the running server’s dependencies missing.
After repairing a failed setup, stop and start the Fetch server process through its client or process manager. Sending another prompt, retrying the URL, or reconnecting to a process that stayed alive does not clear _probed. Check the server’s standard-error log during the next HTML extraction for a setup failure or fallback message.
If Python extraction is sufficient and runtime npm access is unwanted, add --no-readability-js to the server’s launch arguments. The server then skips the Node path regardless of whether Node is installed. Verify the resulting content against pages the agent needs, especially when it must follow links.
For one request where the original markup matters, use the tool argument raw: true. That bypasses HTML simplification and returns the downloaded content, subject to the tool’s normal length limits. It also leaves the original link markup available for inspection. A server launch flag selects Python extraction for every request; raw selects unsimplified content for one request.
If a tool you build can return different content after an optional dependency fails, say which path produced the result so callers can act on it. Install dependencies during deployment where possible. If setup has to happen during a request, decide which failures are worth retrying and how long to wait before trying again.