feat: add actions option to mql, core, and mcp - #9
Conversation
Type and validate the upcoming browser actions API surface so clients can pass ordered interaction steps with semantic locators before the engine ships. Co-authored-by: Cursor <cursoragent@cursor.com>
📝 WalkthroughWalkthroughThe PR adds ordered browser action types, MCP validation, tool documentation, and MQL coverage for action requests and dotted-key URL serialization. ChangesBrowser actions
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant Client
participant browserSchema
participant MQLURLBuilder
participant API
Client->>browserSchema: Submit actions array
browserSchema->>browserSchema: Validate action variants
browserSchema-->>MQLURLBuilder: Parsed actions
MQLURLBuilder->>MQLURLBuilder: Flatten actions into dotted keys
MQLURLBuilder->>API: Send indexed action parameters
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/mcp/src/schemas.js`:
- Around line 253-258: The click and fill schemas currently allow missing or
conflicting locator strategies. Add refinements to both action schemas requiring
exactly one strategy, counting role with optional name as a single strategy and
rejecting name without role; preserve the existing locator field definitions and
strictness.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 3a4ccc85-5d42-46f0-8153-8ae39f7dce07
⛔ Files ignored due to path filters (2)
packages/mql/dist/index.d.tsis excluded by!**/dist/**packages/mql/test/snapshots/get-api-url.mjs.snapis excluded by!**/*.snap
📒 Files selected for processing (11)
packages/core/src/index.d.tspackages/core/test/index.test-d.tspackages/mcp/src/schemas.jspackages/mcp/src/tools/function.jspackages/mcp/src/tools/html.jspackages/mcp/src/tools/pdf.jspackages/mcp/src/tools/screenshot.jspackages/mcp/test/schemas.test.jspackages/mql/test/get-api-url.mjspackages/mql/test/index.test-d.tspackages/mql/test/snapshots/get-api-url.mjs.md
| z | ||
| .object({ | ||
| type: z.literal('click'), | ||
| ...locatorFields | ||
| }) | ||
| .strict(), |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '5,29p' packages/core/src/index.d.ts
sed -n '231,306p' packages/mcp/src/schemas.jsRepository: microlinkhq/microlink
Length of output: 2957
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- locate package files ---'
fd -a '^(package\.json|index\.d\.ts|schemas\.js)$' packages/mcp packages/core | sed 's#^\./##'
printf '%s\n' '--- package metadata for packages/mcp ---'
cat packages/mcp/package.json | sed -n '1,120p'
printf '%s\n' '--- relevant schema sections ---'
sed -n '1,80p' packages/mcp/src/schemas.js
sed -n '215,306p' packages/mcp/src/schemas.js
printf '%s\n' '--- inspect references to locator validation / ActionLocator ---'
rg -n "locatorFields|ActionLocator|mutual|exclusiv|role\?|name" packages -SRepository: microlinkhq/microlink
Length of output: 42263
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- lockfile zod version references ---'
if [ -f package-lock.json ]; then
node -e 'const lock=require("./package-lock.json"); for (const [k,v] of Object.entries(lock.packages||{}).filter(([k,v]) => k && v.version)?.entries) if (k.includes("zod")) console.log(`${k}: ${v.version}`)'
fi
printf '%s\n' '--- deterministic schema behavior probe using repo package files ---'
python3 - <<'PY'
from pathlib import Path
import re
schema = Path('packages/mcp/src/schemas.js').read_text()
locator_fields = dict(re.search(r'const locatorFields = \{(?P<body>.*?)\n\}\n(? =const actionSchema)', schema, re.S).group('body'))
click = re.search(r'z\s*\.\s*object\(\{\s*type:\s* z\.literal\('click'\'),(?P<body>.*?)\}\.strict\(\),', schema, re.S)
fill = re.search(r'z\s*\.\s*object\(\{\s*type:\s*z\.literal\('fill'\'),(?P<body>.*?)\}\.strict\(\),', schema, re.S)
core_type = Path('packages/core/src/index.d.ts').read_text()
print('locator_fields_are_optional:', all('optional()' in value for value in locator_fields.values()))
print('click_accepts_no_strategy:', click is not None and '{ type: z.literal("click") }' in click.group(0))
print('fill_accepts_no_strategy:', fill is not None and '{ type: z.literal("fill") }' in fill.group(0))
print('click_accepts_conflicting_selector_text_example:', bool(click and re.search(r'click.*selector.*text', click.group(0), re.S)))
print('fill_accepts_conflicting_selector_text_example:', bool(fill and re.search(r'fill.*selector.*text', fill.group(0), re.S)))
print('core_click_requires_actionlocator:' ,bool(re.search(r'\(\{\s*type:\s*\'click\'\s*\}\s*&\s*ActionLocator\)', core_type)))
print('core_fill_requires_actionlocator:', bool(re.search(r'\(\{\s*type:\s*\'fill\'\s*,\s*value:\s*string\s*\}\s*&\s*ActionLocator\)', core_type)))
PYRepository: microlinkhq/microlink
Length of output: 514
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
import re
schema = Path('packages/mcp/src/schemas.js').read_text()
locator_body = re.search(r"const locatorFields = \{(?P<body>.*?)\n\}\n", schema, re.S).group('body')
locator_fields = {}
for m in re.finditer(r'(\w+):\s*z\.str.*?\.optional?\(\)', locator_body):
locator_fields[m.group(1)] = m.group(0).rstrip(',')
click = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('click'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S, flags=re.S)
fill = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('fill'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
core = Path('packages/core/src/index.d.ts').read_text()
print('all_locator_fields_optional:', all('optional()' in v for v in locator_fields.values()))
print('click_accepts_no_locator_strategy:', bool(click) and '{ type: z.literal('click') }' in click.group(0))
print('fill_accepts_no_locator_strategy:', bool(fill) and '{ type: z.literal('fill') }' in fill.group(0))
print('click_accepts_conflicting_selector_and_text:', bool(click) and 'selector' in click.group(0) and 'text' in click.group(0))
print('fill_accepts_conflicting_selector_and_text:', bool(fill) and 'selector' in fill.group(0) and 'text' in fill.group(0))
print('core_click_requires_actionlocator:', bool(re.search(r"\(\{\s*type:\s*'click'\s*\}\s*&\s*ActionLocator\)", core)))
print('core_fill_requires_actionlocator:', bool(re.search(r"\(\{\s*type:\s*'fill',\s*value:\s*string\s*\}\s*&\s*ActionLocator\)", core)))
PYRepository: microlinkhq/microlink
Length of output: 413
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
import re
schema = Path('packages/mcp/src/schemas.js').read_text()
locator_body = re.search(r"const locatorFields = \{(?P<body>.*?)\n\}\n", schema, re.S).group('body')
locator_fields = {}
for m in re.finditer(rr"(\w+):\s*z\(.*?\)\.optional\(\)", locator_body):
locator_fields[m.group(1)] = m.group(0).rstrip(',')
click = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('click'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
fill = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('fill'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
core = Path('packages/core/src/index.d.ts').read_text().splitlines()
print('all_locator_fields_optional:', all('optional()' in v for v in locator_fields.values()))
print('locator_fields', locator_fields)
print('click_accepts_no_locator_strategy:', bool(click) and "'click'" in click.group(0) and '{ type:' not in click.group(1).strip())
print('fill_accepts_no_locator_strategy:', bool(fill))
print('click_accepts_conflicting_selector_and_text:', bool(click) and 'selector' in click.group(0) and 'text' in click.group(0))
print('fill_accepts_conflicting_selector_and_text:', bool(fill) and 'selector' in fill.group(0) and 'text' in fill.group(0))
for i,l in enumerate(core):
if "type: 'click'" in l or "type: 'fill'" in l or "ActionLocator =" in l:
print(f'core[{i}]: {l}')
PYRepository: microlinkhq/microlink
Length of output: 318
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - "$@" <<'PY'
from pathlib import Path
import re
schema = Path('packages/mcp/src/schemas.js').read_text()
locator_body = re.search(r"const locatorFields = \{(?P<body>.*?)\n\}\n", schema, re.S).group('body')
locator_fields = {}
for m in re.finditer(r"(\w+):\s*z\..*?\)\.optional\(\)", locator_body, re.S):
locator_fields[m.group(1)] = m.group(0).rstrip(',')
click = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('click'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
fill = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('fill'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
core = Path('packages/core/src/index.d.ts').read_text().splitlines()
print('all_locator_fields_optional:', all('optional()' in v for v in locator_fields.values()))
print('locator_fields', locator_fields)
print('click_accepts_no_locator_strategy:', bool(click) and '{ type: z.literal('click') }' in click.group(0))
print('fill_accepts_no_locator_strategy:', bool(fill) and 'value: z.string()' in fill.group(0))
print('click_accepts_conflicting_selector_and_text:', bool(click) and 'selector' in click.group(0) and 'text' in click.group(0))
print('fill_accepts_conflicting_selector_and_text:', bool(fill) and 'selector' in fill.group(0) and 'text' in fill.group(0))
for i,l in enumerate(core):
if "type: 'click'" in l or "type: 'fill'" in l or "ActionLocator =" in l:
print(f'core[{i}]: {l}')
PYRepository: microlinkhq/microlink
Length of output: 413
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 <<'PY'
from pathlib import Path
import re
schema = Path('packages/mcp/src/schemas.js').read_text()
locator_body = re.search(r"const locatorFields = \{(?P<body>.*?)\n\}\n", schema, re.S).group('body')
locator_fields = {}
for m in re.finditer(r"(\w+):\s*z\..*?\)\.optional\(\)", locator_body, re.S):
locator_fields[m.group(1)] = m.group(0).rstrip(',')
click = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('click'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
fill = re.search(r"z\s*\.\s*object\(\{\s*type:\s*z\.literal\('fill'\'),(?P<body>.*?)\}\.strict\(\)", schema, re.S)
core = Path('packages/core/src/index.d.ts').read_text().splitlines()
action_locator = '\n'.join(core[core.index(next(l for l in core if 'ActionLocator =' in l)): next((i for i,l in enumerate(core) if 'export type Action' in l), len(core))])
print('all_locator_fields_optional=', all('optional()' in v for v in locator_fields.values()))
print('locator_fields=', sorted(locator_fields))
print('click_accepts_no_locator_strategy=', '{ type: z.literal('click') }' in click.group(0) if click else False)
print('click_accepts_conflicting_selector_and_text=', bool(click) and 'selector' in click.group(0) and 'text' in click.group(0))
print('fill_accepts_conflicting_selector_and_text=', bool(fill) and 'selector' in fill.group(0) and 'text' in fill.group(0))
print('core_action_locator_clause=', action_locator[:600].replace('\n',' '))
PYRepository: microlinkhq/microlink
Length of output: 401
🌐 Web query:
Microlink API ActionLocator click fill schema selector role name text label placeholder testId alt action options
💡 Result:
The term ActionLocator does not exist as a standard parameter or feature in the Microlink API. Microlink uses a declarative, query-string-based API to handle browser automation and data extraction, rather than a locator-based system like those found in testing frameworks such as Playwright [1][2][3]. For browser interactions in Microlink, you instead use specific interaction parameters [2]: * Click: You perform clicks by passing a CSS selector to the click parameter (e.g., click='.my-button') [2]. * Fill/Input: Microlink does not have a dedicated fill parameter for declarative browser interaction. If you need to fill forms or perform complex interactions that go beyond simple clicks or scrolls, you should use the function parameter to run custom JavaScript code with full Puppeteer access [2][4]. * Data Extraction: You define the schema for data you want to extract using the data parameter [5]. This object uses selectors (e.g., selector, selectorAll) and attributes (attr) to target specific elements on a page [5][6]. The attributes you listed (role, name, text, label, placeholder, testId, alt) are standard DOM accessibility or testing attributes commonly used as CSS selectors (e.g., [role='button'], [placeholder='email']) [2]. You can use these as values for the selector fields within your Microlink data rules or click parameters by utilizing standard CSS attribute selector syntax [5][2]. If you are seeing references to ActionLocator, it is likely related to Playwright's internal trace tools or custom implementations in other frameworks rather than the Microlink API itself [7][8][9].
Citations:
- 1: https://microlink.io/skills/microlink-api
- 2: https://microlink.io/features/automation
- 3: https://microlink.io/docs/api/getting-started/mcp
- 4: https://microlink.io/docs/guides/function
- 5: https://microlink.io/docs/guides/data-extraction
- 6: https://glama.ai/mcp/servers/microlinkhq/mcp/schema
- 7: https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/traceActions.ts
- 8: https://github.com/MarketSquare/robotframework-browser/blob/main/node/playwright-wrapper/locator-handler.ts
- 9: microsoft/playwright@b455769
🌐 Web query:
packages/mql/src ActionLocator mql index.js "ActionLocator" "click" "fill"
💡 Result:
The terms "ActionLocator", "mql", "index.js", "click", and "fill" appear in several distinct technical contexts, as there is no single standardized library or framework that exclusively combines all these specific components. 1. Playwright and Testing Frameworks: In many automation and testing projects (such as robotframework-browser), "ActionLocator" is a conceptual or class name used to find UI elements [1]. Developers often use Playwright’s.click and.fill methods to interact with these located elements [1][2]. 2. MQL (MetaQuotes Language) Compile Actions: There is a GitHub repository named MQL-Compile-Action which contains an index.js file [3][4]. This project is used to compile MQL files (used in algorithmic trading platforms) and manages this process via build scripts [3]. 3. ObjectStack / UI Frameworks: Some frameworks, like ObjectStack, utilize an ActionLocation concept to define where UI actions (such as buttons or menu items) surface in an application [5][6]. 4. C# Web Frameworks: In custom or educational C# web framework implementations, an ActionLocator component is frequently used within middleware to resolve incoming requests to specific controller actions [7]. 5. Specialized Systems: The term "ActionLocator" also appears in specialized software, such as the UR robot operating system (in the context of command processing) [8] or game development frameworks (like Planeshift) for defining interactive locations [9]. If you are working with a specific codebase or trying to resolve a particular error, you are likely looking at one of these implementations rather than a unified industry-standard package.
Citations:
- 1: https://github.com/MarketSquare/robotframework-browser/blob/main/node/playwright-wrapper/locator-handler.ts
- 2: codephage2020/openobserve@605e007
- 3: Expand action to compile MQL files FX31337/MQL-Compile-Action#3
- 4: Rebuilt dist/index.js due to issues FX31337/MQL-Compile-Action#40
- 5: https://github.com/objectstack-ai/objectstack/blob/main/content/docs/protocol/objectui/actions.mdx
- 6: https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/action.zod.ts
- 7: https://www.cnblogs.com/qinganning/p/19160060
- 8: https://www.gm7.org/archives/121169
- 9: https://vaikene.ee/planeshift/api/classpawsGMActionWindow.html
🌐 Web query:
@microlink/mql ActionLocator click fill selector role name text zod validation
💡 Result:
The @microlink/mql library interacts with the Microlink API to perform web scraping and browser automation [1][2]. Based on official documentation, the concepts of "ActionLocator," "role," "name," and "text" as specific, native parameters for clicking or filling elements are not part of the standard @microlink/mql API [3][4][5]. Instead, Microlink uses the following mechanisms: 1. Interaction (Clicking/Filling): The click parameter is used for interaction before data extraction [6]. It accepts a CSS selector as a string (or an array of strings) to target the elements to be clicked [6][3]. Example: const { data } = await mql('https://example.com', { click: '.button-selector' }) 2. Data Extraction (Selectors): Data extraction is defined via the data parameter, which uses CSS selectors [4][7]. - selector: Specifies the target element (CSS selector) [8][5]. - attr: Specifies the attribute to extract, such as 'text', 'href', 'src', or 'html' [8][9][5]. - type: Used for validation and normalization of the extracted value (e.g., 'string', 'number', 'url', 'image') [10][9][5]. 3. Validation: Microlink does not natively integrate Zod for validation within the request configuration [10][5]. Instead, it uses a built-in type property in the data extraction rule to ensure the extracted value matches a specific format (e.g., 'number', 'date') [10][9]. If the value does not match the expected type, it is considered invalid and may be discarded [10][11]. Note: Some third-party agentic frameworks or automation wrappers (like the example found in the Catcher repository) may implement higher-level abstractions using terms like "role", "name", and "text" to construct Playwright locators internally, but these are not native features of the @microlink/mql library itself [12].
Citations:
- 1: https://microlink.io/docs/mql/getting-started/overview
- 2: https://microlink.io/docs/mql/getting-started/api
- 3: https://microlink.io/docs/api/parameters/click
- 4: https://microlink.io/skills/microlink-api
- 5: https://microlink.io/docs/api/parameters/data
- 6: https://microlink.io/features/automation
- 7: https://microlink.io/docs/mql/rules/basic
- 8: https://microlink.io/docs/mql/data/selector
- 9: https://microlink.io/docs/guides/data-extraction/defining-rules
- 10: https://microlink.io/docs/mql/data/type
- 11: https://microlink.io/docs/guides/data-extraction/troubleshooting.md
- 12: https://github.com/Catcher2026/Catcher/blob/main/electron/actions.ts
Require one locator strategy for click and fill.
The locatorFields object makes every locator field optional, so these action schemas accept targetless actions and compatible conflicting strategies such as selector plus text. This diverges from ActionLocator, which allows only one strategy. Add a refinement for both schemas that requires exactly one strategy; treat role plus optional name as one strategy, and reject name when role is absent.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/mcp/src/schemas.js` around lines 253 - 258, The click and fill
schemas currently allow missing or conflicting locator strategies. Add
refinements to both action schemas requiring exactly one strategy, counting role
with optional name as a single strategy and rejecting name without role;
preserve the existing locator field definitions and strictness.
1 participant
Summary
Action/ActionLocatortypes andactions?: Action[]on@microlink/mqlMicrolinkApiOptions, with flatten snapshot + tsd coverageactionsonmicrolink.iocoreOptions(screenshot/pdf inherit)actionsdiscriminated union to@microlink/mcpbrowserSchemaand preferactionsin screenshot/pdf/html/function tool descriptionsNo wire-format serializer changes —
flattiealready emitsactions.N.*and the API reconstitutes vianestie.Test plan
ava test/get-api-url.mjs(includes actions flatten snapshot)tsdin mql and corenode --test packages/mcp/test/schemas.test.js(53 passing)Made with Cursor
Summary by CodeRabbit
New Features
Enhancements