npm - @j0hanz/fetch-url-mcp - Versions diffs - 0.0.1 → 1.0.0 - Mend

@j0hanz/fetch-url-mcp 0.0.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,38 +1,30 @@
-<!-- markdownlint-disable MD033 -->
 # Fetch URL MCP Server
-<img src="assets/logo.svg" alt="Fetch URL MCP Logo" width="300">
-[![npm version](https://img.shields.io/npm/v/%40j0hanz%2Ffetch-url-mcp)](https://www.npmjs.com/package/@j0hanz/fetch-url-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.26-purple)](https://modelcontextprotocol.io)
+[![npm version](https://img.shields.io/npm/v/%40j0hanz%2Ffetch-url-mcp)](https://www.npmjs.com/package/@j0hanz/fetch-url-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/node-%3E%3D24-3c873a)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.26-7c3aed)](https://modelcontextprotocol.io)
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0078d7?logo=visual-studio-code&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22fetch-url-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffetch-url-mcp%40latest%22%2C%22--stdio%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?logo=visual-studio-code&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22fetch-url-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffetch-url-mcp%40latest%22%2C%22--stdio%22%5D%7D) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install-f97316?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=fetch-url-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmV0Y2gtdXJsLW1jcEBsYXRlc3QiLCItLXN0ZGlvIl19)
-Fetch and convert public web content to clean Markdown both readable by humans and optimized for LLM context.
+Fetch public web pages and convert them into clean, AI-readable Markdown.
 ## Overview
-Fetch URL is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that fetches public web pages, extracts meaningful content using Mozilla's Readability algorithm, and converts the result into clean Markdown optimized for LLM context windows. It handles noise removal, caching, SSRF protection, async task execution, and supports both stdio and Streamable HTTP transports.
+Fetch URL is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that fetches public web pages, extracts meaningful content using Mozilla's Readability algorithm, and converts the result into clean Markdown optimized for LLM context windows. It handles noise removal, caching, SSRF protection, async task execution, and supports both **stdio** and **Streamable HTTP** transports.
-## Key Features
+> [!NOTE]
+> Content extraction quality varies depending on the HTML structure and complexity of the source page. Fetch URL works best with standard article and documentation layouts. Pages relying on client-side JavaScript rendering may yield incomplete results.
-- HTML to Markdown using Mozilla Readability + node-html-markdown.
-- Raw content URL rewriting for GitHub, GitLab, Bitbucket, and Gist.
-- In-memory LRU cache for faster repeat fetches.
-- Stdio or Streamable HTTP transport with session management.
-- SSRF protections: blocked private IP ranges and internal hostnames.
+## Key Features
-> **Note:** Content extraction quality varies depending on the HTML structure and
-> complexity of the source page. Fetch URL works best with standard article and
-> documentation layouts. Always verify the fetched content to ensure it meets
-> your expectations, as some pages may require manual adjustment or alternative
-> approaches.
+- **HTML to Markdown** — Content extraction via Mozilla Readability + node-html-markdown
+- **Noise removal** — Strips navigation, ads, cookie banners, and other non-content elements
+- **In-memory LRU cache** — Faster repeat fetches with configurable TTL (24 h default)
+- **Raw URL rewriting** — Auto-converts GitHub, GitLab, Bitbucket, and Gist URLs to raw content endpoints
 ## Tech Stack
 | Component           | Technology                          |
 | ------------------- | ----------------------------------- |
-| Runtime             | Node.js ≥ 24                        |
+| Runtime             | Node.js >= 24                       |
 | Language            | TypeScript 5.9                      |
 | MCP SDK             | `@modelcontextprotocol/sdk` ^1.26.0 |
 | Content Extraction  | `@mozilla/readability` ^0.6.0       |
@@ -50,51 +42,31 @@ URL → Validate → DNS Preflight → HTTP Fetch → Decompress
 ```
 1. **URL Validation** — Normalize, block private hosts, transform raw-content URLs (GitHub, GitLab, Bitbucket)
-2. **Fetch** — HTTP request via `undici` with redirect following, DNS preflight SSRF checks, and size limits
+2. **Fetch** — HTTP request with redirect following, DNS preflight SSRF checks, and size limits (10 MB)
 3. **Transform** — Offloaded to worker threads: parse HTML with `linkedom`, extract with Readability, remove DOM noise, convert to Markdown
-4. **Cleanup** — Multi-pass Markdown normalization (heading promotion, spacing, skip-link removal, TypeDoc comment stripping)
-5. **Cache + Respond** — Store result, apply inline content limits, return structured content
+4. **Cleanup** — Multi-pass Markdown normalization (heading promotion, spacing, skip-link removal)
+5. **Cache + Respond** — Store result in LRU cache, apply inline content limits, return structured content
 ## Repository Structure
 ```text
 fetch-url-mcp/
-├── assets/
-│   └── logo.svg
-├── scripts/
-│   ├── tasks.mjs
-│   └── validate-fetch.mjs
+├── assets/              # Server icon (logo.svg)
+├── scripts/             # Build & test orchestration
 ├── src/
-│   ├── workers/
-│   │   ├── transform-child.ts
-│   │   └── transform-worker.ts
-│   ├── cache.ts
-│   ├── config.ts
-│   ├── crypto.ts
-│   ├── dom-noise-removal.ts
-│   ├── errors.ts
-│   ├── fetch.ts
-│   ├── host-normalization.ts
-│   ├── http-native.ts
-│   ├── index.ts
-│   ├── instructions.md
-│   ├── ip-blocklist.ts
-│   ├── json.ts
-│   ├── language-detection.ts
-│   ├── markdown-cleanup.ts
-│   ├── mcp-validator.ts
-│   ├── mcp.ts
-│   ├── observability.ts
-│   ├── server-tuning.ts
-│   ├── session.ts
-│   ├── tasks.ts
-│   ├── timer-utils.ts
-│   ├── tools.ts
-│   ├── transform-types.ts
-│   ├── transform.ts
-│   └── type-guards.ts
-├── tests/
-│   └── *.test.ts
+│   ├── workers/         # Worker-thread child for HTML transforms
+│   ├── index.ts         # CLI entrypoint, transport wiring, shutdown
+│   ├── server.ts        # McpServer lifecycle and registration
+│   ├── tools.ts         # fetch-url tool definition and pipeline
+│   ├── fetch.ts         # URL normalization, SSRF, HTTP fetch
+│   ├── transform.ts     # HTML-to-Markdown pipeline, worker pool
+│   ├── config.ts        # Env-driven configuration
+│   ├── resources.ts     # MCP resource/template registration
+│   ├── prompts.ts       # MCP prompt registration (get-help)
+│   ├── mcp.ts           # Task execution management
+│   ├── http-native.ts   # Streamable HTTP server, auth, sessions
+│   └── instructions.md  # Server instructions embedded at runtime
+├── tests/               # Unit/integration tests (Node.js test runner)
 ├── package.json
 ├── tsconfig.json
 └── AGENTS.md
@@ -102,7 +74,7 @@ fetch-url-mcp/
 ## Requirements
-- **Node.js** ≥ 24
+- **Node.js** >= 24
 ## Quickstart
@@ -150,6 +122,12 @@ npm run build
 node dist/index.js --stdio
 ```
+### Docker
+```bash
+docker compose up --build
+```
 ## Configuration
 ### Runtime Modes
@@ -166,18 +144,23 @@ When no `--stdio` flag is passed, the server starts in **HTTP mode** (Streamable
 #### Core Settings
-| Variable              | Default                   | Description                                            |
-| --------------------- | ------------------------- | ------------------------------------------------------ |
-| `HOST`                | `127.0.0.1`               | HTTP server bind address                               |
-| `PORT`                | `3000`                    | HTTP server port (1024–65535)                          |
-| `LOG_LEVEL`           | `info`                    | Log level: `debug`, `info`, `warn`, `error`            |
-| `FETCH_TIMEOUT_MS`    | `15000`                   | HTTP fetch timeout in ms (1000–60000)                  |
-| `CACHE_ENABLED`       | `true`                    | Enable/disable in-memory content cache                 |
-| `USER_AGENT`          | `fetch-url-mcp/{version}` | Custom User-Agent header                               |
-| `ALLOW_REMOTE`        | `false`                   | Allow remote connections in HTTP mode                  |
-| `ALLOWED_HOSTS`       | _(empty)_                 | Comma-separated host/origin allowlist for HTTP mode    |
-| `TASKS_MAX_TOTAL`     | `5000`                    | Maximum retained task records across all owners        |
-| `TASKS_MAX_PER_OWNER` | `1000`                    | Maximum retained task records per session/client/token |
+| Variable           | Default                   | Description                                         |
+| ------------------ | ------------------------- | --------------------------------------------------- |
+| `HOST`             | `127.0.0.1`               | HTTP server bind address                            |
+| `PORT`             | `3000`                    | HTTP server port (1024–65535)                       |
+| `LOG_LEVEL`        | `info`                    | Log level: `debug`, `info`, `warn`, `error`         |
+| `FETCH_TIMEOUT_MS` | `15000`                   | HTTP fetch timeout in ms (1000–60000)               |
+| `CACHE_ENABLED`    | `true`                    | Enable/disable in-memory content cache              |
+| `USER_AGENT`       | `fetch-url-mcp/{version}` | Custom User-Agent header                            |
+| `ALLOW_REMOTE`     | `false`                   | Allow remote connections in HTTP mode               |
+| `ALLOWED_HOSTS`    | _(empty)_                 | Comma-separated host/origin allowlist for HTTP mode |
+#### Task Management
+| Variable              | Default | Description                                      |
+| --------------------- | ------- | ------------------------------------------------ |
+| `TASKS_MAX_TOTAL`     | `5000`  | Maximum retained task records across all owners  |
+| `TASKS_MAX_PER_OWNER` | `1000`  | Maximum retained task records per session/client |
 #### Authentication (HTTP Mode)
@@ -282,6 +265,7 @@ Fetches a webpage and converts it to clean Markdown format optimized for LLM con
 **Limitations:**
 - Does not execute complex client-side JavaScript interactions
+- Inline output may be truncated when `MAX_INLINE_CONTENT_CHARS` is set
 ##### Parameters
@@ -297,31 +281,43 @@ Fetches a webpage and converts it to clean Markdown format optimized for LLM con
 ```json
 {
   "url": "https://example.com",
+  "inputUrl": "https://example.com",
   "resolvedUrl": "https://example.com",
   "finalUrl": "https://example.com",
-  "inputUrl": "https://example.com",
   "title": "Example Domain",
+  "metadata": {
+    "title": "Example Domain",
+    "description": "...",
+    "author": "...",
+    "image": "...",
+    "favicon": "...",
+    "publishedAt": "...",
+    "modifiedAt": "..."
+  },
   "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
+  "fromCache": false,
+  "fetchedAt": "2026-02-11T12:00:00.000Z",
+  "contentSize": 1234,
   "truncated": false
 }
 ```
-| Field         | Type       | Description                                        |
-| ------------- | ---------- | -------------------------------------------------- |
-| `url`         | `string`   | The canonical URL (pre-raw-transform)              |
-| `inputUrl`    | `string`   | The original URL provided by the caller            |
-| `resolvedUrl` | `string`   | The normalized/transformed URL that was fetched    |
-| `finalUrl`    | `string?`  | Final response URL after redirects                 |
-| `title`       | `string?`  | Extracted page title                               |
-| `metadata`    | `object?`  | Extracted metadata (title, description, author...) |
-| `markdown`    | `string?`  | Extracted content in Markdown format               |
-| `fromCache`   | `boolean?` | Whether the response was served from cache         |
-| `fetchedAt`   | `string?`  | ISO timestamp for fetch/cache retrieval            |
-| `contentSize` | `number?`  | Full markdown size before inline truncation        |
-| `truncated`   | `boolean?` | Whether inline markdown was truncated              |
-| `error`       | `string?`  | Error message if the request failed                |
-| `statusCode`  | `number?`  | HTTP status code for failed requests               |
-| `details`     | `object?`  | Additional error details                           |
+| Field         | Type       | Description                                                                              |
+| ------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| `url`         | `string`   | The canonical URL (pre-raw-transform)                                                    |
+| `inputUrl`    | `string?`  | The original URL provided by the caller                                                  |
+| `resolvedUrl` | `string?`  | The normalized/transformed URL that was fetched                                          |
+| `finalUrl`    | `string?`  | Final response URL after redirects                                                       |
+| `title`       | `string?`  | Extracted page title                                                                     |
+| `metadata`    | `object?`  | Extracted metadata (title, description, author, image, favicon, publishedAt, modifiedAt) |
+| `markdown`    | `string?`  | Extracted content in Markdown format                                                     |
+| `fromCache`   | `boolean?` | Whether the response was served from cache                                               |
+| `fetchedAt`   | `string?`  | ISO timestamp for fetch/cache retrieval                                                  |
+| `contentSize` | `number?`  | Full markdown size before inline truncation                                              |
+| `truncated`   | `boolean?` | Whether inline markdown was truncated                                                    |
+| `error`       | `string?`  | Error message if the request failed                                                      |
+| `statusCode`  | `number?`  | HTTP status code for failed requests                                                     |
+| `details`     | `object?`  | Additional error details                                                                 |
 ##### Annotations
@@ -334,7 +330,7 @@ Fetches a webpage and converts it to clean Markdown format optimized for LLM con
 ##### Async Task Execution
-The `fetch-url` tool supports optional async task execution. Include a `task` field in the tool call to run the fetch in the background:
+The `fetch-url` tool supports optional async task execution (`execution.taskSupport: "optional"`). Include a `task` field in the tool call to run the fetch in the background:
 ```json
 {
@@ -351,9 +347,9 @@ Then poll `tasks/get` until the task status is `completed` or `failed`, and retr
 ### Prompts
-| Name       | Description                                      |
-| ---------- | ------------------------------------------------ |
-| `get-help` | Returns server usage guidance and workflow hints |
+| Name       | Description                       |
+| ---------- | --------------------------------- |
+| `get-help` | Returns server usage instructions |
 ### Resources
@@ -362,12 +358,6 @@ Then poll `tasks/get` until the task status is `completed` or `failed`, and retr
 | `internal://instructions`             | `text/markdown` | Server instructions and usage guidance               |
 | `internal://cache/{namespace}/{hash}` | `text/markdown` | Cached markdown entries from prior `fetch-url` calls |
-### Completions
-- `completion/complete` supports `internal://cache/{namespace}/{hash}` template variables:
-  - `namespace`
-  - `hash` (optionally filtered by `context.arguments.namespace`)
 ### Tasks
 The server declares full MCP task support:
@@ -479,6 +469,37 @@ Add to your Windsurf MCP configuration:
 </details>
+<details>
+<summary>Docker</summary>
+Use the published image from GitHub Container Registry:
+```json
+{
+  "mcpServers": {
+    "fetch-url-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "ghcr.io/j0hanz/fetch-url-mcp:latest",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+Or build and run locally:
+```bash
+docker build -t fetch-url-mcp .
+docker run -i --rm fetch-url-mcp --stdio
+```
+</details>
 ## Security
 ### SSRF Protection
@@ -486,7 +507,7 @@ Add to your Windsurf MCP configuration:
 Fetch URL blocks requests to private and internal network addresses:
 - **Blocked hosts**: `localhost`, `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `100.64.0.0/10`
-- **Blocked IPv6**: `::1`, `fc00::/7`, `fe80::/10`, IPv4-mapped private addresses (`::ffff:10.*`, etc.)
+- **Blocked IPv6**: `::1`, `fc00::/7`, `fe80::/10`, IPv4-mapped private addresses
 - **Cloud metadata**: `169.254.169.254` (AWS), `metadata.google.internal`, `metadata.azure.com`, `100.100.100.200` (Azure IMDS)
 DNS preflight checks run on every redirect hop to prevent DNS rebinding attacks.
@@ -532,12 +553,12 @@ npm install
 ## Build and Release
 ```bash
-npm run build        # Clean → Compile → Copy Assets → chmod
+npm run build           # Clean → Compile → Copy Assets → chmod
 npm run prepublishOnly  # Lint → Type-Check → Build
-npm publish          # Publish to npm
+npm publish             # Publish to npm
 ```
-The `prepare` script runs `npm run build` automatically on `npm install` from source.
+CI/CD is handled via a GitHub Actions workflow (`release.yml`) that runs lint, type-check, test, build, and publishes to npm with version bumping.
 ## Troubleshooting
@@ -549,17 +570,15 @@ Use the built-in inspector to test the server interactively:
 npm run inspector
 ```
-This builds the project and launches `@modelcontextprotocol/inspector` pointing to the compiled server.
 ### Common Issues
-| Issue                     | Solution                                                                                                    |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `VALIDATION_ERROR` on URL | URL is blocked (private IP/localhost) or malformed. Do not retry.                                           |
-| `queue_full` error        | Usually auto-handled by worker fallback to in-process transform; if surfaced, retry or use async task mode. |
-| Garbled output            | Binary content (images, PDFs) cannot be converted. Ensure the URL serves HTML.                              |
-| No output in stdio mode   | Ensure `--stdio` flag is passed. Without it, the server starts in HTTP mode.                                |
-| Auth errors in HTTP mode  | Set `ACCESS_TOKENS` or `API_KEY` env var and pass as `Authorization: Bearer <token>`.                       |
+| Issue                     | Solution                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `VALIDATION_ERROR` on URL | URL is blocked (private IP/localhost) or malformed. Do not retry.                     |
+| `queue_full` error        | Worker pool busy. Wait briefly, then retry or use async task mode.                    |
+| Garbled output            | Binary content (images, PDFs) cannot be converted. Ensure the URL serves HTML.        |
+| No output in stdio mode   | Ensure `--stdio` flag is passed. Without it, the server starts in HTTP mode.          |
+| Auth errors in HTTP mode  | Set `ACCESS_TOKENS` or `API_KEY` env var and pass as `Authorization: Bearer <token>`. |
 ### Stdout / Stderr Guidance

package/dist/AGENTS.md CHANGED Viewed

@@ -4,112 +4,147 @@
 ## 1) Project Context
-- **Domain:** MCP (Model Context Protocol) server that fetches web pages and converts HTML to clean, AI-readable Markdown.
+- **Domain:** MCP (Model Context Protocol) server that fetches public web pages and converts HTML into clean, AI-readable Markdown — published as `@j0hanz/fetch-url-mcp` on npm and `io.github.j0hanz/fetch-url-mcp` on the MCP Registry (see `server.json`, `package.json`).
 - **Tech Stack (Verified):**
-  - **Languages:** TypeScript 5.9+ (`package.json` → `"typescript": "^5.9.3"`), ESM (`"type": "module"`)
-  - **Frameworks:** `@modelcontextprotocol/sdk` v1.x (`"^1.26.0"` in `package.json`), Node.js ≥24 (`engines`)
+  - **Language:** TypeScript 5.9+ (see `package.json` `devDependencies`, `tsconfig.json` strict config)
+  - **Runtime:** Node.js >= 24 (see `package.json` `engines`, `.github/workflows/release.yml`)
+  - **Framework:** `@modelcontextprotocol/sdk` ^1.26.0 — MCP server SDK v1.x (see `package.json` `dependencies`)
   - **Key Libraries:**
-    - `zod` v4 (`"^4.3.6"`) — input/output schema validation
-    - `@mozilla/readability` (`"^0.6.0"`) — article extraction
-    - `linkedom` (`"^0.18.12"`) — DOM parsing (no browser required)
-    - `node-html-markdown` (`"^2.0.0"`) — HTML→Markdown conversion
-- **Architecture:** Single-package MCP server with modular source files (one concern per file). Supports both **stdio** and **Streamable HTTP** transports. Features an in-memory cache, task API, worker pool for transforms, IP blocklist, session management, and OAuth/static-token auth.
+    - `zod` ^4.3.6 — input/output schema validation (see `package.json`)
+    - `@mozilla/readability` ^0.6.0 — content extraction (see `package.json`)
+    - `linkedom` ^0.18.12 — server-side DOM (see `package.json`)
+    - `node-html-markdown` ^2.0.0 — HTML-to-Markdown conversion (see `package.json`)
+- **Architecture:** Single-package MCP server exposing `fetch-url` tool via **stdio** (default) and **Streamable HTTP** transports. Entrypoint at `src/index.ts` wires CLI parsing, signal handlers, and transport selection. Server lifecycle managed in `src/server.ts` with tool registration in `src/tools.ts`. HTML fetching, URL normalization, and security (IP blocklist, SSRF protection) in `src/fetch.ts`. HTML → Markdown transformation optionally offloaded to a worker-thread pool (`src/workers/`). In-memory LRU caching in `src/cache.ts`.
 ## 2) Repository Map (High-Level)
-- `src/` — All production TypeScript source
-  - `index.ts` — CLI entrypoint (shebang, arg parsing, transport selection, shutdown)
-  - `mcp.ts` — McpServer creation, resource/tool registration, task handlers
-  - `tools.ts` — `fetch-url` tool definition, pipeline, error mapping, progress reporting
-  - `http-native.ts` — Streamable HTTP server (sessions, auth, health endpoint)
-  - `config.ts` — Centralized env-based configuration (all settings)
-  - `fetch.ts` — URL normalization, HTTP fetching
-  - `transform.ts` / `workers/` — HTML→Markdown transform with worker pool
-  - `cache.ts` — In-memory content cache
-  - `errors.ts` — `FetchError`, `getErrorMessage`, error helpers
-  - `session.ts` — HTTP session store and lifecycle
-  - `ip-blocklist.ts` — Private/metadata IP blocking
-  - `observability.ts` — Structured logging with request context
-- `tests/` — All test files (`*.test.ts`), run against compiled `dist/`
-- `scripts/` — Build orchestration (`tasks.mjs`), validation scripts
-- `assets/` — Static assets (logo SVG)
-- `.github/workflows/` — CI/CD (publish to npm on release)
-- `.github/instructions/` — Agent instruction files for MCP server conventions
-> Ignore: `dist/`, `node_modules/`, `.tsbuildinfo`
+- `src/` — TypeScript source (compiled to `dist/`); flat module structure, no subdirectories except `workers/` (see `tsconfig.json` `rootDir`)
+  - `src/index.ts` — CLI entrypoint with shebang, transport wiring, shutdown handlers
+  - `src/server.ts` — `McpServer` lifecycle: capabilities, icons, instructions, registration
+  - `src/tools.ts` — `fetch-url` tool definition, input/output schemas, fetch pipeline, progress reporting, inline truncation
+  - `src/fetch.ts` — URL normalization, SSRF protection, DNS validation, streaming HTTP fetch, raw-URL transforms (GitHub/GitLab/Bitbucket)
+  - `src/transform.ts` — HTML-to-Markdown pipeline, worker-pool management
+  - `src/workers/` — Worker-thread child for off-main-thread HTML transforms
+  - `src/config.ts` — Centralized env-driven configuration
+  - `src/errors.ts` — Error helpers (`FetchError`, `getErrorMessage`)
+  - `src/mcp.ts` — MCP protocol handlers, task execution management
+  - `src/resources.ts` — MCP resource/template registration (cache snapshots, instructions)
+  - `src/prompts.ts` — MCP prompt registration (`get-help`)
+  - `src/instructions.md` — Server instructions embedded at runtime
+- `tests/` — Unit/integration tests (46+ test files) using Node.js built-in test runner
+- `scripts/` — Build & test orchestration (`tasks.mjs`)
+- `assets/` — Server icon (`logo.svg`)
+- `.github/workflows/` — CI/CD (`release.yml`: lint → type-check → test → build → publish to npm, MCP Registry, Docker)
+> Ignore: `dist/`, `node_modules/`, `coverage/`, `.cache/`, `.tsbuildinfo`
 ## 3) Operational Commands (Verified)
-- **Environment:** Node.js ≥24, npm
-- **Install:** `npm ci` (CI from `publish.yml`) or `npm install`
-- **Dev:** `npm run dev` (tsc watch) / `npm run dev:run` (run with .env + watch)
-- **Build:** `npm run build` (clean → compile → validate instructions → copy assets → chmod; via `scripts/tasks.mjs`)
-- **Test:** `npm test` (builds first, then runs `node --test` on `tests/**/*.test.ts` against compiled `dist/`)
-- **Type-check:** `npm run type-check` (tsc --noEmit)
-- **Lint:** `npm run lint` (ESLint) / `npm run lint:fix`
-- **Format:** `npm run format` (Prettier)
-- **Dead code:** `npm run knip` / `npm run knip:fix`
-- **Inspector:** `npm run inspector` (build + launch MCP Inspector on stdio)
+All commands verified from `.github/workflows/release.yml` (CI) and `package.json` scripts.
+- **Environment:** Node.js >= 24 with npm; no additional runtime managers required (see `package.json` `engines`, `Dockerfile`)
+- **Install:** `npm ci` (see `.github/workflows/release.yml` "Install & validate" step)
+- **Dev:** `npm run dev` → `tsc --watch --preserveWatchOutput` (see `package.json`)
+- **Dev (run):** `npm run dev:run` → `node --env-file=.env --watch dist/index.js` (see `package.json`)
+- **Start:** `npm run start` → `node dist/index.js` (see `package.json`)
+- **Build:** `npm run build` → `node scripts/tasks.mjs build` — cleans `dist/`, compiles TS, validates `instructions.md`, copies assets, sets executable bit (see `scripts/tasks.mjs`, `package.json`)
+- **Type-check:** `npm run type-check` → `tsc -p tsconfig.json --noEmit` (see `scripts/tasks.mjs`, `.github/workflows/release.yml`)
+- **Lint:** `npm run lint` → `eslint .` (see `package.json`, `.github/workflows/release.yml`)
+- **Lint (fix):** `npm run lint:fix` → `eslint . --fix` (see `package.json`)
+- **Format:** `npm run format` → `prettier --write .` (see `package.json`)
+- **Test:** `npm run test` → `node scripts/tasks.mjs test` — builds first, then runs `node --test` on `tests/**/*.test.ts` (see `scripts/tasks.mjs`, `.github/workflows/release.yml`)
+- **Test (coverage):** `npm run test:coverage` (see `package.json`)
+- **Inspector:** `npm run inspector` → builds then launches MCP Inspector on stdio (see `package.json`)
+- **Dead code:** `npm run knip` / `npm run knip:fix` (see `package.json`)
+- **Docker:** `docker compose up --build` (see `docker-compose.yml`, `Dockerfile`)
 ## 4) Coding Standards (Style & Patterns)
-- **Naming:** `camelCase` for variables/functions, `PascalCase` for types/classes/enums, `UPPER_CASE` for constants. Enforced via `@typescript-eslint/naming-convention` in `eslint.config.mjs`.
-- **Imports:**
-  - **Type-only imports required:** `import type { X }` / `import { type X }` (ESLint `consistent-type-imports` rule: error)
-  - **Named exports only:** no default exports
-  - `.js` extensions in local imports (NodeNext module resolution)
-  - Sorted by `@trivago/prettier-plugin-sort-imports`
-  - Unused imports are errors (`eslint-plugin-unused-imports`)
-- **TypeScript Strictness** (all enabled in `tsconfig.json`):
-  - `strict`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `isolatedModules`
-  - `exactOptionalPropertyTypes`, `noImplicitOverride`, `noImplicitReturns`, `noFallthroughCasesInSwitch`
-- **Explicit return types** required on functions (`explicit-function-return-type`: error)
-- **No `any`:** `@typescript-eslint/no-explicit-any`: error
-- **Schemas:** Use `z.strictObject()` for all Zod schemas; add `.describe()` to every parameter; add bounds (`.min()`/`.max()`)
-- **Tool pattern:** One MCP tool per registration; return both `content` (JSON stringified text block) and `structuredContent`; use `isError: true` on failure (never throw uncaught)
-- **Error handling:** Prefer tool execution errors over protocol errors; centralized via `getErrorMessage()`, `createToolErrorResponse()`, `handleToolError()` in `errors.ts`/`tools.ts`
-- **Logging:** Never write to `stdout` in stdio mode; use `logInfo`/`logError`/`logWarn`/`logDebug` from `observability.ts` (writes to stderr)
-- **Patterns Observed:**
-  - Configuration via environment variables, parsed once at import in `config.ts`
-  - Worker pool pattern for CPU-bound transforms (`src/workers/`, `src/transform.ts`)
-  - Inline content truncation with safe code-fence closing (`tools.ts`)
-  - Session-scoped task ownership for async tool execution (`mcp.ts`)
+### Naming (see `eslint.config.mjs` `@typescript-eslint/naming-convention`)
+- **Default:** `camelCase` (leading `_` allowed)
+- **Variables:** `camelCase`, `UPPER_CASE`, or `PascalCase`
+- **Types/Interfaces:** `PascalCase`
+- **Enum members:** `PascalCase` or `UPPER_CASE`
+- **Properties:** unrestricted format
+- **Imports:** `camelCase` or `PascalCase`
+### Structure
+- **Module system:** ESM (`"type": "module"` in `package.json`); use `.js` extensions in local imports (see `tsconfig.json` `module: "NodeNext"`, `.github/instructions/typescript-mcp-server.instructions.md`)
+- **Exports:** Named exports only — no default exports (see `.github/instructions/typescript-mcp-server.instructions.md`)
+- **Imports:** Type-only imports required (`import type { X }` / `import { type X }`) — enforced by `@typescript-eslint/consistent-type-imports` (see `eslint.config.mjs`)
+- **Import order:** Automated via `@trivago/prettier-plugin-sort-imports` — `node:` → third-party → `@modelcontextprotocol` → `@mozilla` → local by layer (see `.prettierrc`)
+- **No unused imports:** Enforced by `eslint-plugin-unused-imports` (see `eslint.config.mjs`)
+### Typing/Strictness (see `tsconfig.json`)
+- `strict: true`
+- `noUncheckedIndexedAccess: true`
+- `exactOptionalPropertyTypes: true`
+- `verbatimModuleSyntax: true`
+- `isolatedModules: true`
+- `noImplicitReturns: true`
+- `noFallthroughCasesInSwitch: true`
+- `useUnknownInCatchVariables: true`
+- ESLint extends `tseslint.configs.strictTypeChecked` + `stylisticTypeChecked` (see `eslint.config.mjs`)
+### Formatting (see `.prettierrc`)
+- 2-space indent, no tabs
+- Single quotes, semicolons, trailing commas (`es5`)
+- Print width: 80
+- LF line endings
+- Arrow parens: always
+### Patterns Observed
+- **Zod v4 strict schemas** for all tool inputs/outputs with `.describe()`, `.min()`/`.max()`, `z.strictObject()` (observed in `src/tools.ts`)
+- **Structured + text content** responses: `structuredContent` always paired with `content: [{ type: 'text', text: JSON.stringify(structured) }]` for backward compatibility (observed in `src/tools.ts`)
+- **Error handling:** Tool errors return `isError: true` in result — never throw uncaught; `FetchError` class with error codes (observed in `src/tools.ts`, `src/errors.ts`)
+- **Class-based internal services** with injected dependencies (e.g., `IpBlocker`, `UrlNormalizer`, `RawUrlTransformer` in `src/fetch.ts`)
+- **AsyncLocalStorage** for request-scoped context/observability (`runWithRequestContext` in `src/observability.ts`, used in `src/tools.ts`)
+- **Worker-thread pool** for CPU-intensive HTML transforms with graceful scaling and shutdown (observed in `src/transform.ts`, `src/workers/`)
+- **Explicit return types** on exported functions — enforced by `@typescript-eslint/explicit-function-return-type` (see `eslint.config.mjs`)
+- **Shebang required:** `src/index.ts` must start with `#!/usr/bin/env node` (observed in `src/index.ts`, documented in `.github/instructions/typescript-mcp-server.instructions.md`)
+- **Prefer arrow callbacks, const, template literals, destructuring, optional chaining, nullish coalescing** — all enforced via ESLint rules (see `eslint.config.mjs`)
 ## 5) Agent Behavioral Rules (Do Nots)
-- Do not introduce new dependencies without updating manifests/lockfiles via the package manager.
-- Do not edit `package-lock.json` manually.
-- Do not commit secrets; never print `.env` values; use existing `config.ts` env parsing.
-- Do not change public APIs (tool schemas, MCP resource URIs) without updating docs/tests and noting migration impact.
-- Do not disable or bypass existing ESLint/TypeScript rules without explicit approval.
-- Do not use default exports; always use named exports.
-- Do not use `any`; use `unknown` and narrow with type guards (`type-guards.ts`).
-- Do not write to `stdout` in production code (corrupts JSON-RPC stdio transport); use `process.stderr` or observability helpers.
-- Do not add `.js` extension-less local imports — NodeNext resolution requires `.js` extensions.
-- Do not use Zod v3 APIs (`z.object()` → use `z.strictObject()`).
-- Do not throw uncaught exceptions from tool handlers — return `isError: true` responses.
+- Do not introduce new dependencies without updating `package.json` and `package-lock.json` via `npm install`. (see `package-lock.json` presence, `.github/workflows/release.yml` uses `npm ci`)
+- Do not edit `package-lock.json` manually. (see `package-lock.json`)
+- Do not commit secrets; never print `.env` values. Use environment variables via `config.ts`. (see `.gitignore` excludes `.env*`)
+- Do not write non-MCP output to **stdout** in server code — it corrupts JSON-RPC on stdio transport. Use `console.error()` or protocol logging. (see `.github/instructions/typescript-mcp-server.instructions.md`)
+- Do not use default exports. Use named exports only. (see `.github/instructions/typescript-mcp-server.instructions.md`)
+- Do not use `any` — enforced by `@typescript-eslint/no-explicit-any: 'error'`. (see `eslint.config.mjs`)
+- Do not disable or bypass existing lint/type rules without explicit approval. (see `eslint.config.mjs`, `tsconfig.json`)
+- Do not use `zod/v3` compat mode — standardize on Zod v4. (see `.github/instructions/typescript-mcp-server.instructions.md`, `package.json`)
+- Do not omit `.js` extensions in local imports. (see `tsconfig.json` `module: "NodeNext"`)
+- Do not remove the shebang line (`#!/usr/bin/env node`) from `src/index.ts`. (see `.github/instructions/typescript-mcp-server.instructions.md`)
+- Do not throw uncaught exceptions from tool handlers — return `isError: true` instead. (see `.github/instructions/typescript-mcp-server.instructions.md`)
 ## 6) Testing Strategy (Verified)
-- **Framework:** `node:test` (built-in Node.js test runner) + `node:assert/strict`
-- **Where tests live:** `tests/` directory (all `*.test.ts` files)
+- **Framework:** Node.js built-in test runner (`node:test`) with `node:assert/strict` (see `scripts/tasks.mjs`, `tests/fetch-url-tool.test.ts`)
+- **Where tests live:** `tests/` directory — 46+ `.test.ts` files (see repo tree)
+- **Test patterns scanned:** `src/__tests__/**/*.test.ts`, `tests/**/*.test.ts` (see `scripts/tasks.mjs` `CONFIG.test.patterns`)
 - **Approach:**
-  - Tests run against **compiled output** (`dist/`) — build is a prerequisite
-  - Unit tests with `t.mock.method()` for mocking (`globalThis.fetch`, library methods)
-  - No external test dependencies (no Jest, Vitest, etc.)
-  - Patterns: describe/it blocks, setUp/tearDown via `after()`, config mutations restored in `finally`
-  - ~45 test files covering tools, cache, transform, URL handling, HTTP server, sessions, errors, etc.
-  - Coverage available via `npm run test:coverage` (`--experimental-test-coverage`)
+  - Tests import from compiled `../dist/` — a full build runs before tests (see `scripts/tasks.mjs` `TestTasks.test`, `tests/fetch-url-tool.test.ts` imports)
+  - Unit tests with `globalThis.fetch` mocked via `t.mock.method()` (observed in `tests/fetch-url-tool.test.ts`)
+  - Config values temporarily overridden per test with `try/finally` cleanup (observed in `tests/fetch-url-tool.test.ts`)
+  - Worker pool shutdown in `after()` hooks for clean teardown (observed in `tests/fetch-url-tool.test.ts`)
+  - No external services (DB/containers) required for tests
+- **CI validation order:** `lint` → `type-check` → `test` → `build` (see `.github/workflows/release.yml`)
-## 7) Common Pitfalls (Verified)
+## 7) Common Pitfalls (Verified Only)
-- **Tests require build first** — `npm test` runs the build automatically, but if running `node --test` manually, ensure `dist/` is current.
-- **CI uses Node 20 but `engines` requires ≥24** — local dev/tests must use Node ≥24; the publish workflow pins Node 20 for npm compatibility.
-- **Config mutations in tests** — tests that modify `config.*` properties must restore original values in `finally` blocks to avoid leaking state across tests.
-- **Worker pool shutdown** — tests using the transform pipeline should call `shutdownTransformWorkerPool()` in `after()` hooks to prevent hanging processes.
-- **Shebang line** — `src/index.ts` must keep `#!/usr/bin/env node` as the exact first line (no BOM, no blank lines before it).
+- Tests run against compiled output (`dist/`), not source — always build before testing. The `npm run test` command handles this automatically. (see `scripts/tasks.mjs`)
+- `src/instructions.md` must exist — the build validates its presence and copies it to `dist/`. Missing it will fail the build. (see `scripts/tasks.mjs` `BuildTasks.validate`)
+- Worker pool state is process-global — tests that change `config.transform.maxWorkerScale` must call `shutdownTransformWorkerPool()` before and/or after to avoid stale pool state. (observed in `tests/fetch-url-tool.test.ts`)
+- Import sorting is enforced by Prettier plugin — manual import reordering will be overwritten by `npm run format`. (see `.prettierrc` `importOrder`)
 ## 8) Evolution Rules
 - If conventions change, include an `AGENTS.md` update in the same PR.
 - If a command is corrected after failures, record the final verified command here.
+- If a new critical path or pattern is discovered, add it to the relevant section with evidence.

package/dist/instructions.md CHANGED Viewed

@@ -1,57 +1,110 @@
-# FETCH URL MCP INSTRUCTIONS
+# FETCH-URL INSTRUCTIONS
-Available as resource (internal://instructions) or prompt (get-help). Load when unsure about tool usage.
+Available as resource (`internal://instructions`) or prompt (`get-help`). Load when unsure about tool usage.
 ---
 ## CORE CAPABILITY
 - Domain: Fetch public web pages and convert HTML to clean, LLM-readable Markdown.
-- Primary Output: Markdown content (inline; may be truncated).
-- Tools: fetch-url (READ-ONLY; no write tools exist).
-- Prompts: get-help.
+- Primary Resources: Markdown content, cached snapshots (`internal://cache/{namespace}/{hash}`).
+- Tools: `fetch-url` (READ-ONLY; no write tools exist).
 ---
-## THE “GOLDEN PATH” WORKFLOWS (CRITICAL)
+## PROMPTS
+- `get-help`: Returns these instructions for quick recall.
+---
+## RESOURCES & RESOURCE LINKS
+- `internal://instructions`: This document.
+- `internal://cache/{namespace}/{hash}`: Immutable cached Markdown snapshots from previous `fetch-url` calls. Ephemeral — lost when the server process restarts.
+- If inline Markdown is truncated (ends with `...[truncated]`), the full content may be available via the cache resource. Use `resources/read` with the cache URI to retrieve it.
+---
+## PROGRESS & TASKS
+- Include `_meta.progressToken` in requests to receive `notifications/progress` updates during fetch.
+- Task-augmented tool calls are supported for `fetch-url`:
+  - These tools declare `execution.taskSupport: "optional"` — invoke normally or as a task.
+  - Send `tools/call` with `task` to get a task id.
+  - Poll `tasks/get` and fetch results via `tasks/result`.
+  - Use `tasks/cancel` to abort.
+  - Task data is stored in memory and cleared on restart.
+---
+## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
 ### WORKFLOW A: STANDARD FETCH
-- Call fetch-url with: { "url": "https://..." }
-- Read the “markdown” field from “structuredContent”.
-- If truncated (ends with "...[truncated]"): re-run with a higher maxInlineChars or configure MAX_INLINE_CONTENT_CHARS.
+1. Call `fetch-url` with `{ "url": "https://..." }`.
+2. Read the `markdown` field from `structuredContent`.
+3. If `truncated` is `true`: use the cache resource URI or paginated access to get full content.
+   NOTE: Never guess URIs; always use values returned in responses.
+### WORKFLOW B: FRESH CONTENT (BYPASS CACHE)
+1. Call `fetch-url` with `{ "url": "https://...", "forceRefresh": true }`.
+2. Read the `markdown` field.
+   NOTE: Use `forceRefresh` only when stale content is suspected. Cached responses are faster.
-### WORKFLOW B: ASYNC EXECUTION (LARGE SITES / TIMEOUTS)
+### WORKFLOW C: FULL-FIDELITY FETCH (PRESERVE NOISE)
-- Call tools/call with task: { ttl: ... } to start a background fetch.
-- Poll tasks/get until status is “completed” or “failed”.
-- Retrieve result via tasks/result.
+1. Call `fetch-url` with `{ "url": "https://...", "skipNoiseRemoval": true }`.
+2. Read the `markdown` field — navigation, footers, and sidebars are preserved.
+   NOTE: Use this when page structure (nav, footer) is relevant to the task.
+### WORKFLOW D: ASYNC EXECUTION (LARGE SITES / TIMEOUTS)
+1. Call `tools/call` with `task: { ttl: ... }` to start a background fetch.
+2. Poll `tasks/get` until status is `completed` or `failed`.
+3. Retrieve result via `tasks/result`.
 ---
 ## TOOL NUANCES & GOTCHAS
-fetch-url
+`fetch-url`
 - Purpose: Fetch a URL and return Markdown.
-- Input: { "url": "https://..." }
-- Optional: skipNoiseRemoval (bool, keeps nav/footers), forceRefresh (bool, bypasses cache), maxInlineChars (int, per-call inline limit).
-- Side effects: None (read-only, idempotent). Populates cache automatically.
-- Limits: HTML capped at 10 MB (MAX_HTML_BYTES). Inline content unlimited by default; set MAX_INLINE_CONTENT_CHARS globally or maxInlineChars per call.
-- Blocked: localhost, private IPs (10.x, 172.16–31.x, 192.168.x), cloud metadata endpoints.
-- Quality: Varies by HTML structure. Best with articles/docs. Always verify output.
+- Input: `{ url, skipNoiseRemoval?, forceRefresh?, maxInlineChars? }`
+  - `url` (required): Must be `http://` or `https://`. Max 2048 chars.
+  - `skipNoiseRemoval` (bool): Keeps navigation, footers, and other elements normally filtered.
+  - `forceRefresh` (bool): Bypasses the cache and fetches live.
+  - `maxInlineChars` (int, 0–10485760): Per-call inline limit. `0` means unlimited. If a global limit is configured, the lower value wins.
+- Output: `{ url, inputUrl, resolvedUrl, finalUrl, title, metadata, markdown, fromCache, fetchedAt, contentSize, truncated, error, statusCode, details }`
+  - `metadata`: Extracted page metadata — `title`, `description`, `author`, `image`, `favicon`, `publishedAt`, `modifiedAt`.
+  - `markdown`: The extracted content. May be absent on error.
+  - `truncated`: `true` when inline content was cut. Full content stored in cache.
+  - `resolvedUrl`: The normalized/raw-transformed URL actually fetched (GitHub/GitLab/Bitbucket URLs auto-convert to raw content URLs).
+  - `finalUrl`: The URL after following redirects.
+- Side effects: None (read-only, idempotent). Populates the in-memory cache automatically.
+- Gotcha: Inline Markdown may be truncated when `MAX_INLINE_CONTENT_CHARS` is configured. Check the `truncated` field and use the cache resource for full content.
+- Gotcha: GitHub, GitLab, and Bitbucket URLs are auto-transformed to raw content endpoints. Check `resolvedUrl` to see the actual fetched URL.
+- Gotcha: Does not execute client-side JavaScript. Content requiring JS rendering may be incomplete.
+- Limits: HTML capped at 10 MB (`MAX_HTML_BYTES`). Inline content unlimited by default; set `MAX_INLINE_CONTENT_CHARS` env var to cap.
 ---
-## ERROR HANDLING STRATEGY
+## CONSTRAINTS & LIMITATIONS
-- VALIDATION_ERROR: URL invalid or blocked. Do not retry.
-- FETCH_ERROR: Network/upstream failure. Retry once with backoff.
-- queue_full: Usually handled internally by automatic fallback to in-process transform. If surfaced, retry or use Task interface.
+- **Blocked URLs:** localhost, private IPs (`10.x`, `172.16–31.x`, `192.168.x`), cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`, etc.), `.local`/`.internal` suffixes.
+- **Max HTML size:** 10 MB per fetch.
+- **Cache:** In-memory LRU — max 100 entries, 50 MB total, 24-hour TTL. Lost on process restart.
+- **No JavaScript execution:** Pages relying on client-side rendering may yield incomplete Markdown.
+- **Binary files:** Not supported — only HTML content is processed.
+- **Redirects:** Max 5 redirects followed automatically.
 ---
-## RESOURCES
+## ERROR HANDLING STRATEGY
-- internal://instructions — This document.
-- internal://cache/{namespace}/{hash} — Read cached markdown entries (typically namespace=`markdown`).
+- `VALIDATION_ERROR`: URL invalid or blocked (private IP, metadata endpoint). Do not retry — fix the URL.
+- `FETCH_ERROR`: Network/upstream failure (DNS, connection refused, timeout). Retry once with backoff.
+- `HTTP_{status}` (e.g. `HTTP_404`, `HTTP_500`): Upstream returned an HTTP error. Check `statusCode` and `details` fields. Retry only for 5xx errors.
+- `queue_full`: Worker pool busy (concurrent transforms). Wait briefly, then retry or use the Task interface.

package/package.json CHANGED Viewed

@@ -1,91 +1,91 @@
-{
-  "name": "@j0hanz/fetch-url-mcp",
-  "version": "0.0.1",
-  "mcpName": "io.github.j0hanz/fetch-url-mcp",
-  "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "fetch-url-mcp": "dist/index.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/j0hanz/fetch-url-mcp.git"
-  },
-  "homepage": "https://github.com/j0hanz/fetch-url-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/j0hanz/fetch-url-mcp/issues"
-  },
-  "author": "j0hanz",
-  "license": "MIT",
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "web-fetching",
-    "content-extraction",
-    "readability",
-    "markdown",
-    "ai-tools",
-    "model-context-protocol",
-    "fetch-url-mcp"
-  ],
-  "scripts": {
-    "clean": "node scripts/tasks.mjs clean",
-    "validate:instructions": "node scripts/tasks.mjs validate:instructions",
-    "build": "node scripts/tasks.mjs build",
-    "copy:assets": "node scripts/tasks.mjs copy:assets",
-    "prepare": "npm run build",
-    "dev": "tsc --watch --preserveWatchOutput",
-    "dev:run": "node --env-file=.env --watch dist/index.js",
-    "start": "node dist/index.js",
-    "format": "prettier --write .",
-    "type-check": "node scripts/tasks.mjs type-check",
-    "type-check:diagnostics": "tsc --noEmit --extendedDiagnostics",
-    "type-check:trace": "node -e \"require('fs').rmSync('.ts-trace',{recursive:true,force:true})\" && tsc --noEmit --generateTrace .ts-trace",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "test": "node scripts/tasks.mjs test",
-    "test:coverage": "node scripts/tasks.mjs test --coverage",
-    "knip": "knip",
-    "knip:fix": "knip --fix",
-    "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js --stdio",
-    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@mozilla/readability": "^0.6.0",
-    "linkedom": "^0.18.12",
-    "node-html-markdown": "^2.0.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-    "@types/node": "^24",
-    "eslint": "^9.23.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-de-morgan": "^2.0.0",
-    "eslint-plugin-depend": "^1.4.0",
-    "eslint-plugin-sonarjs": "^3.0.6",
-    "eslint-plugin-unused-imports": "^4.4.1",
-    "knip": "^5.83.1",
-    "prettier": "^3.8.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0"
-  },
-  "engines": {
-    "node": ">=24"
-  }
-}
+{
+  "name": "@j0hanz/fetch-url-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.j0hanz/fetch-url-mcp",
+  "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "fetch-url-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/j0hanz/fetch-url-mcp.git"
+  },
+  "homepage": "https://github.com/j0hanz/fetch-url-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/j0hanz/fetch-url-mcp/issues"
+  },
+  "author": "j0hanz",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "web-fetching",
+    "content-extraction",
+    "readability",
+    "markdown",
+    "ai-tools",
+    "model-context-protocol",
+    "fetch-url-mcp"
+  ],
+  "scripts": {
+    "clean": "node scripts/tasks.mjs clean",
+    "validate:instructions": "node scripts/tasks.mjs validate:instructions",
+    "build": "node scripts/tasks.mjs build",
+    "copy:assets": "node scripts/tasks.mjs copy:assets",
+    "prepare": "npm run build",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "dev:run": "node --env-file=.env --watch dist/index.js",
+    "start": "node dist/index.js",
+    "format": "prettier --write .",
+    "type-check": "node scripts/tasks.mjs type-check",
+    "type-check:diagnostics": "tsc --noEmit --extendedDiagnostics",
+    "type-check:trace": "node -e \"require('fs').rmSync('.ts-trace',{recursive:true,force:true})\" && tsc --noEmit --generateTrace .ts-trace",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node scripts/tasks.mjs test",
+    "test:coverage": "node scripts/tasks.mjs test --coverage",
+    "knip": "knip",
+    "knip:fix": "knip --fix",
+    "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js --stdio",
+    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.12",
+    "node-html-markdown": "^2.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^24",
+    "eslint": "^9.23.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-de-morgan": "^2.0.0",
+    "eslint-plugin-depend": "^1.4.0",
+    "eslint-plugin-sonarjs": "^3.0.6",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "knip": "^5.83.1",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}