crawlforge-mcp-server 5.10.0 → 6.0.0

package/src/core/ChangeTracker.js

@@ -37,7 +37,7 @@ const ChangeTrackingSchema = z.object({
       moderate: z.number().min(0).max(1).default(0.3),
       major: z.number().min(0).max(1).default(0.7)
     }).optional()
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const ChangeComparisonSchema = z.object({

package/src/core/ElicitationHelper.js

@@ -5,8 +5,58 @@
  * expensive or ambiguous operations. Falls back gracefully when the
  * MCP client does not support elicitation.
  *
- * MCP Spec 2025-11-25: client/elicit request with requestedSchema
+ * The request goes out as a 2025-era server→client `elicitation/create`,
+ * awaited inline in the middle of a tool's work. Two things the SDK does NOT
+ * do for us, and which `supported` therefore decides before we send:
+ *
+ *   - `Server.elicitInput()` refuses a client that declared a bare
+ *     `elicitation: {}` (it demands `elicitation.form`), even though the SDK's
+ *     own capability rule counts a bare declaration as form-capable — that is
+ *     the pre-mode 2025 meaning, and it is what the SDK's legacy shim and its
+ *     2026 seam both apply. We send through `Server.request()`, which applies
+ *     that same lenient rule, so those clients get their prompt.
+ *
+ *   - Both `elicitInput()` and `request()` throw on a 2026-07-28-era
+ *     connection: that revision has no server→client request channel at all.
+ *     There is no inline substitute — the replacement is an `input_required`
+ *     result RETURNED by a tools/call handler, which this helper cannot do
+ *     from the middle of a tool's execution. So `supported` reports false and
+ *     the operation proceeds unasked, exactly as it does for a client with no
+ *     elicitation capability. A confirmation prompt is a nicety; failing the
+ *     call is not an acceptable substitute. See docs/mcp-spec-adoption.md.
+ */
+
+/**
+ * First revision of the modern protocol era. Revisions are ISO dates, so
+ * lexicographic comparison orders them chronologically (the SDK's own rule).
  */
+const FIRST_MODERN_PROTOCOL_VERSION = '2026-07-28';
+
+/** The one-boolean schema a confirmation asks with. */
+const CONFIRM_SCHEMA = {
+  type: 'object',
+  properties: {
+    confirmed: {
+      type: 'boolean',
+      title: 'Proceed?',
+      description: 'Confirm to proceed with the operation',
+    },
+  },
+  required: ['confirmed'],
+};
+
+/**
+ * Whether the client's declared capabilities cover FORM elicitation, by the
+ * SDK's own rule: `elicitation.form` counts, and so does a bare `elicitation`
+ * declaration naming neither mode (the pre-mode 2025 meaning). A client that
+ * declared only `elicitation.url` has not declared form support.
+ */
+function formElicitationDeclared(caps) {
+  const elicitation = caps?.elicitation;
+  if (!elicitation) return false;
+  if (elicitation.form !== undefined) return true;
+  return elicitation.url === undefined;
+}
 
 export class ElicitationHelper {
   /**
@@ -20,22 +70,35 @@ export class ElicitationHelper {
   }
 
   /**
-   * Whether the connected MCP client supports elicitation.
+   * Whether an inline elicitation round trip will actually reach the user.
    * @returns {boolean}
    */
   get supported() {
     const server = this._mcpServer?.server;
-    // The MCP SDK exposes elicitation via Server.elicitInput(); it is only
-    // usable when the connected CLIENT advertised the `elicitation` capability.
-    if (typeof server?.elicitInput !== 'function') return false;
+    if (typeof server?.request !== 'function') return false;
     try {
-      const caps = server.getClientCapabilities?.();
-      return !!caps?.elicitation;
+      // No server→client request channel exists on the 2026-07-28 era.
+      const negotiated = server.getNegotiatedProtocolVersion?.();
+      if (typeof negotiated === 'string' && negotiated >= FIRST_MODERN_PROTOCOL_VERSION) return false;
+      return formElicitationDeclared(server.getClientCapabilities?.());
     } catch {
       return false;
     }
   }
 
+  /**
+   * Send one form-mode `elicitation/create` and return the ElicitResult.
+   * This is byte-for-byte the message `Server.elicitInput()` sends; it just
+   * does not impose that method's stricter `elicitation.form` gate.
+   * @private
+   */
+  async _elicit(message, requestedSchema) {
+    return this._mcpServer.server.request({
+      method: 'elicitation/create',
+      params: { message, requestedSchema, mode: 'form' },
+    });
+  }
+
   /**
    * Ask for user confirmation before proceeding with an expensive operation.
    * Returns true if confirmed (or if elicitation is unsupported — fail-open
@@ -57,20 +120,7 @@ export class ElicitationHelper {
         .join('\n');
       const fullMessage = detailLines ? `${message}\n\n${detailLines}` : message;
 
-      const result = await this._mcpServer.server.elicitInput({
-        message: fullMessage,
-        requestedSchema: {
-          type: 'object',
-          properties: {
-            confirmed: {
-              type: 'boolean',
-              title: 'Proceed?',
-              description: 'Confirm to proceed with the operation',
-            },
-          },
-          required: ['confirmed'],
-        },
-      });
+      const result = await this._elicit(fullMessage, CONFIRM_SCHEMA);
 
       // Only an explicit accept + confirmed=true proceeds; decline/cancel = stop.
       return result?.action === 'accept' && result?.content?.confirmed === true;
@@ -97,23 +147,22 @@ export class ElicitationHelper {
     }
 
     try {
-      const result = await this._mcpServer.server.elicitInput({
-        message,
-        requestedSchema: {
-          type: 'object',
-          properties: {
-            [fieldName]: {
-              type: 'string',
-              title: fieldName,
-              description: fieldDescription,
-              ...(defaultValue ? { default: defaultValue } : {}),
-            },
+      const result = await this._elicit(message, {
+        type: 'object',
+        properties: {
+          [fieldName]: {
+            type: 'string',
+            title: fieldName,
+            description: fieldDescription,
+            ...(defaultValue ? { default: defaultValue } : {}),
           },
-          required: [fieldName],
         },
+        required: [fieldName],
       });
 
-      if (result?.action === 'accept' && result?.content?.[fieldName] != null) {
+      // The answer is client-supplied and no longer schema-checked by the SDK
+      // on this path, so hold it to the type we asked for.
+      if (result?.action === 'accept' && typeof result?.content?.[fieldName] === 'string') {
         return result.content[fieldName];
       }
       return defaultValue || null;

package/src/core/SamplingClient.js

@@ -7,7 +7,9 @@
  * Fallback chain (applied in resolveCompletion):
  *   1. Ollama (local, no API key needed)
  *   2. Server-side API key (OPENAI_API_KEY / ANTHROPIC_API_KEY)
- *   3. MCP sampling request to client
+ *   3. MCP sampling request to client — DEPRECATED in MCP revision 2026-07-28
+ *      (SEP-2577); removal on or after 2027-07-28. Emits a one-line stderr
+ *      deprecation notice when it serves a completion.
  *   4. Error
  */
 
@@ -157,7 +159,11 @@ export class SamplingClient {
           includeContext: 'none',
         });
         const text = samplingResult?.content?.text || '';
-        if (text) return { text, provider: 'sampling' };
+        if (text) {
+          // stderr, never stdout — stdout is the JSON-RPC stream on stdio.
+          console.error('[deprecation] MCP sampling served this completion. Sampling was deprecated in MCP revision 2026-07-28 (SEP-2577); CrawlForge removes this fallback on or after 2027-07-28. Run Ollama or set OPENAI_API_KEY / ANTHROPIC_API_KEY.');
+          return { text, provider: 'sampling' };
+        }
       } catch (_samplingErr) {
         // Sampling not supported or failed
       }

package/src/core/analysis/ContentAnalyzer.js

@@ -28,7 +28,7 @@ const ContentAnalyzerSchema = z.object({
     maxKeywords: z.number().min(1).max(50).default(15),
     includeReadabilityMetrics: z.boolean().default(true),
     includeSentiment: z.boolean().default(true)
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const AnalysisResult = z.object({

package/src/core/processing/BrowserProcessor.js

@@ -74,7 +74,7 @@ const BrowserProcessorSchema = z.object({
       enableTimezoneSpoof: z.boolean().default(true),
       enableGeoLocationSpoof: z.boolean().default(true)
     }).optional()
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const BrowserResult = z.object({

package/src/core/processing/ContentProcessor.js

@@ -20,7 +20,7 @@ const ContentProcessorSchema = z.object({
     removeBoilerplate: z.boolean().default(true),
     preserveImageInfo: z.boolean().default(true),
     extractMetadata: z.boolean().default(true)
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const ReadabilityResult = z.object({

package/src/core/processing/PDFProcessor.js

@@ -31,8 +31,8 @@ const PDFProcessorSchema = z.object({
     parseOptions: z.object({
       normalizeWhitespace: z.boolean().default(true),
       disableCombineTextItems: z.boolean().default(false)
-    }).optional().default({})
-  }).optional().default({})
+    }).optional().prefault({})
+  }).optional().prefault({})
 });
 
 const PDFResult = z.object({

package/src/server/registerTool.js

@@ -10,7 +10,7 @@
  *   validates `structuredContent` against the schema; legacy clients keep
  *   reading the JSON-stringified `content` for backward compatibility.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  * @param {Function} withAuth  — from makeWithAuth() in src/server/withAuth.js
  * @param {Object}  descriptor
  * @param {string}  descriptor.name         — tool name (MCP identifier)

package/src/server/specHygiene.js

@@ -1,19 +1,22 @@
 /**
  * specHygiene — Phase 6 protocol-hygiene wrapper.
  *
- * Applies three MCP wire-level upgrades to an already-registered McpServer
+ * Applies four MCP wire-level upgrades to an already-registered McpServer
  * without changing how tools/prompts are declared anywhere else:
  *
  *   1. JSON Schema 2020-12 dialect stamping on every tool's inputSchema /
- *      outputSchema (the SDK's zod-to-json-schema conversion still emits
- *      draft-07-style `definitions` / `#/definitions/...` refs).
+ *      outputSchema. Under the v2 SDK + zod 4 the conversion already emits
+ *      2020-12 with `$defs`, so the `definitions` -> `$defs` rewrite below is
+ *      now defensive rather than load-bearing; it is kept because the stamping
+ *      and ordering passes still walk the same tree (Phase 4.1 kept behaviour
+ *      identical — removing the rewrite is a separate, verifiable change).
  *   2. Deterministic (alphabetical) tool ordering in tools/list, so clients
  *      that prompt-cache tools/list get stable hits across restarts.
  *   3. SEP-973 icons metadata on every tool/prompt lacking one.
  *   4. SEP-2549-style cache hints on tools/call results for a fixed
  *      allowlist of read-only, idempotent tools (see note below).
  *
- * Wiring: SDK 1.30 has no plugin hook for this, so applySpecHygiene() must be
+ * Wiring: the SDK has no plugin hook for this, so applySpecHygiene() must be
  * called once, after all server.registerTool()/registerPrompt() calls and
  * before transport.connect(). It reaches into `server.server` (the
  * underlying Protocol), captures the ListTools/CallTool/ListPrompts handlers
@@ -22,26 +25,18 @@
  * handler for the same method (confirmed from the SDK source: only
  * `assertCanSetRequestHandler`, called by McpServer's own registration path,
  * throws on a pre-existing handler; `setRequestHandler` itself does not).
+ * In v2 `setRequestHandler` takes a method string rather than a Zod schema.
  *
- * SEP-2549 note: as specified (2026-07-28 RC), `ttlMs` / `cacheScope`
- * ("public"|"private") are defined on tools/list, prompts/list,
- * resources/list, resources/read and resources/templates/list results —
- * there is no CacheableResult for tools/call. Since this deliverable asks
- * for tools/call cache hints, the same two field names are carried into a
- * namespaced `_meta` key following the SDK's own
- * `io.modelcontextprotocol/<name>` convention (see RELATED_TASK_META_KEY in
- * @modelcontextprotocol/sdk/types.js):
+ * SEP-2549 note: as specified (2026-07-28), `ttlMs` / `cacheScope`
+ * ("public"|"private") are defined on server/discover results — there is no
+ * CacheableResult for tools/call. Since this deliverable asks for tools/call
+ * cache hints, the same two field names are carried into a namespaced `_meta`
+ * key following the SDK's own `io.modelcontextprotocol/<name>` convention:
  *   result._meta["io.modelcontextprotocol/cacheable"] = { ttlMs, cacheScope }
  * This is a documented adaptation, not a key confirmed by the spec text for
  * tools/call — revisit if/when a SEP defines call-result caching explicitly.
  */
 
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-  ListPromptsRequestSchema
-} from '@modelcontextprotocol/sdk/types.js';
-
 const APPLIED = Symbol('crawlforge.specHygiene.applied');
 
 const JSON_SCHEMA_2020_12 = 'https://json-schema.org/draft/2020-12/schema';
@@ -158,7 +153,7 @@ function wrapToolsCall(innerHandler, cacheableTools) {
  * tools/prompts are registered and before transport.connect(). Idempotent:
  * a second call on the same server is a no-op.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  * @param {object} [overrides]
  * @param {{src:string,mimeType?:string,sizes?:string[]}} [overrides.icon] — default icon injected into tools/prompts lacking one
  * @param {Record<string,{ttlMs:number,cacheScope:'public'|'private'}>} [overrides.cacheableTools] — tool-name -> cache hint map for tools/call
@@ -177,16 +172,16 @@ export function applySpecHygiene(server, overrides = {}) {
 
   const innerToolsList = protocol._requestHandlers.get('tools/list');
   if (innerToolsList) {
-    protocol.setRequestHandler(ListToolsRequestSchema, wrapToolsList(innerToolsList, icon));
+    protocol.setRequestHandler('tools/list', wrapToolsList(innerToolsList, icon));
   }
 
   const innerToolsCall = protocol._requestHandlers.get('tools/call');
   if (innerToolsCall) {
-    protocol.setRequestHandler(CallToolRequestSchema, wrapToolsCall(innerToolsCall, cacheableTools));
+    protocol.setRequestHandler('tools/call', wrapToolsCall(innerToolsCall, cacheableTools));
   }
 
   const innerPromptsList = protocol._requestHandlers.get('prompts/list');
   if (innerPromptsList) {
-    protocol.setRequestHandler(ListPromptsRequestSchema, wrapPromptsList(innerPromptsList, icon));
+    protocol.setRequestHandler('prompts/list', wrapPromptsList(innerPromptsList, icon));
   }
 }

package/src/server/transports/stdio.js

@@ -2,12 +2,11 @@
  * stdio transport setup — extracted from server.js runServer().
  * Used when server is launched without the --http flag.
  */
-
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 
 /**
  * Connect the MCP server to stdio transport and log startup message.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  */
 export async function connectStdio(server) {
   const transport = new StdioServerTransport();