MCP Server

The Vector Vesper Model Context Protocol (MCP) server integrates the runtime architecture directly with AI coding assistants (such as Claude, Cursor, Windsurf, Antigravity, and OpenCode). When authoring custom interactions, the server evaluates interaction requirements, prescribes optimal primitives, enforces execution lane discipline, and checks authored code against runtime contracts.

Custom components built on the open-source runtime leverage the same frame loop, sensor bus, and adaptive quality engine as core registry components. The MCP server provides assistants with structural knowledge of these contracts.

Workflow

1. Architecture Planning (plan_motion): Evaluates interaction requirements, recommends runtime primitives vs. native CSS, and defines integration order.

2. Contract Inspection (get_hook, get_pattern): Queries lifecycle parameters, execution lanes, and potential transform collisions.

3. Implementation: Authors components according to established contracts and clean client boundaries.

4. Static Verification (check_motion): Validates the implementation against 21 motion and graphics lint rules to catch runtime regressions.

Set it up

Install the MCP server from your project directory:

npx vectorvesper mcp install

With no client name, VV configures every supported editor it finds. To configure one editor explicitly, name it:

npx vectorvesper mcp install cursor

Restart the editor, then confirm the connection:

npx vectorvesper mcp status

No token is required to discover the runtime and its documentation. Authentication only affects which Pro components the install workflow can access.

Supported clients

The installer merges Vector Vesper into an existing MCP config; it does not replace the other servers you rely on. If it finds a config it cannot parse, it leaves the file untouched and prints the snippet for you to add manually.

What your assistant can do

Motion Planning (`plan_motion`)

The plan_motion tool evaluates the specifications of a planned interaction and returns:

• Platform vs. Runtime Recommendation: Distinguishes between interactions achievable via native CSS (transitions, pseudo-classes, compositor animations) and those requiring runtime coordination (continuous pointer tracking, physics, canvas frame loops).
• Primitive Sequence: The exact hooks and execution order required.
• Transform and DOM Ownership: Identifies whether multiple hooks attempt to animate the same CSS transform property on a single element and specifies where intermediate wrapper elements are needed.
• Resource Sharing: Ensures multiple animations subscribe to the single shared frame conductor rather than instantiating isolated requestAnimationFrame loops.

Example Prompt

The tool separates the interaction into two concerns:

1. The entry fade is delegated to CSS and an IntersectionObserver.

2. The interactive card tilt is routed through pointer parallax primitives (useSensorBus and useTick) operating within coordinated frame lanes.

Scaffold Generation for 3D Scenes

When planning Three.js or WebGL scenes, plan_motion scaffolds a baseline implementation using useThreeScene or useSceneGate with useRenderQuality. This ensures the initial scaffold has viewport gating, pixel-ratio capping, reduced-motion fallbacks, and context-loss recovery pre-configured.

Static Code Verification (`check_motion`)

check_motion performs static analysis across 21 domain-specific rules categorized into three severities:

• Errors: Broken execution paths, SSR module-scope violations, missing client directives, or discarded subscription cleanups.
• Warnings: Architectural defects, such as unmanaged RAF loops, state mutations inside per-frame callbacks, layout reads in render lanes, or unhandled WebGL/WebGPU context loss.
• Info: Advisory notices verifying proper prop propagation to canvas wrappers.

For the full list of rules, see the check_motion Rules reference.

Configure it by hand

Use manual configuration only when the installer cannot write the file for you. Claude, Cursor, Windsurf, and Antigravity use this shape:

{
  "mcpServers": {
    "vectorvesper": {
      "command": "npx",
      "args": ["-y", "vectorvesper@latest", "mcp", "--stdio"]
    }
  }
}

OpenCode uses a different shape. Servers sit directly under mcp, and command is one array:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vectorvesper": {
      "type": "local",
      "command": ["npx", "-y", "vectorvesper@latest", "mcp", "--stdio"],
      "enabled": true
    }
  }
}

If OpenCode reports a schema error for mcp.servers, the config is using the Claude/Cursor shape. Move vectorvesper directly under mcp instead.

Keep @latest in the command. Without it, npx may reuse a global install, project dependency, or cached package. Your assistant can then miss tools added in newer VV releases without an obvious error.

Running npx vectorvesper mcp in an interactive shell displays command syntax and usage instructions. Editors launch the server directly using the --stdio flag to communicate over standard input and output streams.

Alternative: AGENTS.md Configuration

For development workflows that do not use MCP, executing npx vectorvesper init generates motion architecture directives in AGENTS.md. These instructions provide AI coding assistants with baseline requirements, such as delegating animation loops to the shared conductor and respecting execution lanes.