@selextract/mcp-selextract 0.5.0 → 0.5.3

package/README.md

@@ -64,6 +64,27 @@ Useful extras:
 - Authenticated scraping: access profile tools (create/list/update/delete/build-session)
 - Run lifecycle: `run_get`, `run_list`, `run_stop`, `run_delete`
 
+## Locale / region controls
+
+You can control language/region in a general way (works across many sites):
+
+- `task_create`
+  - `url_params`: adds or overrides query params on the URL (example: `{"hl":"en","gl":"US"}`)
+  - `options.acceptLanguage`: sets the `Accept-Language` request header
+  - `options.locale`: sets Playwright locale (example: `en-US`)
+  - `options.timezoneId`: sets Playwright timezoneId (example: `America/Los_Angeles`)
+- `run_create`
+  - `options`: same as above (applies to the run)
+  - `budgets.maxRows`: stop after N rows (example: `100`)
+
+## Field types
+
+For `task_create.fields`, `type` can be one of:
+
+- `text`, `number`, `money`, `url`, `image_url`, `html`, `unknown`
+
+Common aliases like `string`, `int`, `price`, and `link` are accepted and mapped.
+
 ## Resources (read-only)
 
 - `selextract://help` (usage guide)

package/dist/http.js

@@ -17,15 +17,18 @@ export class SelextractApiClient {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
+            const headers = {
+                accept: 'application/json',
+                // Worker accepts Bearer JWT or `sk_...` api keys; it treats `sk_...` as an API key.
+                authorization: `Bearer ${this.apiKey}`,
+            };
+            const hasBody = opts.body !== undefined;
+            if (hasBody)
+                headers['content-type'] = 'application/json';
             const resp = await this.fetchImpl(url.toString(), {
                 method: opts.method,
-                headers: {
-                    accept: 'application/json',
-                    'content-type': 'application/json',
-                    // Worker accepts Bearer JWT or `sk_...` api keys; it treats `sk_...` as an API key.
-                    authorization: `Bearer ${this.apiKey}`,
-                },
-                body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                headers,
+                body: hasBody ? JSON.stringify(opts.body) : undefined,
                 signal: controller.signal,
             });
             const contentType = resp.headers.get('content-type') ?? '';

package/dist/tools.js

@@ -11,37 +11,157 @@ function asTextResult(value, maxChars) {
         ],
     };
 }
+const AgentFieldTypeSchema = z.enum(['text', 'number', 'money', 'url', 'image_url', 'html', 'unknown']);
+function coerceAgentFieldType(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw !== 'string')
+        return undefined;
+    const cleaned = raw.trim().toLowerCase();
+    if (!cleaned)
+        return undefined;
+    const direct = AgentFieldTypeSchema.safeParse(cleaned);
+    if (direct.success)
+        return direct.data;
+    const map = {
+        string: 'text',
+        str: 'text',
+        text: 'text',
+        number: 'number',
+        int: 'number',
+        integer: 'number',
+        float: 'number',
+        double: 'number',
+        decimal: 'number',
+        currency: 'money',
+        price: 'money',
+        money: 'money',
+        link: 'url',
+        href: 'url',
+        uri: 'url',
+        url: 'url',
+        image: 'image_url',
+        img: 'image_url',
+        'image-url': 'image_url',
+        imageurl: 'image_url',
+        html: 'html',
+        markup: 'html',
+        any: 'unknown',
+        json: 'unknown',
+        unknown: 'unknown',
+    };
+    return map[cleaned];
+}
 const FieldSchema = z
-    .object({
+    .preprocess((raw) => {
+    if (!raw || typeof raw !== 'object')
+        return raw;
+    const value = raw;
+    return {
+        ...value,
+        value: value.value ?? value.description,
+        type: coerceAgentFieldType(value.type) ?? value.type,
+    };
+}, z.object({
     name: z.string().min(1).optional(),
     value: z.string().min(1).optional(),
-    type: z.string().optional(),
+    type: AgentFieldTypeSchema.optional(),
     required: z.boolean().optional(),
     examples: z.array(z.string()).optional(),
-})
+}))
     .refine((data) => Boolean(data.name?.trim() || data.value?.trim()), {
     message: 'Provide a field name (name) or a short description (value).',
     path: ['value'],
 });
+const UrlParamsSchema = z.record(z.union([z.string(), z.number(), z.boolean(), z.null()]));
+const TaskBuildOptionsSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== 'object')
+        return raw;
+    const value = raw;
+    return {
+        ...value,
+        userAgent: value.userAgent ?? value.user_agent,
+        acceptLanguage: value.acceptLanguage ?? value.accept_language,
+        timezoneId: value.timezoneId ?? value.timezone_id,
+        pageTimeoutMs: value.pageTimeoutMs ?? value.page_timeout_ms,
+    };
+}, z
+    .object({
+    userAgent: z.string().min(1).max(500).optional(),
+    acceptLanguage: z.string().min(1).max(500).optional(),
+    locale: z.string().min(1).max(64).optional(),
+    timezoneId: z.string().min(1).max(64).optional(),
+    pageTimeoutMs: z.number().int().min(1000).max(120000).optional(),
+})
+    .passthrough());
+const RunOptionsSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== 'object')
+        return raw;
+    const value = raw;
+    return {
+        ...value,
+        userAgent: value.userAgent ?? value.user_agent,
+        acceptLanguage: value.acceptLanguage ?? value.accept_language,
+        timezoneId: value.timezoneId ?? value.timezone_id,
+        waitForSelector: value.waitForSelector ?? value.wait_for_selector ?? value.wait_for,
+        delay: value.delay ?? value.delay_ms,
+    };
+}, z
+    .object({
+    timeout: z.number().int().min(1000).max(120000).optional(),
+    userAgent: z.string().min(1).max(500).optional(),
+    acceptLanguage: z.string().min(1).max(500).optional(),
+    locale: z.string().min(1).max(64).optional(),
+    timezoneId: z.string().min(1).max(64).optional(),
+    waitForSelector: z.string().min(1).max(500).optional(),
+    delay: z.number().int().min(0).max(60000).optional(),
+    retries: z.number().int().min(0).max(10).optional(),
+})
+    .passthrough());
+const RunBudgetsSchema = z
+    .object({
+    maxPages: z.number().int().min(1).max(1000).optional(),
+    maxScrolls: z.number().int().min(1).max(500).optional(),
+    maxTimeMs: z.number().int().min(1000).max(3600000).optional(),
+    maxRows: z.number().int().min(1).max(200000).optional(),
+    maxSteps: z.number().int().min(1).max(500).optional(),
+    maxRowBytes: z.number().int().min(100).max(1000000).optional(),
+})
+    .passthrough();
 const TaskCreateInputSchema = z.preprocess((raw) => {
     if (!raw || typeof raw !== 'object')
         return raw;
     const value = raw;
+    const options = value.options && typeof value.options === 'object' ? { ...value.options } : {};
+    if (value.userAgent ?? value.user_agent)
+        options.userAgent = value.userAgent ?? value.user_agent;
+    if (value.acceptLanguage ?? value.accept_language)
+        options.acceptLanguage = value.acceptLanguage ?? value.accept_language;
+    if (value.locale)
+        options.locale = value.locale;
+    if (value.timezoneId ?? value.timezone_id)
+        options.timezoneId = value.timezoneId ?? value.timezone_id;
+    if (value.pageTimeoutMs ?? value.page_timeout_ms)
+        options.pageTimeoutMs = value.pageTimeoutMs ?? value.page_timeout_ms;
     return {
         ...value,
         access_profile_id: value.access_profile_id ?? value.accessProfileId,
         field_mode: value.field_mode ?? value.fieldMode ?? value.mode,
         max_preview_rows: value.max_preview_rows ?? value.maxPreviewRows,
         goal: value.goal ?? value.description,
+        url_params: value.url_params ?? value.urlParams,
+        options: Object.keys(options).length ? options : undefined,
     };
 }, z
     .object({
     url: z.string().url(),
+    url_params: UrlParamsSchema.optional(),
     access_profile_id: z.string().uuid().optional(),
     field_mode: z.enum(['auto', 'manual']).optional(),
     goal: z.string().min(1).optional(),
     fields: z.array(FieldSchema).optional(),
     max_preview_rows: z.number().int().positive().optional().default(10),
+    options: TaskBuildOptionsSchema.optional(),
 })
     .superRefine((data, ctx) => {
     const effectiveFieldMode = data.field_mode ?? (data.fields?.length ? 'manual' : 'auto');
@@ -139,17 +259,48 @@ const AccessProfileBuildSessionInputSchema = z.preprocess((raw) => {
     hint: z.string().min(1).optional(),
 }));
 export const ToolInputs = {
-    health: z.object({}),
     // Tasks (AI-built)
     task_create: TaskCreateInputSchema,
     task_build_status: TaskBuildStatusInputSchema,
     task_publish: TaskPublishInputSchema,
     task_draft_delete: TaskDraftDeleteInputSchema,
     // Runs
-    run_create: z.object({
+    run_create: z.preprocess((raw) => {
+        if (!raw || typeof raw !== 'object')
+            return raw;
+        const value = raw;
+        const options = value.options && typeof value.options === 'object' ? { ...value.options } : {};
+        if (value.userAgent ?? value.user_agent)
+            options.userAgent = value.userAgent ?? value.user_agent;
+        if (value.acceptLanguage ?? value.accept_language)
+            options.acceptLanguage = value.acceptLanguage ?? value.accept_language;
+        if (value.locale)
+            options.locale = value.locale;
+        if (value.timezoneId ?? value.timezone_id)
+            options.timezoneId = value.timezoneId ?? value.timezone_id;
+        if (value.timeout)
+            options.timeout = value.timeout;
+        if (value.waitForSelector ?? value.wait_for_selector ?? value.wait_for)
+            options.waitForSelector = value.waitForSelector ?? value.wait_for_selector ?? value.wait_for;
+        if (value.delay ?? value.delay_ms)
+            options.delay = value.delay ?? value.delay_ms;
+        if (value.retries)
+            options.retries = value.retries;
+        return {
+            ...value,
+            pagination: value.pagination ?? value.page,
+            options: Object.keys(options).length ? options : undefined,
+        };
+    }, z
+        .object({
         task_id: z.string().uuid(),
         max_runtime_seconds: z.number().int().min(30).max(3600).optional(),
-    }),
+        pagination: z.record(z.any()).optional(),
+        budgets: RunBudgetsSchema.optional(),
+        options: RunOptionsSchema.optional(),
+        test: z.boolean().optional(),
+    })
+        .passthrough()),
     run_get: z.object({
         run_id: z.string().uuid(),
     }),
@@ -183,11 +334,6 @@ export const ToolInputs = {
 };
 export function toolDefinitions() {
     return [
-        {
-            name: 'health',
-            description: 'Health check for the Selextract Worker API.',
-            inputSchema: { type: 'object', properties: {}, required: [] },
-        },
         // Tasks (AI-built)
         {
             name: 'task_create',
@@ -196,11 +342,23 @@ export function toolDefinitions() {
                 type: 'object',
                 properties: {
                     url: { type: 'string', description: 'The page to analyze.' },
+                    url_params: { type: 'object', description: 'Optional query params to add/override on the URL (ex: {"hl":"en","gl":"US"}).' },
                     access_profile_id: { type: 'string', description: 'Optional access profile ID for logged-in/session scraping.' },
                     field_mode: { type: 'string', enum: ['auto', 'manual'], description: 'auto = infer fields; manual = use provided fields.' },
                     goal: { type: 'string', description: 'Optional short description of what to extract (helps in auto mode).' },
                     fields: { type: 'array', items: { type: 'object' }, description: 'Fields to extract (required in manual mode).' },
                     max_preview_rows: { type: 'number', description: 'How many sample rows to generate in the preview (default: 10).' },
+                    options: {
+                        type: 'object',
+                        description: 'Optional browsing controls (language/region, time zone, user agent, timeouts).',
+                        properties: {
+                            userAgent: { type: 'string' },
+                            acceptLanguage: { type: 'string', description: 'Sets the Accept-Language request header.' },
+                            locale: { type: 'string', description: 'Sets Playwright locale (ex: en-US).' },
+                            timezoneId: { type: 'string', description: 'Sets Playwright timezoneId (IANA, ex: America/Los_Angeles).' },
+                            pageTimeoutMs: { type: 'number', description: 'Page timeout (ms) used during the build.' },
+                        },
+                    },
                 },
                 required: ['url'],
             },
@@ -245,6 +403,23 @@ export function toolDefinitions() {
                 properties: {
                     task_id: { type: 'string', description: 'Task ID.' },
                     max_runtime_seconds: { type: 'number', description: 'Optional hard limit for run time (seconds).' },
+                    pagination: { type: 'object', description: 'Optional pagination override for this run only.' },
+                    budgets: { type: 'object', description: 'Optional safety limits for this run only (ex: {"maxRows":100}).' },
+                    options: {
+                        type: 'object',
+                        description: 'Optional browsing controls (language/region, time zone, user agent, timeouts).',
+                        properties: {
+                            timeout: { type: 'number', description: 'Navigation/step timeout (ms).' },
+                            userAgent: { type: 'string' },
+                            acceptLanguage: { type: 'string', description: 'Sets the Accept-Language request header.' },
+                            locale: { type: 'string', description: 'Sets Playwright locale (ex: en-US).' },
+                            timezoneId: { type: 'string', description: 'Sets Playwright timezoneId (IANA, ex: America/Los_Angeles).' },
+                            waitForSelector: { type: 'string', description: 'Wait for a selector after navigation.' },
+                            delay: { type: 'number', description: 'Extra delay (ms) after navigation.' },
+                            retries: { type: 'number', description: 'Retries for certain flow steps (0-10).' },
+                        },
+                    },
+                    test: { type: 'boolean', description: 'If true, reduces pagination (best-effort) for a quick smoke run.' },
                 },
                 required: ['task_id'],
             },
@@ -373,13 +548,6 @@ export function toolDefinitions() {
 }
 export function toolHandlers(api, maxChars) {
     const handlers = {
-        health: async () => {
-            const result = await api.request({
-                method: 'GET',
-                path: '/health',
-            });
-            return asTextResult(result, maxChars);
-        },
         task_create: async (raw) => {
             const input = ToolInputs.task_create.parse(raw);
             const effectiveFieldMode = input.field_mode ?? (input.fields?.length ? 'manual' : 'auto');
@@ -388,6 +556,8 @@ export function toolHandlers(api, maxChars) {
                 path: '/v1/agent/extractions/build',
                 body: {
                     url: input.url,
+                    ...(input.url_params ? { urlParams: input.url_params } : {}),
+                    ...(input.options ? { options: input.options } : {}),
                     access_profile_id: input.access_profile_id,
                     field_mode: effectiveFieldMode,
                     goal: input.goal,
@@ -439,10 +609,17 @@ export function toolHandlers(api, maxChars) {
         },
         run_create: async (raw) => {
             const input = ToolInputs.run_create.parse(raw);
+            const body = {
+                ...(input.max_runtime_seconds ? { max_runtime_seconds: input.max_runtime_seconds } : {}),
+                ...(input.pagination ? { pagination: input.pagination } : {}),
+                ...(input.budgets ? { budgets: input.budgets } : {}),
+                ...(input.options ? { options: input.options } : {}),
+                ...(input.test === true ? { test: true } : {}),
+            };
             const result = await api.request({
                 method: 'POST',
                 path: `/v1/tasks/${input.task_id}/runs`,
-                body: input.max_runtime_seconds ? { max_runtime_seconds: input.max_runtime_seconds } : {},
+                body: Object.keys(body).length ? body : {},
             });
             return asTextResult(result, maxChars);
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selextract/mcp-selextract",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Selextract Cloud MCP server (local stdio) for calling the Selextract Worker API",
   "license": "UNLICENSED",
   "type": "module",