@j0hanz/superfetch 2.1.2 → 2.1.4

package/dist/cache.js

@@ -410,6 +410,30 @@ function appendServerOnClose(server, handler) {
         handler();
     };
 }
+function attachInitializedGate(server) {
+    let initialized = false;
+    const previousInitialized = server.server.oninitialized;
+    server.server.oninitialized = () => {
+        initialized = true;
+        previousInitialized?.();
+    };
+    return () => initialized;
+}
+function getClientResourceCapabilities(server) {
+    const caps = server.server.getClientCapabilities();
+    if (!caps || !isRecord(caps)) {
+        return { listChanged: true, subscribe: true };
+    }
+    const { resources } = caps;
+    if (!isRecord(resources)) {
+        return { listChanged: true, subscribe: true };
+    }
+    const { listChanged, subscribe } = resources;
+    return {
+        listChanged: listChanged === true,
+        subscribe: subscribe === true,
+    };
+}
 function registerResourceSubscriptionHandlers(server) {
     const subscriptions = new Set();
     server.server.setRequestHandler(SubscribeRequestSchema, (request) => {
@@ -438,9 +462,10 @@ function notifyResourceUpdate(server, uri, subscriptions) {
     });
 }
 export function registerCachedContentResource(server) {
+    const isInitialized = attachInitializedGate(server);
     const subscriptions = registerResourceSubscriptionHandlers(server);
     registerCacheContentResource(server);
-    registerCacheUpdateSubscription(server, subscriptions);
+    registerCacheUpdateSubscription(server, subscriptions, isInitialized);
 }
 function buildCachedContentResponse(uri, cacheKey) {
     const cached = requireCacheEntry(cacheKey);
@@ -452,20 +477,25 @@ function registerCacheContentResource(server) {
     }), {
         title: 'Cached Content',
         description: 'Access previously fetched web content from cache. Namespace: markdown. UrlHash: SHA-256 hash of the URL.',
-        mimeType: 'text/plain',
+        mimeType: 'text/markdown',
     }, (uri, params) => {
         const { namespace, urlHash } = resolveCacheParams(params);
         const cacheKey = `${namespace}:${urlHash}`;
         return buildCachedContentResponse(uri, cacheKey);
     });
 }
-function registerCacheUpdateSubscription(server, subscriptions) {
+function registerCacheUpdateSubscription(server, subscriptions, isInitialized) {
     const unsubscribe = onCacheUpdate(({ cacheKey }) => {
-        const resourceUri = toResourceUri(cacheKey);
-        if (!resourceUri)
+        if (!server.isConnected() || !isInitialized())
             return;
-        notifyResourceUpdate(server, resourceUri, subscriptions);
-        if (server.isConnected()) {
+        const { listChanged, subscribe } = getClientResourceCapabilities(server);
+        if (subscribe) {
+            const resourceUri = toResourceUri(cacheKey);
+            if (resourceUri) {
+                notifyResourceUpdate(server, resourceUri, subscriptions);
+            }
+        }
+        if (listChanged) {
             server.sendResourceListChanged();
         }
     });

package/dist/http.d.ts

@@ -4,6 +4,7 @@ interface SessionEntry {
     readonly transport: StreamableHTTPServerTransport;
     createdAt: number;
     lastSeen: number;
+    protocolInitialized: boolean;
 }
 interface McpRequestParams {
     _meta?: Record<string, unknown>;
@@ -47,6 +48,7 @@ interface McpSessionOptions {
     readonly sessionStore: SessionStore;
     readonly maxSessions: number;
 }
+type JsonRpcId = string | number | null;
 export declare function createSessionStore(sessionTtlMs: number): SessionStore;
 export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
 interface SlotTracker {
@@ -55,11 +57,12 @@ interface SlotTracker {
     readonly isInitialized: () => boolean;
 }
 export declare function createSlotTracker(): SlotTracker;
-export declare function ensureSessionCapacity({ store, maxSessions, res, evictOldest, }: {
+export declare function ensureSessionCapacity({ store, maxSessions, res, evictOldest, requestId, }: {
     store: SessionStore;
     maxSessions: number;
     res: Response;
     evictOldest: (store: SessionStore) => boolean;
+    requestId?: JsonRpcId;
 }): boolean;
 type CloseHandler = (() => void) | undefined;
 export declare function composeCloseHandlers(first: CloseHandler, second: CloseHandler): CloseHandler;

package/dist/http.js

@@ -864,6 +864,13 @@ function sendJsonRpcError(res, code, message, status = 400, id = null) {
         id,
     });
 }
+function sendJsonRpcErrorOrNoContent(res, code, message, status, id) {
+    if (id === null) {
+        res.sendStatus(204);
+        return;
+    }
+    sendJsonRpcError(res, code, message, status, id ?? null);
+}
 function getSessionId(req) {
     const header = req.headers['mcp-session-id'];
     return Array.isArray(header) ? header[0] : header;
@@ -965,21 +972,29 @@ function tryEvictSlot(store, maxSessions, evictOldest) {
         currentSize - 1 + inFlightSessions < maxSessions;
     return canFreeSlot && evictOldest(store);
 }
-export function ensureSessionCapacity({ store, maxSessions, res, evictOldest, }) {
+export function ensureSessionCapacity({ store, maxSessions, res, evictOldest, requestId, }) {
     if (!isServerAtCapacity(store, maxSessions)) {
         return true;
     }
     if (tryEvictSlot(store, maxSessions, evictOldest)) {
         return !isServerAtCapacity(store, maxSessions);
     }
-    respondServerBusy(res);
+    respondServerBusy(res, requestId);
     return false;
 }
-function respondServerBusy(res) {
-    sendJsonRpcError(res, -32000, 'Server busy: maximum sessions reached', 503, null);
+function respondServerBusy(res, requestId) {
+    sendJsonRpcErrorOrNoContent(res, -32000, 'Server busy: maximum sessions reached', 503, requestId);
 }
 function respondBadRequest(res, id) {
-    sendJsonRpcError(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400, id);
+    sendJsonRpcErrorOrNoContent(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400, id);
+}
+function respondSessionNotInitialized(res, requestId) {
+    sendJsonRpcErrorOrNoContent(res, -32000, 'Bad Request: Session not initialized', 400, requestId);
+}
+function isAllowedBeforeInitialized(method) {
+    return (method === 'initialize' ||
+        method === 'notifications/initialized' ||
+        method === 'ping');
 }
 function createTimeoutController() {
     let initTimeout = null;
@@ -1109,6 +1124,7 @@ async function connectTransportOrThrow({ transport, clearInitTimeout, releaseSlo
         logError('Failed to initialize MCP session', error instanceof Error ? error : undefined);
         throw error;
     }
+    return mcpServer;
 }
 function evictExpiredSessionsWithClose(store) {
     const evicted = store.evictExpired();
@@ -1132,13 +1148,15 @@ function evictOldestSessionWithClose(store) {
     });
     return true;
 }
-function reserveSessionIfPossible({ options, res, }) {
-    if (!ensureSessionCapacity({
+function reserveSessionIfPossible({ options, res, requestId, }) {
+    const capacityArgs = {
         store: options.sessionStore,
         maxSessions: options.maxSessions,
         res,
         evictOldest: evictOldestSessionWithClose,
-    })) {
+        ...(requestId !== undefined ? { requestId } : {}),
+    };
+    if (!ensureSessionCapacity(capacityArgs)) {
         return false;
     }
     if (!reserveSessionSlot(options.sessionStore, options.maxSessions)) {
@@ -1147,14 +1165,19 @@ function reserveSessionIfPossible({ options, res, }) {
     }
     return true;
 }
-function resolveExistingSessionTransport(store, sessionId, res, requestId) {
+function resolveExistingSessionTransport(store, sessionId, res, requestId, method) {
     const existingSession = store.get(sessionId);
     if (existingSession) {
+        if (!existingSession.protocolInitialized &&
+            !isAllowedBeforeInitialized(method)) {
+            respondSessionNotInitialized(res, requestId);
+            return null;
+        }
         store.touch(sessionId);
         return existingSession.transport;
     }
     // Client supplied a session id but it doesn't exist; Streamable HTTP: invalid session IDs => 404.
-    sendJsonRpcError(res, -32600, 'Session not found', 404, requestId);
+    sendJsonRpcErrorOrNoContent(res, -32600, 'Session not found', 404, requestId);
     return null;
 }
 function createSessionContext() {
@@ -1163,24 +1186,35 @@ function createSessionContext() {
     const transport = createSessionTransport({ tracker, timeoutController });
     return { tracker, timeoutController, transport };
 }
-function finalizeSessionIfValid({ store, transport, tracker, clearInitTimeout, res, }) {
+function attachSessionInitializedHandler(server, store, sessionId) {
+    const previousInitialized = server.server.oninitialized;
+    server.server.oninitialized = () => {
+        const entry = store.get(sessionId);
+        if (entry) {
+            entry.protocolInitialized = true;
+        }
+        previousInitialized?.();
+    };
+}
+function finalizeSessionIfValid({ store, transport, mcpServer, tracker, clearInitTimeout, res, requestId, }) {
     const { sessionId } = transport;
     if (typeof sessionId !== 'string') {
         clearInitTimeout();
         tracker.releaseSlot();
-        respondBadRequest(res, null);
+        respondBadRequest(res, requestId ?? null);
         return false;
     }
     finalizeSession({
         store,
         transport,
         sessionId,
+        mcpServer,
         tracker,
         clearInitTimeout,
     });
     return true;
 }
-function finalizeSession({ store, transport, sessionId, tracker, clearInitTimeout, }) {
+function finalizeSession({ store, transport, sessionId, mcpServer, tracker, clearInitTimeout, }) {
     clearInitTimeout();
     tracker.markInitialized();
     tracker.releaseSlot();
@@ -1189,7 +1223,9 @@ function finalizeSession({ store, transport, sessionId, tracker, clearInitTimeou
         transport,
         createdAt: now,
         lastSeen: now,
+        protocolInitialized: false,
     });
+    attachSessionInitializedHandler(mcpServer, store, sessionId);
     const previousOnClose = transport.onclose;
     transport.onclose = composeCloseHandlers(previousOnClose, () => {
         store.remove(sessionId);
@@ -1197,11 +1233,16 @@ function finalizeSession({ store, transport, sessionId, tracker, clearInitTimeou
     });
     logInfo('Session initialized');
 }
-async function createAndConnectTransport({ options, res, }) {
-    if (!reserveSessionIfPossible({ options, res }))
+async function createAndConnectTransport({ options, res, requestId, }) {
+    const reserveArgs = {
+        options,
+        res,
+        ...(requestId !== undefined ? { requestId } : {}),
+    };
+    if (!reserveSessionIfPossible(reserveArgs))
         return null;
     const { tracker, timeoutController, transport } = createSessionContext();
-    await connectTransportOrThrow({
+    const mcpServer = await connectTransportOrThrow({
         transport,
         clearInitTimeout: timeoutController.clear,
         releaseSlot: tracker.releaseSlot,
@@ -1209,9 +1250,11 @@ async function createAndConnectTransport({ options, res, }) {
     if (!finalizeSessionIfValid({
         store: options.sessionStore,
         transport,
+        mcpServer,
         tracker,
         clearInitTimeout: timeoutController.clear,
         res,
+        ...(requestId !== undefined ? { requestId } : {}),
     })) {
         return null;
     }
@@ -1220,14 +1263,14 @@ async function createAndConnectTransport({ options, res, }) {
 export async function resolveTransportForPost({ res, body, sessionId, options, }) {
     const requestId = body.id ?? null;
     if (sessionId) {
-        return resolveExistingSessionTransport(options.sessionStore, sessionId, res, requestId);
+        return resolveExistingSessionTransport(options.sessionStore, sessionId, res, requestId, body.method);
     }
     if (!isInitializeRequest(body)) {
         respondBadRequest(res, requestId);
         return null;
     }
     evictExpiredSessionsWithClose(options.sessionStore);
-    return createAndConnectTransport({ options, res });
+    return createAndConnectTransport({ options, res, requestId });
 }
 function startSessionCleanupLoop(store, sessionTtlMs) {
     const controller = new AbortController();

package/dist/instructions.md

@@ -1,66 +1,39 @@
-# superFetch MCP Server — AI Usage Instructions
+# superFetch Instructions
 
-Use this server to fetch single public http(s) URLs, extract readable content, and return clean Markdown suitable for summarization, RAG ingestion, and citation. Prefer these tools over "remembering" state in chat.
+> **Guidance for the Agent:** These instructions are available as a resource (`internal://instructions`). Load them when you are confused about tool usage.
 
-## Operating Rules
+## 1. Core Capability
 
-- Only fetch sources that are necessary and likely authoritative.
-- Cite using `resolvedUrl` (when present) and keep `fetchedAt`/metadata intact.
-- If content is missing/truncated, check for a `resource_link` in the output and read the cache resource.
-- If request is vague, ask clarifying questions.
+- **Domain:** Fetch public http(s) URLs, extract readable content, and return clean Markdown.
+- **Primary Resources:** `fetch-url` output (`markdown`, `title`, `url`) and cache resources (`superfetch://cache/markdown/{urlHash}`).
 
-### Strategies
+## 2. The "Golden Path" Workflows (Critical)
 
-- **Discovery:** Use `fetch-url` to retrieve content. Review the output for `resource_link` if the page is large.
-- **Action:** Read the Markdown content directly from the tool output or the referenced resource.
+### Workflow A: Fetch and Read
 
-## Data Model
+1. Call `fetch-url` with a public http(s) URL.
+2. Read `structuredContent.markdown` and `structuredContent.title`.
+3. Cite using `resolvedUrl` or `url` from the response.
 
-- **Markdown Content:** `markdown` content, `title`, and `url` metadata.
-- **Resources:** Cached content accessible via `superfetch://cache/{namespace}/{hash}`.
+### Workflow B: Large Content / Cache Resource
 
-## Workflows
+1. If the response includes a `resource_link`, read that resource URI.
+2. If content is missing, list resources and select the matching `superfetch://cache/markdown/{urlHash}` entry.
+   > **Constraint:** Never guess resource URIs. Use the returned `resource_link` or list resources first.
 
-### 1) Fetch and Read
+## 3. Tool Nuances & "Gotchas"
 
-```text
-fetch-url(url) → Get markdown content
-If content truncated → read resource(superfetch://cache/...)
-```
+- **`fetch-url`**:
+  - **Latency:** Network-bound; expect slower responses for large pages.
+  - **Side Effects:** Calls external websites (open-world).
+  - **Input:** `url` must be public http/https. Private/internal addresses are blocked.
+  - **Output:** Large content may return a `resource_link` instead of full inline markdown.
+- **Cache resources (`superfetch://cache/markdown/{urlHash}`)**:
+  - **Namespace:** Only `markdown` is valid.
+  - **Discovery:** Use resource listing or the `resource_link` returned by `fetch-url`.
 
-## Tools
+## 4. Error Handling Strategy
 
-### fetch-url
-
-Fetches a webpage and converts it to clean Markdown format (HTML → Readability → Markdown).
-
-- **Use when:** You need the text content of a specific public URL.
-- **Args:**
-  - `url` (string, required): The URL to fetch (must be http/https).
-- **Returns:**
-  - `structuredContent` with `markdown`, `title`, `url`.
-  - Content block with standard text.
-  - Or `resource_link` block if content exceeds inline limits.
-
-## Response Shape
-
-Success: `{ "content": [...], "structuredContent": { "markdown": "...", "title": "...", "url": "..." } }`
-Error: `{ "isError": true, "structuredContent": { "error": "...", "url": "..." } }`
-
-### Common Errors
-
-| Code               | Meaning              | Resolution                      |
-| ------------------ | -------------------- | ------------------------------- |
-| `VALIDATION_ERROR` | Invalid input URL    | Ensure URL is valid http/https  |
-| `FETCH_ERROR`      | Network/HTTP failure | Verify URL is public/accessible |
-
-## Limits
-
-- **Max Inline Characters:** 20000
-- **Max Content Size:** 10MB
-- **Fetch Timeout:** 15000ms
-
-## Security
-
-- Server blocks private/internal IP ranges (localhost, 127.x, 192.168.x, metadata services).
-- Do not attempt to fetch internal network targets.
+- **`VALIDATION_ERROR`**: URL is invalid or blocked. Confirm it is a public http(s) URL.
+- **`FETCH_ERROR`**: Network/HTTP failure. Retry or verify the site is reachable.
+- **Cache miss (`Content not found`)**: Re-run `fetch-url` or verify the cache entry exists.

package/dist/mcp.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerCachedContentResource } from './cache.js';
 import { config } from './config.js';
@@ -17,7 +17,6 @@ function createServerCapabilities() {
     return {
         tools: { listChanged: false },
         resources: { listChanged: true, subscribe: true },
-        logging: {},
     };
 }
 function createServerInstructions(serverVersion) {
@@ -32,6 +31,21 @@ function createServerInstructions(serverVersion) {
         return `superFetch MCP server |${serverVersion}| A high-performance web content fetching and processing server.`;
     }
 }
+function registerInstructionsResource(server) {
+    server.registerResource('instructions', new ResourceTemplate('internal://instructions', { list: undefined }), {
+        title: 'Server Instructions',
+        description: 'Usage guidance for the superFetch MCP server.',
+        mimeType: 'text/markdown',
+    }, (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: createServerInstructions(config.server.version),
+            },
+        ],
+    }));
+}
 export function createMcpServer() {
     const server = new McpServer(createServerInfo(), {
         capabilities: createServerCapabilities(),
@@ -39,6 +53,7 @@ export function createMcpServer() {
     });
     registerTools(server);
     registerCachedContentResource(server);
+    registerInstructionsResource(server);
     return server;
 }
 function attachServerErrorHandler(server) {

package/dist/tools.d.ts

@@ -62,9 +62,27 @@ export interface PipelineResult<T> {
     fetchedAt: string;
     cacheKey?: string | null;
 }
+export type ProgressToken = string | number;
+export interface RequestMeta {
+    progressToken?: ProgressToken | undefined;
+    [key: string]: unknown;
+}
+export interface ProgressNotificationParams {
+    progressToken: ProgressToken;
+    progress: number;
+    total?: number;
+    message?: string;
+    _meta?: Record<string, unknown>;
+}
+export interface ProgressNotification {
+    method: 'notifications/progress';
+    params: ProgressNotificationParams;
+}
 export interface ToolHandlerExtra {
     signal?: AbortSignal;
     requestId?: string | number;
+    _meta?: RequestMeta;
+    sendNotification?: (notification: ProgressNotification) => Promise<void>;
 }
 export declare const FETCH_URL_TOOL_NAME = "fetch-url";
 export declare const FETCH_URL_TOOL_DESCRIPTION = "Fetches a webpage and converts it to clean Markdown format";

package/dist/tools.js

@@ -2,12 +2,13 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import * as cache from './cache.js';
 import { config } from './config.js';
-import { FetchError, isSystemError } from './errors.js';
+import { FetchError, getErrorMessage, isSystemError } from './errors.js';
 import { fetchNormalizedUrl, normalizeUrl, transformToRawUrl, } from './fetch.js';
 import { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from './observability.js';
 import { transformHtmlToMarkdown, } from './transform.js';
 import { isRecord } from './utils.js';
 const TRUNCATION_MARKER = '...[truncated]';
+const FETCH_PROGRESS_TOTAL = 4;
 const fetchUrlInputSchema = z.strictObject({
     url: z.url({ protocol: /^https?$/i }).describe('The URL to fetch'),
 });
@@ -30,6 +31,33 @@ const fetchUrlOutputSchema = z.strictObject({
 });
 export const FETCH_URL_TOOL_NAME = 'fetch-url';
 export const FETCH_URL_TOOL_DESCRIPTION = 'Fetches a webpage and converts it to clean Markdown format';
+function createProgressReporter(extra) {
+    const token = extra?._meta?.progressToken ?? null;
+    const sendNotification = extra?.sendNotification;
+    if (token === null || !sendNotification) {
+        return { report: async () => { } };
+    }
+    return {
+        report: async (progress, message) => {
+            try {
+                await sendNotification({
+                    method: 'notifications/progress',
+                    params: {
+                        progressToken: token,
+                        progress,
+                        total: FETCH_PROGRESS_TOTAL,
+                        message,
+                    },
+                });
+            }
+            catch (error) {
+                logWarn('Failed to send progress notification', {
+                    error: getErrorMessage(error),
+                });
+            }
+        },
+    };
+}
 function serializeStructuredContent(structuredContent, fromCache) {
     return JSON.stringify(structuredContent, fromCache ? undefined : null, fromCache ? undefined : 2);
 }
@@ -354,11 +382,16 @@ function buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult) {
 function logFetchStart(url) {
     logDebug('Fetching URL', { url });
 }
-async function fetchPipeline(url, signal) {
+async function fetchPipeline(url, signal, progress) {
     return performSharedFetch({
         url,
         ...(signal === undefined ? {} : { signal }),
-        transform: (html, normalizedUrl) => buildMarkdownTransform()(html, normalizedUrl, signal),
+        transform: async (html, normalizedUrl) => {
+            if (progress) {
+                await progress.report(3, 'Transforming content');
+            }
+            return buildMarkdownTransform()(html, normalizedUrl, signal);
+        },
         serialize: serializeMarkdownResult,
         deserialize: deserializeMarkdownResult,
     });
@@ -376,11 +409,18 @@ async function executeFetch(input, extra) {
     if (!url) {
         return createToolErrorResponse('URL is required', '');
     }
+    const progress = createProgressReporter(extra);
+    await progress.report(1, 'Validating URL');
     logFetchStart(url);
-    const { pipeline, inlineResult } = await fetchPipeline(url, extra?.signal);
+    await progress.report(2, 'Fetching content');
+    const { pipeline, inlineResult } = await fetchPipeline(url, extra?.signal, progress);
+    if (pipeline.fromCache) {
+        await progress.report(3, 'Using cached content');
+    }
     if (inlineResult.error) {
         return createToolErrorResponse(inlineResult.error, url);
     }
+    await progress.report(4, 'Finalizing response');
     return buildResponse(pipeline, inlineResult, url);
 }
 export async function fetchUrlToolHandler(input, extra) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/superfetch",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "mcpName": "io.github.j0hanz/superfetch",
   "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
   "type": "module",
@@ -64,15 +64,15 @@
     "@eslint/js": "^9.39.2",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/express": "^5.0.6",
-    "@types/node": "^22.19.5",
+    "@types/node": "^22.19.6",
     "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.5",
     "eslint-plugin-unused-imports": "^4.3.0",
-    "knip": "^5.80.2",
-    "prettier": "^3.7.4",
+    "knip": "^5.81.0",
+    "prettier": "^3.8.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.53.0"