Cavalry MCP

A local, domain-specific MCP server for controlling Cavalry through its installed JavaScript API. It exposes validated tools and structured JSON results instead of arbitrary script execution.

Requirements

• Cavalry 2.4 or newer

• Node.js 20 or newer

• An MCP client with stdio support

Related MCP server: cavalry-mcp

Install from this repository

npm install
node src/index.js --install-bridge

Open Cavalry, choose Scripts > Stallion, and approve Cavalry's one-time trust prompt. The bundled Stallion bridge listens only on 127.0.0.1:8080.

Configure the MCP client:

{
  "mcpServers": {
    "cavalry": {
      "command": "node",
      "args": ["C:/absolute/path/to/cavalry-mcp/src/index.js"]
    }
  }
}

After publication to npm:

npx -y cavalry-mcp install

If Stallion.js already exists and should be replaced, add --force. The legacy --install-bridge flag remains supported.

{
  "mcpServers": {
    "cavalry": {
      "command": "npx",
      "args": ["-y", "cavalry-mcp"]
    }
  }
}

MCP interface

Every successful tool response includes both human-readable text and validated structuredContent.

The read-only cavalry://scene resource exposes the live scene summary to MCP clients that support resources.

Dedicated tools first

Use the dedicated domain tools for normal work. cavalry_api_call is the fallback for the rest of Cavalry's installed @JS_GUI_API surface:

{
  "method": "getFrame",
  "args": []
}

The server rejects unknown methods. Scene replacement and destructive scene operations require confirmDangerous: true. Arbitrary script execution, process execution, browser launches, and general filesystem read/write methods are never exposed by this fallback.

Architecture

MCP client ──stdio──> Cavalry MCP ──HTTP loopback──> Stallion ──> Cavalry api
                         │
                         └── installed API metadata for validation/discovery

The bridge injects generated adapters directly into Cavalry through api.exec. Only the structured result uses a temporary JSON file, which is removed after every call. No desktop mouse/keyboard automation, MCP network listener, or arbitrary-JavaScript tool is exposed.

Configuration

Safety

Tool schemas validate input at the MCP boundary. Mutating tools declare MCP safety annotations, saves and renders refuse existing targets unless explicitly allowed, render restores the previous frame, and generic API calls are restricted to installed metadata. New JavaScript Console errors and warnings fail the active MCP operation instead of being silently reported as success.

The MCP never drives Cavalry through desktop input. If the installed JavaScript API does not expose an operation, the tool fails explicitly instead of clicking menus or sending keystrokes.

An MCP client still has substantial authority over the open Cavalry scene. Keep Stallion on loopback and save important work before approving mutations.

Development

npm run check
npm test
npm run smoke
npm run smoke:mcp
npm run smoke:write # creates and removes a temporary layer and PNG
npm pack --dry-run

MIT licensed. Stallion remains copyright its original author and is included under its MIT license in THIRD_PARTY_LICENSES.md.