crawlforge-mcp-server 6.1.0 → 6.3.0

package/src/tools/tracking/trackChanges/schema.js

@@ -6,8 +6,17 @@
 
 import { z } from 'zod';
 
-export const TrackChangesSchema = z.object({
-  url: z.string().url().optional(),
+/**
+ * The raw input shape — one declaration (G5). server.js spreads it, with the
+ * shared compliance params, into the registered inputSchema, so the
+ * `.describe()` strings a client sees and the defaults the tool validates
+ * with cannot drift apart again (they had: the `email` block and the default
+ * `excludeSelectors` never reached tools/list). `.prefault({})` on the option
+ * objects fills their inner defaults when the object is omitted; zod 4's
+ * `.default({})` would not.
+ */
+export const TRACK_CHANGES_INPUT_SHAPE = {
+  url: z.string().url().optional().describe("The URL to track changes for (optional for list_scheduled_monitors)"),
   operation: z.enum([
     'create_baseline',
     'compare',
@@ -22,13 +31,10 @@ export const TrackChangesSchema = z.object({
     'create_alert_rule',
     'generate_trend_report',
     'get_monitoring_templates'
-  ]).default('compare'),
-
-  content: z.string().optional(),
-  html: z.string().optional(),
+  ]).default('compare').describe("Tracking operation to perform"),
 
-  respect_robots: z.boolean().optional(),
-  user_agent: z.string().optional(),
+  content: z.string().optional().describe("Content to compare against baseline"),
+  html: z.string().optional().describe("HTML content to compare against baseline"),
 
   trackingOptions: z.object({
     granularity: z.enum(['page', 'section', 'element', 'text']).default('section'),
@@ -48,7 +54,7 @@ export const TrackChangesSchema = z.object({
       moderate: z.number().min(0).max(1).default(0.3),
       major: z.number().min(0).max(1).default(0.7)
     }).optional()
-  }).optional().prefault({}),
+  }).optional().prefault({}).describe("Options for how changes are tracked and compared"),
 
   monitoringOptions: z.object({
     enabled: z.boolean().default(false),
@@ -59,7 +65,7 @@ export const TrackChangesSchema = z.object({
     enableWebhook: z.boolean().default(false),
     webhookUrl: z.string().url().optional(),
     webhookSecret: z.string().optional()
-  }).optional().prefault({}),
+  }).optional().prefault({}).describe("Monitoring schedule and notification settings"),
 
   storageOptions: z.object({
     enableSnapshots: z.boolean().default(true),
@@ -67,7 +73,7 @@ export const TrackChangesSchema = z.object({
     maxHistoryEntries: z.number().min(1).max(1000).default(100),
     compressionEnabled: z.boolean().default(true),
     deltaStorageEnabled: z.boolean().default(true)
-  }).optional().prefault({}),
+  }).optional().prefault({}).describe("Storage and history retention settings"),
 
   queryOptions: z.object({
     limit: z.number().min(1).max(500).default(50),
@@ -76,7 +82,7 @@ export const TrackChangesSchema = z.object({
     endTime: z.number().optional(),
     includeContent: z.boolean().default(false),
     significanceFilter: z.enum(['all', 'minor', 'moderate', 'major', 'critical']).optional()
-  }).optional().prefault({}),
+  }).optional().prefault({}).describe("Query options for history and stats retrieval"),
 
   notificationOptions: z.object({
     email: z.object({
@@ -99,17 +105,19 @@ export const TrackChangesSchema = z.object({
       channel: z.string().optional(),
       username: z.string().optional()
     }).optional()
-  }).optional(),
+  }).optional().describe("Notification configuration for webhooks, Slack and email (email is sent by hosted monitors only)"),
 
   scheduledMonitorOptions: z.object({
-    schedule: z.string().optional(),
+    schedule: z.string().optional().describe("Optional cron expression (power users)"),
     templateId: z.string().optional(),
     enabled: z.boolean().default(true),
-    interval: z.number().min(60000).optional(),
-    goal: z.string().optional(),
-    monitorId: z.string().optional(),
-    notificationThreshold: z.enum(['minor', 'moderate', 'major', 'critical']).optional()
-  }).optional(),
+    interval: z.number().min(60000).optional().describe("Polling interval in ms (default 1h)"),
+    goal: z.string().optional().describe("Plain-English alert goal; an LLM judges whether a change matches (degrades to threshold if no LLM)"),
+    monitorId: z.string().optional().describe("Monitor id for stop_scheduled_monitor"),
+    notificationThreshold: z.enum(['minor', 'moderate', 'major', 'critical']).optional(),
+    hosted: z.boolean().default(false).describe("Run the monitor on CrawlForge's servers: it fires from the hosted scheduler whether or not this process is alive and sends email and signed webhooks. Each check bills 3 credits per compared target from the account; blocked and errored targets are free. Default false = local, in-process."),
+    name: z.string().min(1).max(80).optional().describe("Display name for a hosted monitor (default: the URL host)")
+  }).optional().describe("Scheduled monitoring: recurring compare + notify, optional plain-English goal"),
 
   alertRuleOptions: z.object({
     ruleId: z.string().optional(),
@@ -117,7 +125,7 @@ export const TrackChangesSchema = z.object({
     actions: z.array(z.enum(['webhook', 'email', 'slack'])).optional(),
     throttle: z.number().min(0).optional(),
     priority: z.enum(['low', 'medium', 'high']).optional()
-  }).optional(),
+  }).optional().describe("Alert rule configuration for change notifications"),
 
   exportOptions: z.object({
     format: z.enum(['json', 'csv']).default('json'),
@@ -125,11 +133,17 @@ export const TrackChangesSchema = z.object({
     endTime: z.number().optional(),
     includeContent: z.boolean().default(false),
     includeSnapshots: z.boolean().default(false)
-  }).optional(),
+  }).optional().describe("Export options for change history data"),
 
   dashboardOptions: z.object({
     includeRecentAlerts: z.boolean().default(true),
     includeTrends: z.boolean().default(true),
     includeMonitorStatus: z.boolean().default(true)
-  }).optional()
+  }).optional().describe("Dashboard display options")
+};
+
+export const TrackChangesSchema = z.object({
+  ...TRACK_CHANGES_INPUT_SHAPE,
+  respect_robots: z.boolean().optional(),
+  user_agent: z.string().optional()
 });

package/src/utils/schemaValidate.js

@@ -0,0 +1,139 @@
+/**
+ * Shared JSON-Schema → zod validation.
+ *
+ * Lifted out of `src/tools/extract/extractWithLlm.js`, where it was local and
+ * unexported, so that every consumer of LLM-decoded JSON validates the same
+ * way. `LLMManager.validateAgainstSchema` used to hand-roll its own check that
+ * only ever looked one level deep: `{countries: ["a string", "another"]}`
+ * against `{countries: {type: 'array', items: {type: 'object'}}}` reported
+ * `valid: true` because the top-level value was, in fact, an array (R19).
+ */
+
+import { z } from 'zod';
+
+/**
+ * Build a zod validator from a JSON-Schema-like hint. Best-effort: unknown
+ * shapes fall back to `z.any()` so validation never rejects on constructs the
+ * converter does not understand.
+ */
+export function jsonSchemaToZod(schema) {
+  if (!schema || typeof schema !== 'object') return z.any();
+
+  // Flat hint map (no `type`/`properties`) → treat values as field hints.
+  const isJsonSchema = schema.type || schema.properties || schema.items;
+  if (!isJsonSchema) {
+    const shape = {};
+    for (const [key, val] of Object.entries(schema)) {
+      shape[key] = jsonSchemaToZod(typeof val === 'string' ? { type: val } : val).nullable().optional();
+    }
+    return z.object(shape).passthrough();
+  }
+
+  switch (schema.type) {
+    case 'string': return z.string();
+    case 'number':
+    case 'integer': return z.number();
+    case 'boolean': return z.boolean();
+    case 'null': return z.null();
+    case 'array': return z.array(schema.items ? jsonSchemaToZod(schema.items) : z.any());
+    case 'object': {
+      const shape = {};
+      const required = Array.isArray(schema.required) ? schema.required : [];
+      for (const [key, val] of Object.entries(schema.properties || {})) {
+        const field = jsonSchemaToZod(val);
+        // The model is told to answer null for a field the content never
+        // states, so null is the honest answer for a field the schema does
+        // not require — not a type violation. A required field stays strict:
+        // null there is exactly what the caller needs to hear about.
+        shape[key] = required.includes(key) ? field : field.nullable().optional();
+      }
+      return z.object(shape).passthrough();
+    }
+    default: return z.any();
+  }
+}
+
+/**
+ * Validate parsed output against the schema hint.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgainstSchema(parsed, schema) {
+  try {
+    const validator = jsonSchemaToZod(schema);
+    const result = validator.safeParse(parsed);
+    if (result.success) return { valid: true, errors: [] };
+    return {
+      valid: false,
+      errors: result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+    };
+  } catch {
+    // Converter failure should not block extraction — treat as unvalidated.
+    return { valid: true, errors: [] };
+  }
+}
+
+/**
+ * Validate against a schema and report problems per field, in the wording
+ * callers see in tool output: "Missing required field: x" and
+ * `Field "x": expected number, got string`, with a dotted path for anything
+ * nested (`Field "countries.0.capital": ...`).
+ *
+ * Same structural check as validateAgainstSchema — this differs only in how
+ * the failures are worded, and in also checking `enum`, which the zod
+ * converter does not carry.
+ *
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateFieldsAgainstSchema(data, schema) {
+  const required = Array.isArray(schema?.required) ? schema.required : [];
+  const properties = schema?.properties || {};
+  const errors = [];
+
+  let issues = [];
+  try {
+    const result = jsonSchemaToZod(schema).safeParse(data);
+    if (!result.success) issues = result.error.issues;
+  } catch {
+    // The converter is best-effort and falls back to z.any() rather than
+    // throwing, so this is unreachable in practice. Treat it as unvalidated
+    // rather than failing an extraction on a validator bug.
+    return { valid: true, errors: [] };
+  }
+
+  for (const issue of issues) {
+    const path = issue.path;
+    const value = path.reduce((acc, key) => (acc == null ? undefined : acc[key]), data);
+    // A required field the decoder left null is "not filled in", the same as
+    // absent — the caller wants to hear it is missing, not that null is the
+    // wrong type. Optional nulls never reach here: the converter allows them.
+    if (path.length === 1 && required.includes(path[0]) && (value === null || value === undefined)) {
+      errors.push(`Missing required field: ${path[0]}`);
+      continue;
+    }
+    const where = path.length ? path.join('.') : '(root)';
+    if (issue.code === 'invalid_type' && issue.expected) {
+      const actualType = Array.isArray(value) ? 'array' : typeof value;
+      errors.push(`Field "${where}": expected ${issue.expected}, got ${actualType}`);
+    } else {
+      errors.push(`Field "${where}": ${issue.message}`);
+    }
+  }
+
+  // The converter carries no `enum`, so that check stays here. Top level only.
+  for (const [key, fieldSchema] of Object.entries(properties)) {
+    const value = data?.[key];
+    if (value === null || value === undefined) continue;
+    if (fieldSchema?.enum && !fieldSchema.enum.includes(value)) {
+      errors.push(`Field "${key}": value "${value}" not in enum ${JSON.stringify(fieldSchema.enum)}`);
+    }
+  }
+
+  // A malformed array can raise one issue per element; the full list is pushed
+  // into tool output, so cap it.
+  const MAX_REPORTED = 10;
+  const reported = errors.length > MAX_REPORTED
+    ? [...errors.slice(0, MAX_REPORTED), `…and ${errors.length - MAX_REPORTED} more validation errors`]
+    : errors;
+
+  return { valid: errors.length === 0, errors: reported };
+}