Avatar Studio

Create a personalized robot avatar for your profile, team chat, app, or AI assistant. Avatar Studio combines a browser-based creator with a local MCP server so people and agents can generate avatars from the same accessory catalog.

Built on Agent Robot Avatar by CX ArtLab, using SVG and vanilla JavaScript. The website runs without a backend or account; the MCP server runs separately as a local Node.js subprocess.

Live creator · Documentation · Releases · Changelog · npm package

The documentation covers creator guides, npm integration, MCP setup, API controls, and visual use cases.

Glossy 3D preview

The creator includes an optional Glossy 3D style with rounded vinyl bodies, reflective materials, raised eyes, and the existing shape-fitting accessory catalog. Switch styles in the editor; colors, eye controls, and body shapes carry over. PNG captures the transparent 3D view; GIF records a floating and blinking loop. SVG retains the original vector appearance.

This first version requires browser WebGL. Devices without it keep the SVG editor. Reduced-motion preferences stop the floating motion. Accessories are currently converted from their SVG outlines into raised 3D shapes; individually sculpted accessories and full gesture parity are future work. The npm component and local MCP image tools continue to render the existing SVG style.

The creator loads its self-hosted Three.js renderer only when 3D is selected. For local development, npm run dev builds the renderer automatically; npm run build:glossy rebuilds it after changes. Three.js is MIT licensed; its license is included in the deployed bundle directory.

Avatar examples

Try the live creator or use MCP to make your own. These 24 GIF examples were generated through the Avatar Studio MCP server, using different colors, accessories, expressions, classic and seeded fluid bodies, and profile badges. Each preview links to its downloadable GIF.

MCP GIFs use a deterministic blink cycle with a selected expression. Sleeping eyes stay closed. For full actions, cursor following, and gestures, embed the live npm component.

SVG, PNG, and sprite examples

The same designs can be exported as transparent SVGs, profile PNGs, or sprite sheets with frame coordinates.

Classic SVG · Headphones SVG · Crown SVG · Fluid fox SVG · Wizard SVG · Flower SVG · Sleeping SVG · Visor SVG

Reproduce the GIFs using the exact create_avatar arguments in the example manifest. See sprite coordinates and configs for the PNG sheet. All assets are committed to this repository; no external image host is required.

Avatars in real applications

48 illustrated use cases, from account profiles to agent workflows. These are documentation mockups made with real avatar exports, not bundled integrations. Your application supplies messaging, presence, notifications, accounts, game logic, and state transitions. Platform support for animated profile images varies; use PNG when GIF is not supported.

Profiles and communities

Assistants and support

Presence and workflow states

Collaboration and work

Branding and product identity

Content and community identity

Games and learning

Developer and agent workflows

Choose an integration

See the MCP-generated live component configuration for looping, pointer-following, and antenna flash settings. Source: 48 use-case definitions, MCP export metadata, and the gallery builder. After installing MCP dependencies, run node scripts/build-use-case-gallery.mjs to rebuild the mockups. PNG previews are committed so GitHub can display them directly.

Run the website

Requires Node.js 22 or newer and npm.

git clone https://github.com/ai-calypse/avatar-studio.git
cd avatar-studio
npm ci
npm run dev

Open Avatar Studio locally. To use another port:

npm run dev -- --port 4175

The creator opens immediately, with a live preview and downloads alongside the customization controls:

• Choose body, eye, and accessory colors independently, or enable Match eyes for the accessory.
• Adjust eye size, eye spacing, and head roundness. Choose Fluid / random for an organic body, then Shuffle to find a unique silhouette. Your shape seed is saved with your look.
• Choose from 50 accessories, plus None, in a grouped dropdown. Accessories fit the changing body outline.
• Choose the header language to translate controls, all 50 accessories, showcases, and download messages into English, Spanish, French, German, Portuguese, Japanese, Korean, Simplified Chinese, or Traditional Chinese. The URL and browser remember your selection.
• Try expressions and movement settings, including blinking, pointer following, and interactive head movement.
• See your avatar in live examples of chat, profile cards, an app companion, and project branding.

Your appearance settings are saved in your browser. Reset look restores the defaults.

Download formats

Exports are generated in the browser. SVG and PNG capture the current appearance; GIF records the live animation.

Build for static hosting

npm run build:pages

Upload the contents of .pages-site/ to your static host. The generated index.html serves the creator at the site root. This build contains only the website; it does not deploy or expose the MCP server.

Connect the MCP server

The local MCP server provides 11 tools for stable user identities, brand palettes, batch exports, design variants, expression packs, sprite sheets, and SVG/PNG/GIF generation. It shares the website's accessory catalog and shape-fitting accessory renderer. It uses predefined expressions and a deterministic blink animation rather than recording the browser's live state.

From the repository checkout, install its separate dependencies and verify the server:

npm ci --prefix mcp --ignore-scripts
npm run test:mcp

Add the following entry to your MCP client's configuration. Replace both absolute paths with your Node executable and this repository's location. Run command -v node to find Node; your client may use a different configuration format.

{
  "mcpServers": {
    "avatar-studio": {
      "command": "/absolute/path/to/node",
      "args": [
        "--max-old-space-size=192",
        "/absolute/path/to/avatar-studio/mcp/src/index.mjs"
      ],
      "env": {}
    }
  }
}

Restart or reconnect your MCP client after saving its configuration. The client launches and manages the server process. No API key, HTTP URL, or separate website process is required.

npm run mcp:start also starts the server manually, but it speaks MCP over stdin/stdout and needs an MCP client attached. It does not start a web server or interactive command prompt.

Available tools

For example: “Create six branded support agents,” “Make a repeatable profile avatar for user-2048,” or “Build a sprite sheet of my guide's expressions.” See workflow examples for exact arguments.

Render tools also accept presentation for a hex/transparent background, circular or rounded frame, 0–24% padding, and an online/away/busy/offline status badge. The npm exportAvatar helper supports the same presentation controls. Batch/variant/expression tools produce SVG/PNG at 32–256 pixels; single-avatar generation retains SVG/PNG/GIF support. Results stay in memory and your app owns storage.

For example, ask your connected agent:

Use Avatar Studio to create a dark green robot profile avatar with lime eyes and headphones that match the eyes. Return a 256-pixel PNG.

The corresponding create_avatar arguments are:

{
  "format": "png",
  "size": 256,
  "config": {
    "body": "#182725",
    "eyes": "#dbf59d",
    "accessory": "headphones",
    "accessoryColor": "#ffffff",
    "matchEyes": true,
    "eyeSize": 100,
    "spacing": 0,
    "headRoundness": 70,
    "expression": "happy"
  }
}

Configuration controls

All configuration fields are optional; omitted fields use the defaults below. Unknown fields are rejected.

format defaults to svg, and size defaults to 256. SVG and PNG accept integer sizes from 32 to 512. For GIF, explicitly set size between 32 and 128:

{
  "format": "gif",
  "size": 128,
  "config": { "accessory": "wizard", "expression": "happy" }
}

MCP GIFs contain 12 looping blink frames at 100 ms per frame, with a light background and reduced color palette. SVG and PNG have transparent backgrounds by default; set presentation.background for a solid background.

Use artifacts in your application

The result's structuredContent includes the normalized configuration, format, size, MIME type, byte count, and SHA-256 checksum. The artifact is returned in content:

• SVG: embedded resource with the SVG string in resource.text.
• PNG: image block with base64 data in data.
• GIF: embedded resource with base64 data in resource.blob.

Decode the returned data and save it through your application's authorized storage layer. Retain the normalized configuration to regenerate the avatar later. An avatar://generated/... resource URI identifies the returned artifact; it is not a hosted download URL or a stored resource to fetch. The MCP server does not save files.

See the MCP guide for more details and the example client configuration.

Security model

The MCP server is designed for a trusted MCP client launching a local subprocess. It has no network listener and exposes no file, shell, URL-fetching, or arbitrary SVG tools.

Inputs use strict allowlisted schemas. Rendering has bounded image sizes, output sizes, concurrency, and execution time, with separate workers that receive no inherited environment variables. Dependencies are pinned in a lockfile.

These controls do not make the process an operating-system sandbox or a public multi-tenant service. Read the security model and limitations before integrating or hosting it. Remote access would require a separate authentication, isolation, and deployment design.

npm package for applications

The browser package is @ai-calypse/avatar-studio. It includes the animated robot and cat components, the 50-accessory catalog, programmatic customization, and SVG snapshots with TypeScript declarations. It has no runtime dependencies. The website controls and Node.js MCP server are separate.

Install the published package from npm:

npm install @ai-calypse/avatar-studio

Import it in your browser application's entrypoint:

import { customizeAvatar, exportAvatarSVG, accessories } from '@ai-calypse/avatar-studio';

const avatar = document.createElement('agent-robot-avatar');
avatar.setAttribute('size', '160');
document.querySelector('#avatar-container').appendChild(avatar);

customizeAvatar(avatar, {
  body: '#182725',
  eyes: '#dbf59d',
  accessory: 'headphones',
  matchEyes: true,
  headRoundness: 70,
  bodyShape: 'random',
  shapeSeed: 42
});

avatar.startWaiting();
// When your operation completes:
await avatar.play('success');

const svg = exportAvatarSVG(avatar, 256);
console.log(accessories); // 50 entries with id, name, and category

Call customizeAvatar after attaching the element to the page. It accepts partial appearance updates using the color, accessory, eye-size, spacing, and head-roundness controls listed above. Unsupported fields, accessory IDs, and out-of-range values are rejected. Set expressions through the component's animation API, such as avatar.play('success'); the MCP-only expression field is not accepted by customizeAvatar. With bodyShape: "random", the same shapeSeed and headRoundness reproduce the same silhouette in the browser and MCP. Roundness still controls the underlying softness; changing the seed changes the outline. The shape stays stable while blinking, dragging, and exporting. Shape uniqueness is visual variety, not an authentication guarantee. Settings are isolated per element and are not automatically saved to browser storage.

exportAvatarSVG returns a string snapshot of the current pose at a size from 32 to 512. Use exportAvatar for browser SVG/PNG/GIF Blobs, the website downloads, or MCP for generated artifacts. In a server-rendered application, create and customize elements on the client after mounting.

To test local changes before publishing a new version, install from a local tarball:

npm pack --pack-destination /tmp
# Run in your application's directory:
npm install /tmp/ai-calypse-avatar-studio-0.2.0.tgz

See the basic example, the accessible request lifecycle example, and TypeScript declarations for the underlying component API. Publishing instructions explain npm login, validation, and release automation.

Complete control API (npm 0.2.0+)

import { configureAvatar, exportAvatar, avatarActions } from '@ai-calypse/avatar-studio';

// Attach the component before configuring it.
configureAvatar(avatar, {
  appearance: { bodyShape: 'random', shapeSeed: 42, antenna: true,
    accessory: 'headphones', matchEyes: true, eyes: '#dbf59d' },
  behavior: { pointerFollow: true, antennaFlash: true, loop: true,
    pressSqueeze: true, antennaDrag: true, motion: 'auto',
    wakeOn: 'interaction', autoSleep: 60000 },
  action: 'waiting-wrap'
});
const gif = await exportAvatar(avatar, { format: 'gif', size: 128,
  frames: 12, delay: 100,
  presentation: { frame: 'circle', status: 'online', padding: 4 } });
// Returns a Blob. Your app owns saving or uploading it.
console.log(avatarActions); // Every public action and alias.

configureAvatar accepts partial appearance/behavior updates and preserves previous settings. Antenna visibility is an appearance field; headwear can hide the antenna. Behavior switches default to pointer following and gestures enabled, antenna flash and expression looping disabled. Motion supports auto, reduce, full; wake policy supports activity, interaction, manual; auto-sleep is 0–86400000 ms (0 disables it). Looping waiting uses continuous waiting; other actions repeat after completing. Reset/cancellation clears queued repeats. Disconnecting prevents a queued repeat from starting. Explicit actions start asynchronously after runtime policies are applied.

exportAvatar supports SVG/PNG at 32–512 pixels and GIF at 32–256 pixels, 2–48 frames, 20–500 ms per frame. PNG keeps transparency by default; GIF uses a light background. Presentation supports background hex/transparent, none/circle/rounded framing, padding 0–24%, and none/online/away/busy/offline badges. background is a shorthand for a solid presentation background. GIF records the current live component; its image loop is independent of the expression-loop switch. No files, uploads, or network access are performed by these helpers.

Interactive movement and full action lifecycles run in a live browser component. An image file cannot follow a cursor. MCP's create_avatar_component returns validated npm integration code and normalized settings for those interactive use cases; it executes no code on the server. Website language selection affects the interface, not avatar geometry.

Development checks

npm run lint
npm run check
npm run test:types
npm run test:mcp
npm audit --prefix mcp --omit=dev
npm run build:pages

For the creator's Chromium browser tests:

npx playwright install chromium
npx playwright test tests/studio.spec.mjs --project=chromium

Set AVATAR_TEST_PORT=4175 if testing the local server on that port. npm test runs the original component's full validation suite, including Chromium, Firefox, and WebKit, and requires those Playwright browsers to be installed. Run npm run test:mcp separately to check the MCP server.

Contributing and security

See CONTRIBUTING.md for local setup and required checks, SECURITY.md to report vulnerabilities privately, and CODE_OF_CONDUCT.md for community guidelines. CI checks code quality, types, browser compatibility, npm packaging, MCP workflows, dependencies, and GitHub Actions security.

Attribution and license

Avatar Studio extends Agent Robot Avatar. The original robot character and visual identity were designed by CX ArtLab; this repository adds the personalized creator, accessory catalog, exports, showcases, and local MCP integration.

The original project's character and visual identity notice is retained: the MIT license permits use, modification, and distribution of the software, but does not transfer ownership of the original character's name or identity or grant the right to claim it as another party's original character.

MIT License, with copyright notices for CX ART Lab and ai-calypse.

Website translations

The header language picker supports English, Spanish, French, German, Portuguese, Japanese, Korean, Simplified Chinese, and Traditional Chinese. Studio copy, accessory options, export feedback, page metadata, tooltips, and accessible labels use local catalogs in demo/avatar-studio-i18n.js. Movement controls and the conversation demo have their own catalogs in demo/agent-robot-avatar-demo-controls.js and demo/agent-robot-avatar-demo-dialog-i18n.js. Brand names, sample people/handles, commands, package names, and file formats stay literal. No visitor text is sent to a translation service.

To add another language, add a complete locale to each catalog and the LANGUAGES list in the demo controls. Use a BCP 47 language tag; configure dir=rtl and review the layout when introducing a right-to-left language. Run npx playwright test tests/translation-coverage.spec.mjs: it checks every offered studio locale against the full phrase catalog and mounted interface, including image descriptions and tooltips. Add new phrases to every locale when changing copy. Missing translations fall back to English at runtime and fail coverage checks. Machine translations should be reviewed by a fluent speaker before release.

Publish to GitHub Pages

The repository's Deploy Live Demo workflow builds the static site into .pages-site and deploys it with GitHub's Pages actions. It runs for relevant changes on main or manually from Actions. All asset imports are relative so the site works under /avatar-studio/.

1. In Settings → Pages → Build and deployment, select GitHub Actions as the source.
2. Merge website changes into main, or run Deploy Live Demo manually on main.
3. Open https://ai-calypse.github.io/avatar-studio/ after the deployment succeeds.

Run npm run build:pages locally to inspect the generated artifact. The hosted site is a browser-only avatar editor; the MCP server runs locally and is not exposed by Pages.

Website documentation

The site documentation lives at /docs/. Run npm run build:docs to generate eight navigable pages from this README, mcp/README.md, and mcp/SECURITY.md; npm run dev builds them automatically. The Pages build includes the docs and their visual assets. Edit the Markdown sources and rebuild rather than editing generated HTML. Layout and search are maintained in docs/docs.css and docs/docs.js. Documentation is maintained in English. The header language menu offers opt-in full-page Google Translate translations, with twelve language shortcuts and access to more languages. Code blocks and inline identifiers are marked translate="no". Translation opens in an external service; original English guides and local search remain available. Text embedded in example images stays as drawn. The creator remains available in nine languages through local catalogs.

The creator’s In use section includes all 48 README use cases, loaded from the same manifest, with translated captions, category filters, and search. Its four live previews continue to show your current avatar design.