url-context-mcp

An MCP (Model Context Protocol) server that fetches web pages and extracts clean, AI-usable context from them. Runs over stdio transport.

It's designed for AI agents that need to:

• Read a web page as clean markdown (no boilerplate, no nav/footer noise)
• Discover links on a page (with filters) before deciding what to fetch next
• Search pages for specific text/code without reading the whole thing
• Do all of the above in a single call

Tools

All tools accept either a `url` (server fetches it) or raw `html` (you provide the markup), so they're composable with other fetchers too.

Installation (copy-paste into your MCP client config)

{
  "mcpServers": {
    "url-context": {
      "command": "npx",
      "args": ["-y", "url-context-mcp"]
    }
  }
}

That's it. `npx -y` downloads and runs the server on first use; no separate install step needed. Requires Node.js 18+.

Why it's the best design for an AI agent

• Readability-first: defaults to Mozilla Readability extraction so the agent gets the article, not the chrome. Reduces tokens and irrelevance.
• One-call combo: `fetch_and_search` returns content + links + matches together — fewer round trips when an agent wants to "understand this page and find X on it".
• Link discovery before prefetch: `extract_links` lets an agent survey a page's destinations and pick the right one to fetch, instead of guessing or fetching everything.
• Regex search with context: agents can locate an error string, an API endpoint, a version number, etc. on a page with bounded context windows.
• No browser, no head: pure HTTP + jsdom. Fast, sandboxed, works anywhere Node runs. No Playwright/Chromium dependency bloat.
• Sane defaults + truncation: `maxChars`, `limit`, `maxMatches` keep responses bounded so context windows don't blow up.

Local development

npm install
node index.js          # run the stdio server
npm pack               # build the publishable tarball

Changelog

1.3.0

• `fetch_image`: optional compression. Oversized images can now be

shrunk to fit within `maxSizeKB` instead of being rejected. Set

`compress=true` (default false) and the image is resized to

`compressMaxWidth`×`compressMaxHeight` (defaults 1024×768, aspect

preserved) and re-encoded as JPEG (or PNG when the source has an alpha

channel or is animated), lowering `compressQuality` (1–100, default 75)

in steps of 10 until under the limit. Supports tuning via

`compressQuality`, `compressMaxWidth`, `compressMaxHeight`.

• `fetch_image`: hardened DoS guards. The response body is streamed

with a hard byte cap (applied regardless of `compress`), so chunked/

lying-header/infinite bodies can't OOM the server. Image decoding runs

with `failOn: "error"`, an explicit `limitInputPixels` (≈26 MP) and

rejects via a pre-decode dimension check, blocking decompression bombs.

The compression encode loop is bounded by iteration count (6) and a

15 s deadline.

• Server version bumps to 1.3; user-agent string updated accordingly.

1.2.0

• New tool: `fetch_image`. Resolves an image URL (absolute, or relative

to a `baseUrl`) and returns it as an MCP `image` content block (base64

with a `mimeType` derived from the response Content-Type header, falling

back to the URL extension). Lets the model actually *see* images found in

pages marked up in markdown. Optional `maxSizeKB` (default 512 KB) protects

the context window from oversized payloads. MIME fallback map covers

png/jpg/jpeg/gif/webp/svg/bmp/avif/ico.

• Server version bumps to 1.2; user-agent string updated accordingly.

1.1.0

• Preserve dropped headings in extracted content. Mozilla Readability

strips the page ``/title from its `content` on minimal pages

(e.g. `example.com`: the `# Example Domain` heading was never returned by

`fetch_url`, and `search_content` therefore couldn't find "Example

Domain"). We now detect headings present in the raw body but missing from

Readability's cleaned HTML and re-prepend them, so the page title is

always part of the returned markdown/text and is searchable.

• `search_content` raw-HTML fallback. When a search of the converted

(markdown/text) content finds zero matches and raw HTML is available,

the tool re-runs the search against the stripped raw text as a safety net.

The result flag notes when the fallback path was used (`(raw-HTML

fallback)` in the header).

• Misc: user-agent string bumped to `1.1`.

License

MIT