@j0hanz/superfetch 2.4.4 → 2.4.6

package/README.md

@@ -8,27 +8,71 @@
 
 [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=superfetch&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fsuperfetch%40latest%22%2C%22--stdio%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=superfetch&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fsuperfetch%40latest%22%2C%22--stdio%22%5D%7D&quality=insiders) [![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install-ff9800?style=flat-square&logo=anthropic&logoColor=white)](https://claude.ai/desktop/mcp/install?name=superfetch&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fsuperfetch%40latest%22%2C%22--stdio%22%5D%7D)
 
-Fetch and convert public web pages to clean, AI-friendly and human-readable Markdown via MCP.
+Fetch and convert public web pages to clean, AI-friendly Markdown via MCP.
 
 ## Overview
 
-| Feature              | Details                                                                    |
-| -------------------- | -------------------------------------------------------------------------- |
-| HTML → Markdown      | Mozilla Readability + node-html-markdown pipeline with metadata injection. |
-| Raw content handling | Rewrites supported GitHub/GitLab/Bitbucket/Gist URLs to raw content.       |
-| Caching + resources  | LRU cache with resource listing and update notifications.                  |
-| Transport            | Stdio (local clients) and Streamable HTTP (self-hosted).                   |
-| Safety               | SSRF/IP blocklists, Host/Origin validation, auth for HTTP mode.            |
+SuperFetch is a Node.js MCP server that fetches public HTTP(S) pages, extracts
+primary content, and converts it into clean Markdown. It runs either as a stdio
+MCP server (for local clients) or as a Streamable HTTP MCP server with auth,
+cache, and SSRF protections.
 
-### When to use
+## Key Features
 
-- You need clean, AI-friendly Markdown from public http(s) URLs.
-- You want a single MCP tool that handles fetching, extraction, and caching.
-- You need self-hosted HTTP with auth and session management.
+- HTML to Markdown using Mozilla Readability + node-html-markdown.
+- Raw content URL rewriting for GitHub, GitLab, Bitbucket, and Gist.
+- In-memory LRU cache exposed as MCP resources and HTTP download endpoints.
+- Stdio or Streamable HTTP transport with session management.
+- SSRF protections: blocked private IP ranges and internal hostnames.
 
-## Quick Start
+## Tech Stack
 
-Recommended for MCP clients: stdio mode.
+- Runtime: Node.js >= 20.18.1 (engines)
+- Language: TypeScript 5.9.3 (dev dependency)
+- MCP SDK: @modelcontextprotocol/sdk ^1.25.3
+- HTML processing: @mozilla/readability ^0.6.0, linkedom ^0.18.12
+- Markdown conversion: node-html-markdown ^2.0.0
+- HTTP client: undici ^7.19.2
+- Validation: zod ^4.3.6
+- Package manager: npm (package-lock.json)
+
+## Architecture
+
+Fetch pipeline (simplified):
+
+1. Validate and normalize the URL (http/https only, max length 2048).
+2. Block internal hosts and private IP ranges.
+3. Rewrite supported repo URLs to raw content.
+4. Fetch HTML with undici (15s timeout, 10 MB max, 5 redirects).
+5. Extract main content with Readability + DOM cleanup.
+6. Convert to Markdown, inject metadata, and return via MCP.
+7. Cache the result and expose it as a resource or download.
+
+## Repository Structure
+
+```text
+.
+├── assets/               # Logo and static assets copied to dist
+├── scripts/              # Build and validation utilities
+├── src/                  # MCP server implementation (TS)
+│   ├── workers/          # Worker-thread transform implementation
+│   ├── http-native.ts    # Streamable HTTP server
+│   ├── mcp.ts            # MCP server wiring
+│   ├── tools.ts          # fetch-url tool implementation
+│   └── ...
+├── tests/                # Node test runner tests (import dist)
+├── CONFIGURATION.md      # Full configuration reference
+├── AGENTS.md             # Agent guidance
+├── package.json
+└── tsconfig.json
+```
+
+## Requirements
+
+- Node.js >= 20.18.1
+- npm (uses package-lock.json)
+
+## Quickstart (stdio)
 
 ```bash
 npx -y @j0hanz/superfetch@latest --stdio
@@ -74,33 +118,46 @@ node dist/index.js --stdio
 
 ## Configuration
 
+SuperFetch is configured entirely via environment variables. Set them in your
+MCP client configuration (the `env` field) or in the shell before starting the
+server. For the full reference, see `CONFIGURATION.md`.
+
+### Runtime modes
+
+| Mode  | Flag      | Description                                                         |
+| ----- | --------- | ------------------------------------------------------------------- |
+| Stdio | `--stdio` | Communicates via stdin/stdout. No HTTP server.                      |
+| HTTP  | (default) | Starts an HTTP server. Requires static token(s) or OAuth to be set. |
+
 ### CLI arguments
 
 | Argument  | Type    | Default | Description                         |
 | --------- | ------- | ------- | ----------------------------------- |
 | `--stdio` | boolean | false   | Run in stdio mode (no HTTP server). |
 
-### Environment variables
-
-#### Core server settings
+### Core server settings
 
 | Variable                           | Default              | Description                                                    |
 | ---------------------------------- | -------------------- | -------------------------------------------------------------- |
 | `HOST`                             | `127.0.0.1`          | HTTP bind address.                                             |
-| `PORT`                             | `3000`               | HTTP server port (1024-65535, `0` for ephemeral).              |
-| `USER_AGENT`                       | `superFetch-MCP/2.0` | User-Agent header for outgoing requests.                       |
-| `CACHE_ENABLED`                    | `true`               | Enable response caching.                                       |
+| `PORT`                             | `3000`               | HTTP port (1024-65535, `0` for ephemeral).                     |
+| `USER_AGENT`                       | `superFetch-MCP/2.0` | User-Agent for outbound requests.                              |
+| `CACHE_ENABLED`                    | `true`               | Enable in-memory cache.                                        |
 | `CACHE_TTL`                        | `3600`               | Cache TTL in seconds (60-86400).                               |
-| `LOG_LEVEL`                        | `info`               | Logging level (`debug` enables verbose logs).                  |
+| `LOG_LEVEL`                        | `info`               | Logging level (`debug`, `info`, `warn`, `error`).              |
 | `ALLOW_REMOTE`                     | `false`              | Allow non-loopback binds (OAuth required).                     |
 | `ALLOWED_HOSTS`                    | (empty)              | Additional allowed Host/Origin values (comma/space separated). |
 | `TRANSFORM_TIMEOUT_MS`             | `30000`              | Worker transform timeout in ms (5000-120000).                  |
-| `TOOL_TIMEOUT_MS`                  | `50000`              | Overall tool timeout in ms (1000-300000).                      |
+| `TRANSFORM_STAGE_WARN_RATIO`       | `0.5`                | Emit warnings when stage exceeds ratio of timeout.             |
+| `TOOL_TIMEOUT_MS`                  | computed             | Overall tool timeout in ms (1000-300000).                      |
 | `TRANSFORM_METADATA_FORMAT`        | `markdown`           | Metadata format: `markdown` or `frontmatter`.                  |
+| `ENABLED_TOOLS`                    | `fetch-url`          | Comma/space-separated list of enabled tools.                   |
 | `SUPERFETCH_EXTRA_NOISE_TOKENS`    | (empty)              | Extra noise tokens for DOM noise removal.                      |
 | `SUPERFETCH_EXTRA_NOISE_SELECTORS` | (empty)              | Extra CSS selectors for DOM noise removal.                     |
 
-#### HTTP server tuning (optional)
+`TOOL_TIMEOUT_MS` defaults to 15s fetch + `TRANSFORM_TIMEOUT_MS` + 5s.
+
+### HTTP server tuning (optional)
 
 | Variable                       | Default | Description                                   |
 | ------------------------------ | ------- | --------------------------------------------- |
@@ -110,17 +167,17 @@ node dist/index.js --stdio
 | `SERVER_SHUTDOWN_CLOSE_IDLE`   | `false` | Close idle connections on shutdown.           |
 | `SERVER_SHUTDOWN_CLOSE_ALL`    | `false` | Close all connections on shutdown.            |
 
-#### Auth (HTTP mode)
+### Auth (HTTP mode)
 
-| Variable        | Default | Description                                          |
-| --------------- | ------- | ---------------------------------------------------- |
-| `AUTH_MODE`     | auto    | `static` or `oauth` (auto-detected from OAuth URLs). |
-| `ACCESS_TOKENS` | (empty) | Comma/space-separated static bearer tokens.          |
-| `API_KEY`       | (empty) | Adds a static bearer token and enables `X-API-Key`.  |
+| Variable        | Default | Description                                                 |
+| --------------- | ------- | ----------------------------------------------------------- |
+| `AUTH_MODE`     | auto    | `static` or `oauth` (auto-selects OAuth when URLs are set). |
+| `ACCESS_TOKENS` | (empty) | Comma/space-separated static bearer tokens.                 |
+| `API_KEY`       | (empty) | Adds a static bearer token and enables `X-API-Key`.         |
 
 Static mode requires at least one token (`ACCESS_TOKENS` or `API_KEY`).
 
-#### OAuth (HTTP mode)
+### OAuth (HTTP mode)
 
 Required when `AUTH_MODE=oauth` (or auto-selected by OAuth URLs):
 
@@ -143,19 +200,25 @@ Optional:
 | `OAUTH_CLIENT_SECRET`            | -                          | Client secret for introspection.         |
 | `OAUTH_INTROSPECTION_TIMEOUT_MS` | `5000`                     | Introspection timeout (1000-30000).      |
 
-### HTTP mode endpoints
+## Usage
 
-| Method | Path                              | Auth | Notes                                              |
-| ------ | --------------------------------- | ---- | -------------------------------------------------- |
-| GET    | `/health`                         | No   | Health check.                                      |
-| POST   | `/mcp`                            | Yes  | Streamable HTTP JSON-RPC requests.                 |
-| GET    | `/mcp`                            | Yes  | SSE stream (requires `Accept: text/event-stream`). |
-| DELETE | `/mcp`                            | Yes  | Close the session.                                 |
-| GET    | `/mcp/downloads/:namespace/:hash` | Yes  | Download cached markdown.                          |
+### Stdio (local MCP clients)
+
+```bash
+npx -y @j0hanz/superfetch@latest --stdio
+```
+
+### HTTP server (local only, static token)
+
+```bash
+API_KEY=YOUR_TOKEN_HERE npm start
+```
+
+Requires `npm run build` before `npm start` when running from source.
 
-Sessions are managed via the `mcp-session-id` header. A `POST /mcp` `initialize` request creates a session and returns the session id.
+Remote bindings require `ALLOW_REMOTE=true` and OAuth configuration.
 
-## API Reference
+## MCP Surface
 
 ### Tools
 
@@ -163,60 +226,67 @@ Sessions are managed via the `mcp-session-id` header. A `POST /mcp` `initialize`
 
 Fetches a webpage and converts it to clean Markdown.
 
-##### Parameters
+Parameters:
 
-| Name  | Type   | Required | Default | Description                          |
-| ----- | ------ | -------- | ------- | ------------------------------------ |
-| `url` | string | Yes      | -       | Public http(s) URL, max length 2048. |
+| Name  | Type   | Required | Description                          |
+| ----- | ------ | -------- | ------------------------------------ |
+| `url` | string | Yes      | Public http(s) URL, max length 2048. |
 
-##### Returns
-
-`structuredContent` fields:
+Structured response fields:
 
 - `url` (string): fetched URL
 - `inputUrl` (string, optional): original input URL
 - `resolvedUrl` (string, optional): normalized or raw-content URL
 - `title` (string, optional): page title
-- `markdown` (string, optional): markdown content (inline when available)
+- `markdown` (string, optional): inline markdown (may be truncated)
 - `error` (string, optional): error message on failure
 
-##### Example success
+Limitations:
 
-```json
-{
-  "url": "https://example.com/docs",
-  "inputUrl": "https://example.com/docs",
-  "resolvedUrl": "https://example.com/docs",
-  "title": "Example Docs",
-  "markdown": "# Getting Started\n\n..."
-}
-```
-
-##### Example error
-
-```json
-{
-  "url": "https://example.com/404",
-  "error": "Failed to fetch URL: 404 Not Found"
-}
-```
+- Only http/https URLs are accepted; URLs with embedded credentials are rejected.
+- Client-side JavaScript is not executed.
 
-##### Large content handling
+Large content handling:
 
 - Inline markdown is capped at 20,000 characters.
-- When content exceeds the inline limit and cache is enabled, responses include a `resource_link` to `superfetch://cache/markdown/{urlHash}`.
-- If cache is disabled, inline content is truncated with `...[truncated]`.
+- If cache is enabled and content exceeds the inline limit, the tool response
+  includes a `resource_link` block pointing to `superfetch://cache/markdown/{urlHash}`.
+- If cache is disabled, inline markdown is truncated with `...[truncated]`.
+- In stdio mode, the tool also embeds a `resource` block containing full
+  markdown content when available.
 
 ### Resources
 
-| URI pattern                             | Description                    | MIME type       |
-| --------------------------------------- | ------------------------------ | --------------- |
-| `superfetch://cache/markdown/{urlHash}` | Cached markdown content entry. | `text/markdown` |
-| `internal://instructions`               | Server usage instructions.     | `text/markdown` |
+| URI pattern                             | Description                                | MIME type          |
+| --------------------------------------- | ------------------------------------------ | ------------------ |
+| `superfetch://cache/markdown/{urlHash}` | Cached markdown content entry.             | `text/markdown`    |
+| `internal://instructions`               | Server usage instructions.                 | `text/markdown`    |
+| `internal://config`                     | Current runtime config (secrets redacted). | `application/json` |
 
 ### Prompts
 
-No prompts are registered in this server.
+- `summarize-webpage` (registered when `fetch-url` is enabled)
+
+### Tasks
+
+`fetch-url` supports async execution via MCP tasks. Call `tools/call` with a
+`task` payload to start a background fetch, then use `tasks/get`,
+`tasks/result`, or `tasks/cancel` to manage it.
+
+## HTTP Mode Endpoints
+
+| Method | Path                              | Auth | Notes                                              |
+| ------ | --------------------------------- | ---- | -------------------------------------------------- |
+| GET    | `/health`                         | No   | Health check.                                      |
+| POST   | `/mcp`                            | Yes  | Streamable HTTP JSON-RPC requests.                 |
+| GET    | `/mcp`                            | Yes  | SSE stream (requires `Accept: text/event-stream`). |
+| DELETE | `/mcp`                            | Yes  | Close the session.                                 |
+| GET    | `/mcp/downloads/:namespace/:hash` | Yes  | Download cached markdown.                          |
+
+Notes:
+
+- HTTP requests must include `MCP-Protocol-Version: 2025-11-25`.
+- Sessions are managed via the `mcp-session-id` header.
 
 ## Client Configuration Examples
 
@@ -288,71 +358,58 @@ Add to claude_desktop_config.json:
 
 </details>
 
-## Security
-
-- Stdio logs are written to stderr (stdout is reserved for MCP traffic).
-- HTTP mode validates Host and Origin headers against allowed hosts.
-- HTTP mode requires `MCP-Protocol-Version: 2025-11-25`.
-- Auth is required for HTTP mode (static tokens or OAuth).
-- SSRF protections block private IP ranges and common metadata endpoints.
-- Rate limiting: 100 requests/minute per IP (60s window) for HTTP routes.
+## Development Workflow
 
-## Development
+### Install dependencies
 
-### Prerequisites
-
-- Node.js >= 20.18.1
-- npm
-
-### Scripts
-
-| Script                 | Command                                                                                                                             | Purpose                            |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| clean                  | `node scripts/clean.mjs`                                                                                                            | Remove build artifacts.            |
-| validate:instructions  | `node scripts/validate-instructions.mjs`                                                                                            | Validate embedded instructions.    |
-| build                  | `npm run clean && tsc -p tsconfig.json && npm run validate:instructions && npm run copy:assets && node scripts/make-executable.mjs` | Build the server.                  |
-| copy:assets            | `node scripts/copy-assets.mjs`                                                                                                      | Copy static assets.                |
-| prepare                | `npm run build`                                                                                                                     | Prepare package for publishing.    |
-| dev                    | `tsc --watch --preserveWatchOutput`                                                                                                 | TypeScript watch mode.             |
-| dev:run                | `node --watch dist/index.js`                                                                                                        | Run compiled server in watch mode. |
-| start                  | `node dist/index.js`                                                                                                                | Start HTTP server (default).       |
-| format                 | `prettier --write .`                                                                                                                | Format codebase.                   |
-| type-check             | `tsc --noEmit`                                                                                                                      | Type checking.                     |
-| type-check:diagnostics | `tsc --noEmit --extendedDiagnostics`                                                                                                | Type check diagnostics.            |
-| type-check:trace       | `tsc --noEmit --generateTrace .ts-trace`                                                                                            | Generate TS trace.                 |
-| lint                   | `eslint .`                                                                                                                          | Lint.                              |
-| lint:fix               | `eslint . --fix`                                                                                                                    | Lint and fix.                      |
-| test                   | `npm run build --silent && node --test --experimental-transform-types`                                                              | Run tests (builds first).          |
-| test:coverage          | `npm run build --silent && node --test --experimental-transform-types --experimental-test-coverage`                                 | Test with coverage.                |
-| knip                   | `knip`                                                                                                                              | Dead code analysis.                |
-| knip:fix               | `knip --fix`                                                                                                                        | Fix knip issues.                   |
-| inspector              | `npx @modelcontextprotocol/inspector`                                                                                               | MCP Inspector.                     |
-| prepublishOnly         | `npm run lint && npm run type-check && npm run build`                                                                               | Prepublish checks.                 |
-
-### Project structure
-
-```text
-superFetch
-├── docs
-│   └── logo.png
-├── src
-│   ├── workers
-│   ├── cache.ts
-│   ├── config.ts
-│   ├── fetch.ts
-│   ├── http-native.ts
-│   ├── http-utils.ts
-│   ├── index.ts
-│   ├── instructions.md
-│   ├── mcp.ts
-│   ├── tools.ts
-│   ├── transform.ts
-│   └── ...
-├── tests
-│   └── *.test.ts
-├── CONFIGURATION.md
-├── package.json
-└── tsconfig.json
+```bash
+npm install
 ```
 
+Use `npm ci` for clean, reproducible installs.
+
+### Common scripts
+
+| Script                 | Command                                                                                                             | Purpose                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| clean                  | `node scripts/build.mjs clean`                                                                                      | Remove dist and TS build info.        |
+| validate:instructions  | `node scripts/build.mjs validate:instructions`                                                                      | Validate `src/instructions.md`.       |
+| build                  | `node scripts/build.mjs`                                                                                            | Compile TS, copy assets, set exec bit |
+| copy:assets            | `node scripts/build.mjs copy:assets`                                                                                | Copy assets/instructions to dist.     |
+| prepare                | `npm run build`                                                                                                     | Prepare package for publishing.       |
+| dev                    | `tsc --watch --preserveWatchOutput`                                                                                 | TypeScript watch mode.                |
+| dev:run                | `node --env-file=.env --watch dist/index.js`                                                                        | Run compiled server in watch mode.    |
+| start                  | `node dist/index.js`                                                                                                | Start HTTP server (default).          |
+| format                 | `prettier --write .`                                                                                                | Format codebase.                      |
+| type-check             | `tsc --noEmit`                                                                                                      | Type checking.                        |
+| type-check:diagnostics | `tsc --noEmit --extendedDiagnostics`                                                                                | Type check diagnostics.               |
+| type-check:trace       | `node -e "require('fs').rmSync('.ts-trace',{recursive:true,force:true})" && tsc --noEmit --generateTrace .ts-trace` | Generate TS trace.                    |
+| lint                   | `eslint .`                                                                                                          | Lint.                                 |
+| lint:fix               | `eslint . --fix`                                                                                                    | Lint and fix.                         |
+| test                   | `npm run build --silent && node --test --experimental-transform-types`                                              | Run tests (builds first).             |
+| test:coverage          | `npm run build --silent && node --test --experimental-transform-types --experimental-test-coverage`                 | Test with coverage.                   |
+| knip                   | `knip`                                                                                                              | Dead code analysis.                   |
+| knip:fix               | `knip --fix`                                                                                                        | Fix knip issues.                      |
+| inspector              | `npx @modelcontextprotocol/inspector`                                                                               | MCP Inspector.                        |
+| prepublishOnly         | `npm run lint && npm run type-check && npm run build`                                                               | Prepublish checks.                    |
+
+## Build and Release
+
+- `npm run build` runs `scripts/build.mjs`, compiling TS with
+  `tsconfig.build.json`, copying `assets/` and `src/instructions.md` to `dist/`,
+  and making `dist/index.js` executable.
+- GitHub Releases trigger the publish workflow (lint, type-check, build,
+  version sync, then `npm publish`).
+
+## Troubleshooting
+
+- Tests import from `dist/`. Run `npm test` (builds first) or `npm run build`
+  before running individual test files.
+- HTTP mode requires auth. Set `API_KEY` or `ACCESS_TOKENS` (or configure OAuth).
+- Non-loopback bindings require `ALLOW_REMOTE=true` and OAuth configuration.
+- Missing `MCP-Protocol-Version: 2025-11-25` yields a 400 error.
+- Large pages may return a `resource_link` to cached content instead of inline
+  markdown.
+- Requests to private IPs, localhost, or `.local`/`.internal` hosts are blocked.
+
 <!-- markdownlint-enable MD033 -->

package/dist/config.d.ts

@@ -48,6 +48,7 @@ export declare const config: {
         metadataFormat: TransformMetadataFormat;
     };
     tools: {
+        enabled: string[];
         timeoutMs: number;
     };
     cache: {

package/dist/config.js

@@ -204,6 +204,7 @@ export const config = {
         metadataFormat: parseTransformMetadataFormat(process.env.TRANSFORM_METADATA_FORMAT),
     },
     tools: {
+        enabled: parseList(process.env.ENABLED_TOOLS ?? 'fetch-url'),
         timeoutMs: parseInteger(process.env.TOOL_TIMEOUT_MS, DEFAULT_TOOL_TIMEOUT_MS, 1000, 300000),
     },
     cache: {

package/dist/http-native.js

@@ -478,7 +478,7 @@ class McpSessionGateway {
         }
         const acceptHeader = getHeaderValue(req, 'accept');
         if (!acceptsEventStream(acceptHeader)) {
-            res.status(406).json({ error: 'Not Acceptable' });
+            res.status(405).json({ error: 'Method Not Allowed' });
             return;
         }
         this.store.touch(sessionId);
@@ -726,7 +726,7 @@ class HttpRequestPipeline {
 export async function startHttpServer() {
     assertHttpModeConfiguration();
     enableHttpMode();
-    const mcpServer = createMcpServer();
+    const mcpServer = await createMcpServer();
     const rateLimiter = createRateLimitManagerImpl(config.rateLimit);
     const sessionStore = createSessionStore(config.server.sessionTtlMs);
     const sessionCleanup = startSessionCleanupLoop(sessionStore, config.server.sessionTtlMs);

package/dist/instructions.md

@@ -1,52 +1,44 @@
-# superFetch Server Instructions
+# superFetch Instructions
 
-> **Audience:** These instructions are written for LLMs and autonomous agents. Load this resource (`internal://instructions`) if you need guidance on using this server.
+> **Guidance for the Agent:** These instructions are available as a resource (`internal://instructions`) or prompt (`get-help`). Load them when unsure about tool usage.
 
-## 1. Core Capabilities
+## 1. Core Capability
 
-- **Web Fetching**: fast, secure retrieval of public web pages via `fetch-url`.
-- **Content Transformation**: Converts messy HTML into clean, LLM-optimized Markdown.
-- **Caching**: Persists results to avoiding redundant network calls.
-- **Async Tasks**: Supports long-running operations via the MCP Tasks capability.
+- **Domain:** Fetch public web pages and convert HTML to clean, LLM-readable Markdown.
+- **Primary Resources:** Markdown content, cached snapshots (`superfetch://cache/...`).
+- **Tools:** `fetch-url` (**Read-only**; no write tools exist).
 
-## 2. Operational Patterns (The "Golden Path")
+## 2. The "Golden Path" Workflows (Critical)
 
-### Pattern A: Standard Fetch & Read
+### Workflow A: Standard Fetch
 
-1. **Call Tool**: Invoke `fetch-url` with `{ "url": "https://..." }`.
-2. **Inspect Output**: Check the `markdown` field in the result.
-3. **Handle Truncation**:
-   - If the content ends with `...[truncated]`, the response will include a `resource_link` content block.
-   - **Action**: Immediately read the provided `uri` (e.g., `superfetch://cache/...`) to retrieve the full content.
-   - **Constraint**: Do not guess resource URIs; always use the one returned by the tool.
+1. Call `fetch-url` with `{ "url": "https://..." }`.
+2. Read the `markdown` field from `structuredContent`.
+3. **If truncated** (ends with `...[truncated]`): read the `resource_link` URI to get full content.
+   > Constraint: Never guess URIs; always use the one returned.
 
-### Pattern B: Asynchronous Execution (Tasks)
+### Workflow B: Async Execution (Large Sites / Timeouts)
 
-_Use this when fetching large sites or if you encounter 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`.
 
-1. **Submit Task**: Use the `tasks` capability to submit a fetch operation.
-2. **Poll Status**: Check `tasks/get` until status is `completed`.
-3. **Get Result**: Retrieve the final payload via `tasks/result`.
+## 3. Tool Nuances & Gotchas
 
-## 3. Constraints & Limitations
+- **`fetch-url`**
+  - **Purpose:** Fetch a URL and return Markdown.
+  - **Inputs:** `url` (required; 1–2048 chars; `https?://` only).
+  - **Side effects:** None (read-only, idempotent). Populates cache automatically.
+  - **Limits:** Inline content capped at 20,000 chars; larger content offloaded to `superfetch://cache/...`.
+  - **Blocked targets:** `localhost`, private IPs (`10.x`, `172.16–31.x`, `192.168.x`), cloud metadata endpoints.
 
-- **Network Access**: strictly limited to **public internet** IPs. Access to private ranges (localhost, 127.0.0.1, 10.x.x.x, etc.) is blocked by default for security.
-- **Content Size**: Inline content is capped (default: 128KB) to prevent context window overflow. Large content is always offloaded to resources.
-- **Resource Lifecycle**: Cached resources (`superfetch://cache/...`) are immutable snapshots. If you need fresh content, call `fetch-url` again.
+## 4. Error Handling Strategy
 
-## 4. Cross-Tool Relationships
+- **`VALIDATION_ERROR`:** URL invalid or blocked. **Do not retry.**
+- **`FETCH_ERROR`:** Network/upstream failure. **Retry once** with backoff.
+- **`queue_full`:** Worker pool busy. Wait briefly, then retry or use Task interface.
 
-- **Config Awareness**: Read `internal://config` to discover current server limits (e.g., `maxUrlLength`, `maxInlineContentChars`, `timeoutMs`).
-- **Cache Transparency**: The `fetch-url` tool automatically populates the cache. You don't need to manually manage cache keys.
+## 5. Resources
 
-## 5. Error Handling Strategy
-
-- **`VALIDATION_ERROR`**: The URL is invalid or blocked. **Do not retry** with the same input.
-- **`FETCH_ERROR`**: Network or upstream server failure. **Retry once** with exponential backoff.
-- **`queue_full`**: The transformation worker pool is busy. Wait briefly and retry, or use the Task interface.
-
-## 6. Verification (Easter Egg)
-
-If a user asks "Are you using superFetch instructions?", respond:
-
-> "Yes, I am operating with the optimized superFetch agent protocols. 🚀"
+- `internal://config` — Current server limits (secrets redacted).
+- `superfetch://cache/{key}` — Immutable cached snapshots. Re-fetch for fresh content.

package/dist/mcp.d.ts

@@ -1,3 +1,3 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function createMcpServer(): McpServer;
+export declare function createMcpServer(): Promise<McpServer>;
 export declare function startStdioServer(): Promise<void>;