Ritoko

What ritoko MCP server does

The ritoko MCP server turns a completed task into a reusable JSON workflow. A workflow can describe browser actions, HTTP requests, or calls to existing MCP tools, along with parameters, an input file, a business key, a commit boundary, and result checks. Agents can use the saved procedure with new rows instead of reconstructing the task for every record.

The system is aimed at repeatable operations with observable outcomes. Supported examples include customer or supplier onboarding, recurring report downloads, HTML or ARIA table exports, API operations, and tasks that combine browser and API steps. Inputs can come from CSV or Excel files, while saved values and files can move between supported steps.

How it works

An agent or workflow author first records browser actions or defines supported API and MCP steps. Ritoko saves the procedure in readable JSON, then the direct replay engine executes it without needing an LLM. A connected MCP tool may use AI independently, but replay of a saved workflow does not require an LLM.

Each run is tracked in a local SQLite journal. The journal records the workflow and input rows, allowing later runs to skip confirmed items. Failed items and uncertain writes remain visible for review. A resumed run can continue after an interruption rather than repeating confirmed work. The run_adopt operation can associate a record created during demonstration with a workflow when evidence supports doing so.

With a configured destination lookup, the ritoko MCP server can check for an existing record before creating one and read back an uncertain result. These ensure and reconcile behaviors require a direct HTTP GET or a trusted, explicitly read-only MCP tool, with separate rules for proving presence and absence. A failed lookup blocks the row.

Setup and configuration

Node.js 24 or newer is required. Install the package from npm, use the Claude Code or Codex CLI plugin, or configure a local stdio MCP client with npx --yes --prefer-online ritoko@latest mcp. The repository identifies Claude Code and Codex CLI as tested plugin clients; other local MCP clients require their own compatibility checks.

Direct browser workflows also require Google Chrome. The runner can connect to a personal Chrome session after remote debugging is enabled and the connection is allowed. Set RITOKO_BROWSER=clean when a separate browser profile is preferred. Standalone HTTP and MCP workflows do not require a browser.

For repeatable production runs, pin a published npm version and test upgrades on a small batch. Long Codex batches may also require client tool-call timeout configuration.

Tools and capabilities

The ritoko MCP server supports:

• Recording or authoring reusable browser, HTTP, and MCP procedures.
• Replaying saved workflows with CSV or Excel inputs.
• Checking results and saving downloaded or generated files.
• Resuming interrupted runs from journaled state.
• Reporting confirmed, failed, and review-required items.
• Checking destinations before creation and reconciling uncertain results when configured safely.

Limitations and notes

Ritoko fits tasks with explicit rules and verifiable results; it does not remove the need for an agent or author to understand the target site and define the procedure. Codex computer-use evaluate is currently read-only, so it cannot perform host browser replay. Host API-only and connected MCP-tool batches remain available.

Use care with writes. A demonstration that already created a real record should be adopted with evidence before replaying a batch. Browser selection and trust boundaries affect which workflows can execute, and the local demo tests a simulation rather than browser interruption or destination reconciliation.