Skip to main content
Glama
roxy-gg

JevRelay

by roxy-gg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

JevRelay

Open-source local MCP runtime for fast browser automation.

An AI creates a declarative Jev Script. JevRelay validates it, runs Playwright locally, and calls the configured inference provider only for explicit bounded decisions.

Claude / ChatGPT / Roxy
-> local @jevrelay/mcp process
-> Playwright actions on the user's computer
-> optional TypeSafe, OpenRouter, or JevRelay decision call

Browser cookies, page state, and computer control stay local.

Status

This is an early MVP. It supports:

  • MCP over stdio.

  • Chromium through Playwright.

  • Declarative Jev Script validation.

  • Local actions, extraction, assertions, background runs, status, and cancellation.

  • Direct TypeSafe Jev inference.

  • OpenRouter structured-output inference.

  • The future api.jevrelay.com/v1/decide endpoint.

It does not execute arbitrary JavaScript, shell commands, or local files.

Related MCP server: easy-ui-mcp

Install

Node.js 20 or newer is required.

npm install -g @jevrelay/mcp
jevrelay-mcp install-browser
jevrelay-mcp doctor

Until the package is published, install and run it directly from GitHub:

npx github:roxy-gg/jevrelay install-browser
npx github:roxy-gg/jevrelay doctor

Or clone the repository:

npm install
npm run build
npx playwright install chromium
node dist/cli.js doctor

MCP Configuration

Claude Desktop

{
  "mcpServers": {
    "jevrelay": {
      "command": "npx",
      "args": ["-y", "@jevrelay/mcp"]
    }
  }
}

Roxy

Before npm publication, use the public GitHub repository:

{
  "mcpServers": {
    "jevrelay": {
      "command": "npx",
      "args": ["-y", "github:roxy-gg/jevrelay"]
    }
  }
}

After npm publication, replace the final argument with @jevrelay/mcp.

Scripts without decide steps need no provider or API key.

Inference Providers

Secrets are environment variables on the local MCP process. Never pass provider keys as MCP tool arguments because tool arguments can enter model transcripts and logs.

TypeSafe Jev

JEVRELAY_PROVIDER=typesafe
TYPESAFE_API_KEY=...

OpenRouter

JEVRELAY_PROVIDER=openrouter
OPENROUTER_API_KEY=...
OPENROUTER_MODEL=openai/gpt-4o-mini

Choose an OpenRouter model that supports structured outputs.

JevRelay Provider

JEVRELAY_PROVIDER=jevrelay
JEVRELAY_API_KEY=...
JEVRELAY_API_URL=https://api.jevrelay.com/v1/decide

The hosted JevRelay provider is optional and not implemented in this repository.

Example MCP configuration with a direct TypeSafe key:

{
  "mcpServers": {
    "jevrelay": {
      "command": "npx",
      "args": ["-y", "@jevrelay/mcp"],
      "env": {
        "JEVRELAY_PROVIDER": "typesafe",
        "TYPESAFE_API_KEY": "..."
      }
    }
  }
}

MCP Tools

jevrelay_validate

Validates a Jev Script without running it.

jevrelay_run

Runs a script. Arguments:

  • script: Jev Script object.

  • inputs: Optional input overrides.

  • headless: Defaults to true.

  • wait: Defaults to true. Set to false for a background run.

jevrelay_status

Returns progress and partial output for a run ID.

jevrelay_stop

Requests cancellation of a running automation.

Jev Script

{
  "version": 1,
  "name": "read-example",
  "permissions": {
    "origins": ["https://example.com"]
  },
  "steps": [
    {
      "action": "browser.goto",
      "url": "https://example.com"
    },
    {
      "action": "browser.assert",
      "target": { "role": "heading", "name": "Example Domain" },
      "state": "visible"
    },
    {
      "action": "browser.extract",
      "target": { "role": "heading", "name": "Example Domain" },
      "fields": ["text"],
      "saveAs": "heading"
    }
  ]
}

Run it through MCP, or use the exported RunManager from Node.

A decision step chooses only from script-supplied or extracted options:

{
  "decide": {
    "state": "${vars.videos}",
    "question": "Which video best matches the request?",
    "optionsFrom": "videos.href",
    "minimumConfidence": 0.5,
    "saveAs": "videoUrl"
  }
}

If confidence is below the threshold, the run returns needs_input and does not execute the next action.

Browser Actions

The MVP supports:

browser.goto
browser.fill
browser.press
browser.click
browser.wait
browser.extract
browser.assert

Targets can use:

{ "selector": "article a" }
{ "role": "button", "name": "Play" }
{ "text": "Learn more" }
{ "id": "video-123" }

browser.extract fields include text, id, href, value, ariaLabel, tagName, and attr:<name>.

Security Boundary

  • Scripts declare allowed top-level origins.

  • Navigation, redirects, and popups to undeclared top-level origins are blocked.

  • Subresources loaded by an allowed page are not origin-restricted in the MVP.

  • Unknown actions and fields fail schema validation.

  • No shell execution or arbitrary JavaScript exists in the script format.

  • Provider secrets come from the local process environment.

  • Inference runs only at explicit decide steps.

  • Low-confidence decisions stop instead of guessing.

This is not yet a complete sandbox. Review generated scripts before using them with sensitive accounts, purchases, messages, or destructive workflows.

Development

npm install
npm run format
npm run check

Install Chromium once for browser tests and real runs:

npx playwright install chromium

License

MIT

Available Tools

4 tools
jevrelay_runRun Jev ScriptA
Destructive

Validate and execute a Jev Script locally with Playwright. Inference is used only for explicit decide steps.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoWait for completion before returning
inputsNoValues overriding script inputs
scriptYesThe declarative Jev Script JSON object
headlessNoRun the browser without a window

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: execution happens locally via Playwright (browser automation against open-world targets) and inference is invoked only for explicit decide steps, which forewarns of cost and non-determinism. It still omits what state/side effects the run leaves behind.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action, and the second sentence carries real information about the inference boundary. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain what a run returns — especially given the wait flag and the existence of jevrelay_status, which imply asynchronous execution and polling. It also never mentions required permissions or prerequisites for the destructive browser run, leaving real gaps for a tool with nested inputs and open-world side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with wait, inputs, headless and script each described in the schema itself, so the baseline is 3. The description adds nothing parameter-specific beyond hinting at decide steps, so it does not raise the bar.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (validate and execute) plus the resource (Jev Script) and the execution environment (locally, Playwright). This clearly separates it from jevrelay_validate, though the differentiation is implied rather than stated outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance, and none of the three sibling tools (jevrelay_validate, jevrelay_status, jevrelay_stop) are named. The agent must infer the boundary between validating and running, and when to poll status or stop instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jevrelay_statusGet JevRelay Run StatusB
Read-only

Return the current status and partial output of a JevRelay run.

ParametersJSON Schema
NameRequiredDescriptionDefault
runIdYes

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only safety profile is covered. The description adds that it returns partial output, which is useful behavioral context, but it does not explain status values, whether output is cumulative, or any polling/blocking behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant or filler language. It is appropriately sized for a simple status-retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only status tool, the description covers the basic purpose and return gist, and annotations cover the safety profile. However, with no output schema and no parameter explanation, it leaves gaps in what the status values mean and how runId should be supplied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate, but it never names or explains the runId parameter, its UUID format, or that it is required. The phrase 'of a JevRelay run' only indirectly implies a run identifier, leaving the parameter semantics almost entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Return), resource (JevRelay run), and the returned content (current status and partial output). It is clear enough to distinguish from validate/run/stop based on the common 'status' naming, but it does not explicitly differentiate itself from those siblings or name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus the sibling tools jevrelay_run, jevrelay_stop, or jevrelay_validate. It implies polling or checking a run's status but does not state any conditions, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jevrelay_stopStop JevRelay RunB
Destructive

Request cancellation of a running JevRelay automation.

ParametersJSON Schema
NameRequiredDescriptionDefault
runIdYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The word 'Request' adds mild value by implying cancellation may be asynchronous rather than immediate, but the description doesn't say whether the stop is graceful, forced, or idempotent, nor what happens to in-flight work.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler. It is appropriately sized, though it is arguably too terse given the destructive nature of the operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation with annotations carrying the safety profile and no output schema, the description is minimally adequate. But for a destructive stop operation it omits what 'cancellation' actually entails (immediate vs. graceful, effect on partial runs), leaving an agent with real gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single required parameter (runId, a UUID) is never referenced in the description. With low coverage the description should compensate by explaining what runId identifies, but it adds no meaning beyond the schema's type/format constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Request cancellation') and resource ('running JevRelay automation'), which clearly distinguishes it from the run/status/validate siblings. It stops short of explicitly naming an alternative, but the intent is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the phrase 'a running JevRelay automation' — the agent can infer this applies to an active run. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives such as jevrelay_status for checking state first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jevrelay_validateValidate Jev ScriptA
Read-only

Validate a declarative Jev Script without executing it.

ParametersJSON Schema
NameRequiredDescriptionDefault
scriptYesThe Jev Script JSON object to validate

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description reinforces this with 'without executing it,' which is useful confirmation, but it says nothing about what validation produces (pass/fail shape, error reporting) or whether partial validation is possible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. Every word contributes to scoping the operation relative to execution.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple one-parameter tool, so little is required, but with no output schema the description should at least hint at what a validation result looks like. The gap is minor but real for a validator whose only value is its report.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single script parameter, so the schema carries the parameter burden. The description adds no format, size, or structural guidance beyond what the schema already states, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb (Validate) with a specific resource (a declarative Jev Script) and adds the scope qualifier 'without executing it,' which separates it from jevrelay_run. It does not explicitly name the sibling tool, but the execution contrast makes the boundary inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without executing it' implies the natural usage (check a script before running it), but the description never states when to call this versus jevrelay_run, nor any prerequisites. Usage is only implied, not prescribed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedjevrelay_run
    • First observedjevrelay_status
    • First observedjevrelay_stop
    • First observedjevrelay_validate
Deploy Server
Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role in the script lifecycle: validate checks syntax, run executes, status reports progress, and stop cancels. Although run also validates, its execution focus makes it distinct from validate-only.

Naming Consistency5/5

All tools use the same jevrelay_ prefix and snake_case format with predictable verb/noun labels. The only minor variation is status being a noun, but it remains clear and consistent with the overall scheme.

Tool Count5/5

Four tools is well-scoped for a script validation and execution service. Each tool covers a necessary lifecycle operation without redundancy.

Completeness4/5

The surface covers the core lifecycle: validate, run, check status, and stop. Minor gaps exist, such as listing past runs or retrieving full logs/artifacts, but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Playwright MCP Server

    faruklmu17
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables web browser automation and inspection using structured data instead of screenshots, allowing AI agents to interact with web pages programmatically through the Playwright framework.
    -

  • browser-guard-mcp

    egoring
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to automate browsers through Playwright behind multi-layer safety guards, restricting navigation to allowed domains, defaulting to read-only actions, and recording all behavior in audit logs.
    7
    MIT