/ docs
Open App

Tool Reference

Complete reference for all 69 ASCII Motion MCP tools organized by category.

Canvas Management (7 tools)

Tools for managing the canvas workspace.

get_canvas_summary

Get a compact summary of the canvas including dimensions and cell counts.

Parameters: frameIndex (optional) - Frame to inspect

Example: "Get a summary of the canvas dimensions"

resize_canvas

Resize the canvas to new dimensions.

Parameters:

  • width (required) - New width in cells
  • height (required) - New height in cells
  • anchor (optional) - Resize anchor point

Example: "Resize the canvas to 80x40"

clear_canvas

Clear all cells on the canvas.

Parameters: frameIndex (optional) - Frame to clear

Example: "Clear the entire canvas"

clear_cells

Clear specific cells on the canvas.

Parameters:

  • cells (required) - Array of {x, y} coordinates
  • frameIndex (optional) - Target frame

get_cell

Get the character and colors at a specific position.

Parameters:

  • x (required) - X coordinate
  • y (required) - Y coordinate
  • frameIndex (optional) - Frame to read

set_cell

Set a single cell's character and colors.

Parameters:

  • x (required) - X coordinate
  • y (required) - Y coordinate
  • char (required) - Character to set
  • color (optional) - Foreground color (hex)
  • bgColor (optional) - Background color (hex)
  • frameIndex (optional) - Target frame

Example: "Set the cell at position 10,5 to the character '@' in red"

set_cells_batch

Set multiple cells at once (max 10,000 cells per batch).

Parameters:

  • cells (required) - Array of cell data
  • frameIndex (optional) - Target frame

inspect_cells

Inspect all non-empty cells in a region.

Parameters:

  • x, y, width, height (required) - Region bounds
  • frameIndex (optional) - Frame to inspect

Drawing Tools (5 tools)

Tools for drawing shapes and text.

draw_line

Draw a line between two points using Bresenham's algorithm.

Parameters:

  • x1, y1 (required) - Start point
  • x2, y2 (required) - End point
  • char (required) - Character to draw
  • color, bgColor (optional) - Colors

Example: "Draw a line from 0,0 to 20,10 using dashes"

draw_rectangle

Draw a rectangle outline or filled.

Parameters:

  • x, y (required) - Top-left corner
  • width, height (required) - Dimensions
  • char (required) - Character for outline/fill
  • filled (optional) - Fill the rectangle
  • color, bgColor (optional) - Colors

draw_circle

Draw a circle outline or filled.

Parameters:

  • cx, cy (required) - Center point
  • radius (required) - Circle radius
  • char (required) - Character to use
  • filled (optional) - Fill the circle

draw_ellipse

Draw an ellipse outline or filled.

Parameters:

  • cx, cy (required) - Center point
  • radiusX, radiusY (required) - Radii
  • char (required) - Character to use
  • filled (optional) - Fill the ellipse

type_text

Type text at a position using ASCII fonts.

Parameters:

  • x, y (required) - Position
  • text (required) - Text to type
  • font (optional) - Font style
  • color (optional) - Text color

Example: "Type 'HELLO' at position 5,5 in cyan"

Selection Tools (6 tools)

Tools for selecting and working with regions.

get_selection

Get the current selection bounds and contents.

Parameters: includeCells (optional) - Include cell data

select_rectangle

Select a rectangular region.

Parameters:

  • x, y (required) - Top-left corner
  • width, height (required) - Dimensions

Example: "Select the rectangle from 10,10 to 30,20"

select_by_color

Select all cells matching a color.

Parameters:

  • color (required) - Color to match (hex)
  • matchForeground (optional) - Match foreground
  • matchBackground (optional) - Match background

Example: "Select all cells with red foreground"

apply_to_selection

Apply an operation to all selected cells.

Parameters:

  • operation (required) - Operation type
  • params (required) - Operation parameters

recolor_selection

Change colors in the selection.

Parameters:

  • color (optional) - New foreground color
  • bgColor (optional) - New background color

Example: "Recolor the selection to gold"

clear_selection

Clear the current selection.

Flood Fill & Region Tools (2 tools)

fill_region

Flood fill a region with a character and colors.

Parameters:

  • x, y (required) - Starting point
  • char (required) - Fill character
  • color, bgColor (optional) - Fill colors
  • contiguous (optional) - Only fill connected cells
  • matchChar, matchColor, matchBgColor (optional) - Match criteria

Example: "Flood fill from 15,15 with the '@' character in blue"

flip_region

Flip content horizontally or vertically.

Parameters:

  • direction (required) - "horizontal" or "vertical"
  • region (optional) - Region to flip
  • frameIndex (optional) - Target frame

Example: "Flip the selection horizontally"

Frame Management (8 tools)

Tools for animation frame control.

get_frame_info

Get information about a specific frame.

Parameters: frameIndex (optional) - Frame to query

add_frame

Add a new empty frame.

Parameters:

  • atIndex (optional) - Position for new frame
  • copyFrom (optional) - Frame to copy

Example: "Add a new frame at position 5"

delete_frame

Delete a frame.

Parameters: frameIndex (required) - Frame to delete

duplicate_frame

Create a copy of a frame.

Parameters:

  • frameIndex (optional) - Frame to copy
  • insertAt (optional) - Position for duplicate

Example: "Duplicate frame 3 and put it at the end"

go_to_frame

Navigate to a specific frame.

Parameters: frameIndex (required) - Frame to go to

set_frame_duration

Set the display duration for a frame.

Parameters:

  • frameIndex (required) - Target frame
  • duration (required) - Duration in milliseconds

Example: "Set frame 5 duration to 200ms"

copy_region_between_frames

Copy a region from one frame to another.

Parameters:

  • sourceFrame (required) - Source frame index
  • targetFrame (required) - Target frame index
  • region (required) - Region to copy {x, y, width, height}

interpolate_frames

Create interpolated frames between two keyframes.

Parameters:

  • startFrame (required) - First keyframe
  • endFrame (required) - Second keyframe
  • count (required) - Number of frames to generate

Example: "Interpolate 4 frames between frame 1 and frame 6"

Effects (6 tools)

Apply visual effects to frames.

apply_effect

Apply a visual effect to the current frame.

Parameters:

  • effect (required) - Effect name
  • params (optional) - Effect parameters

Available effects:

  • invert - Invert colors
  • grayscale - Convert to grayscale
  • sepia - Apply sepia tone
  • pixelate - Pixelate with block size
  • blur - Blur effect
  • sharpen - Sharpen effect
  • hueShift - Shift hue by degrees
  • scanlines - CRT scanlines
  • glitch - Random glitch effect
  • noise - Add noise
  • vignette - Darken edges
  • chromatic - Chromatic aberration

Example: "Apply a glitch effect to the current frame"

get_color_stats

Get statistics about colors used in a frame.

Parameters: frameIndex (optional) - Frame to analyze

create_gradient

Create a color gradient across a region.

Parameters:

  • startColor (required) - Starting color (hex)
  • endColor (required) - Ending color (hex)
  • direction (required) - "horizontal", "vertical", or "radial"
  • region (optional) - Target region

Example: "Create a horizontal gradient from blue to purple"

color_cycle_animation

Create color cycling across frames.

Parameters:

  • colors (required) - Array of colors to cycle
  • frameRange (optional) - Frames to affect

apply_dithering

Apply dithering to reduce colors.

Parameters:

  • algorithm (required) - "floyd-steinberg", "ordered", or "random"
  • colorCount (optional) - Target color count

adjust_brightness_contrast

Adjust brightness and contrast.

Parameters:

  • brightness (optional) - Brightness adjustment (-100 to 100)
  • contrast (optional) - Contrast adjustment (-100 to 100)

Palette Tools (9 tools)

Manage character and color palettes.

list_character_palettes

List all available character palettes.

Available palettes:

  • minimal-ascii - Basic ASCII (.:-=+*#)
  • standard-ascii - Full printable ASCII
  • block-characters - Unicode blocks (░▒▓█)
  • retro-computing - Classic computer characters
  • box-drawing-light - Light box drawing
  • box-drawing-double - Double box drawing

get_character_palette

Get characters from a specific palette.

Parameters: paletteId (required) - Palette identifier

list_color_palettes

List all available color palettes.

Available palettes:

  • ansi-16 - Standard ANSI terminal colors
  • monochrome-green - Classic terminal green
  • grayscale - Black to white gradient
  • rainbow - Full spectrum colors
  • retro-8bit - 8-bit computer palette

get_color_palette

Get colors from a specific palette.

Parameters: paletteId (required) - Palette identifier

get_foreground_color

Get the current foreground color.

set_foreground_color

Set the current foreground color.

Parameters: color (required) - Color in hex format

Example: "Set the foreground color to cyan"

get_background_color

Get the current background color.

set_background_color

Set the current background color.

Parameters: color (required) - Color in hex format

suggest_palette_for_style

Get palette suggestions for a style.

Parameters: style (required) - Style description

Example: "Suggest a palette for retro terminal art"

Import Tools (4 tools)

Import images and convert to ASCII.

import_image

Import an image and convert to ASCII art.

Parameters:

  • filePath (required) - Path to image file
  • targetWidth (optional) - Width in characters
  • targetHeight (optional) - Height in characters
  • charset (optional) - Characters for brightness
  • colorMode (optional) - "none", "foreground", "background", "both"
  • dithering (optional) - "none", "floyd-steinberg", "ordered"

Example: "Import logo.png at 60 characters wide with dithering"

import_json

Import a previously exported ASCII Motion project.

Parameters: filePath (required) - Path to JSON file

import_ansi

Import ANSI art file.

Parameters: filePath (required) - Path to .ans file

import_ascii_text

Import plain ASCII text.

Parameters:

  • text (required) - Text content
  • x, y (optional) - Position

Export Tools (12 tools)

Export to various formats.

export_ansi

Export as ANSI escape codes for terminal display.

Parameters:

  • frameIndex (optional) - Frame to export
  • outputPath (optional) - Output file path

export_html

Export as a standalone HTML file.

Parameters:

  • outputPath (optional) - Output file path
  • darkMode (optional) - Use dark background
  • includeAnimation (optional) - Include all frames

export_png

Export as PNG image.

Parameters:

  • outputPath (optional) - Output file path
  • frameIndex (optional) - Frame to export
  • scale (optional) - Scale factor

export_svg

Export as SVG vector image.

Parameters:

  • outputPath (optional) - Output file path
  • frameIndex (optional) - Frame to export

export_json

Export as JSON for later editing.

Parameters:

  • outputPath (optional) - Output file path
  • pretty (optional) - Pretty-print JSON

export_gif

Export animation as GIF.

Parameters:

  • outputPath (optional) - Output file path
  • fps (optional) - Frames per second
  • loop (optional) - Loop count (0 = infinite)

Example: "Export as a looping GIF at 10fps"

export_mp4

Export animation as MP4 video.

Parameters:

  • outputPath (optional) - Output file path
  • fps (optional) - Frames per second
  • quality (optional) - Quality setting

export_webm

Export animation as WebM video.

Parameters:

  • outputPath (optional) - Output file path
  • fps (optional) - Frames per second
  • transparent (optional) - Transparent background

export_bubbletea

Export as Bubbletea component for Go TUI apps.

Parameters:

  • outputPath (optional) - Output file path
  • packageName (optional) - Go package name

Example: "Export as a Bubbletea component called 'banner'"

export_ink

Export as Ink component for Node.js CLI apps.

Parameters:

  • outputPath (optional) - Output file path
  • typescript (optional) - Generate TypeScript

export_react

Export as React component.

Parameters:

  • outputPath (optional) - Output file path
  • typescript (optional) - Generate TSX
  • componentName (optional) - Component name

Example: "Export as a React TypeScript component"

export_opentui

Export for OpenTUI framework.

Parameters:

  • outputPath (optional) - Output file path

Project Management (6 tools)

Manage ASCII Motion projects.

create_project

Create a new project.

Parameters:

  • name (required) - Project name
  • width (optional) - Canvas width
  • height (optional) - Canvas height

Example: "Create a new project called 'my-animation' with a 60x20 canvas"

load_project

Load an existing project.

Parameters: filePath (required) - Path to project file

save_project

Save the current project.

Parameters: filePath (optional) - Output path

get_project_info

Get information about the current project.

list_project_files

List all project files in the project directory.

get_auth_token

Get the WebSocket authentication token for live browser sync.

Returns: The token needed to connect the browser to MCP

Undo/Redo (3 tools)

History management tools.

get_undo_status

Check undo/redo availability.

Returns: Object with canUndo, canRedo, and history length

undo

Undo the last action.

redo

Redo a previously undone action.

Connection Tools (2 tools)

Browser connection management.

get_connection_status

Check browser connection status.

Returns: Whether browser is connected and client count

get_auth_token

Get the authentication token for browser connection.

Clipboard (3 tools)

Copy and paste operations.

copy_to_clipboard

Copy the current selection to clipboard.

paste_from_clipboard

Paste clipboard contents.

Parameters:

  • x, y (optional) - Paste position
  • frameIndex (optional) - Target frame

get_clipboard_contents

View clipboard contents without pasting.

Next Steps