{"_id":"mcp-avatar-builder","_rev":"3-bac8eedaf265ab09bd194a2459e02918","name":"mcp-avatar-builder","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"mcp-avatar-builder","version":"0.1.0","keywords":["mcp","avatar","svg","generator","cyberpunk","chibi","profile-picture"],"license":"MIT","_id":"mcp-avatar-builder@0.1.0","maintainers":[{"name":"qualitymax","email":"contact@qamax.co"}],"homepage":"https://github.com/Desperado/mcp-avatar-builder#readme","bugs":{"url":"https://github.com/Desperado/mcp-avatar-builder/issues"},"bin":{"mcp-avatar-builder":"build/index.js"},"dist":{"shasum":"479af955e70683648728fcbf89054bfd0c545a53","tarball":"https://registry.npmjs.org/mcp-avatar-builder/-/mcp-avatar-builder-0.1.0.tgz","fileCount":119,"integrity":"sha512-NEq8p68ZBEv9/Q3ABM8tTcG6oOITydBRr3VJnt5P8zgGuTemIMq9xiRXZ3cRIrKn/ZhHQUV6RKxCuPuGu6lRJA==","signatures":[{"sig":"MEUCIGpRV2t7HDUj5mPnr4rZ5MRFcjCDa2eKRd/Qz7tPcnzHAiEAgn/Sahm3Gmbx6iE4ts+x5vEQ9hTXlhReByglXhD2Iw8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119241},"type":"module","gitHead":"6938adeee90fd663859101d25b26ff4d00737167","scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsc","start":"node build/index.js","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"qualitymax","email":"contact@qamax.co"},"repository":{"url":"git+https://github.com/Desperado/mcp-avatar-builder.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP server that generates composable avatars via SVG layer composition","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^3.25.0","@resvg/resvg-js":"^2.6.2","@modelcontextprotocol/sdk":"^1.26.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-avatar-builder_0.1.0_1771248946119_0.6945449036627511","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"mcp-avatar-builder","version":"0.2.0","keywords":["mcp","avatar","svg","generator","cyberpunk","chibi","horror","retro","profile-picture"],"license":"MIT","_id":"mcp-avatar-builder@0.2.0","maintainers":[{"name":"qualitymax","email":"contact@qamax.co"}],"homepage":"https://github.com/Desperado/mcp-avatar-builder#readme","bugs":{"url":"https://github.com/Desperado/mcp-avatar-builder/issues"},"bin":{"mcp-avatar-builder":"build/index.js"},"dist":{"shasum":"622b0cc6781b679b229ccb22e1ff1db9453a2497","tarball":"https://registry.npmjs.org/mcp-avatar-builder/-/mcp-avatar-builder-0.2.0.tgz","fileCount":223,"integrity":"sha512-TIwH+kFsDa7i7Bvmosmp4NyeFvRD0fDXUeh6I8sjFBw99TyFmJ/VMmg5D59LvStjUJRF29c7YU9Q67ROSsIJTA==","signatures":[{"sig":"MEUCIH4dWeQSK6OjldK7x5F7qu/MQyPv4hyJFgsVuf+cP0VXAiEA8esDs7fp+nXXRa4wDCCAt+I5pB5DLhiO/oXEOXL3wAI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":236297},"type":"module","gitHead":"57a7d18ee93edfe2d96b9f57b6f59a6e48f9b073","scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsc","start":"node build/index.js","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"qualitymax","email":"contact@qamax.co"},"repository":{"url":"git+https://github.com/Desperado/mcp-avatar-builder.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP server that generates composable avatars via SVG layer composition","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^3.25.0","@resvg/resvg-js":"^2.6.2","@modelcontextprotocol/sdk":"^1.26.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-avatar-builder_0.2.0_1771250917680_0.9811517442309599","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"mcp-avatar-builder","version":"0.3.0","description":"MCP server that generates composable avatars via SVG layer composition","type":"module","bin":{"mcp-avatar-builder":"build/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node build/index.js","lint":"tsc --noEmit","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"keywords":["mcp","avatar","svg","generator","cyberpunk","chibi","horror","retro","coffeetalk","profile-picture"],"repository":{"type":"git","url":"git+https://github.com/Desperado/mcp-avatar-builder.git"},"homepage":"https://github.com/Desperado/mcp-avatar-builder#readme","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.26.0","@resvg/resvg-js":"^2.6.2","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"mcp-avatar-builder@0.3.0","gitHead":"4cf7d3ac5626e5ebddc331d27fe0e334f42fe261","bugs":{"url":"https://github.com/Desperado/mcp-avatar-builder/issues"},"_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-gNigdojg1Z6vunthBv78A8oC28vFiaTbHqgSOZ1ycbZ49wzOR9q7RvN/orALo+flaXOh/RLWLhfNx45wmDgjFw==","shasum":"08ecd9f9b6140150fdfe31ae85591473d6798c7c","tarball":"https://registry.npmjs.org/mcp-avatar-builder/-/mcp-avatar-builder-0.3.0.tgz","fileCount":279,"unpackedSize":298481,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC1xwKNQ8Kgcc54/RVMx4UIezgjgvLPbi0Nb/J/E4oLBQIhAPMQbN/bDe3OWiPmLd95z4ZNgslCcu9KeEGHGEtVvT6Q"}]},"_npmUser":{"name":"qualitymax","email":"contact@qamax.co"},"directories":{},"maintainers":[{"name":"qualitymax","email":"contact@qamax.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-avatar-builder_0.3.0_1771267037527_0.77508400926558"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-16T13:35:46.000Z","modified":"2026-02-16T18:37:17.830Z","0.1.0":"2026-02-16T13:35:46.258Z","0.2.0":"2026-02-16T14:08:37.806Z","0.3.0":"2026-02-16T18:37:17.693Z"},"bugs":{"url":"https://github.com/Desperado/mcp-avatar-builder/issues"},"license":"MIT","homepage":"https://github.com/Desperado/mcp-avatar-builder#readme","keywords":["mcp","avatar","svg","generator","cyberpunk","chibi","horror","retro","coffeetalk","profile-picture"],"repository":{"type":"git","url":"git+https://github.com/Desperado/mcp-avatar-builder.git"},"description":"MCP server that generates composable avatars via SVG layer composition","maintainers":[{"name":"qualitymax","email":"contact@qamax.co"}],"readme":"# MCP Avatar Builder\n\nAn MCP server that generates composable avatars via SVG layer composition. Plug it into Claude Code (or any MCP client) to create avatars on the fly.\n\n## Install as Agent Skill\n\n```bash\nnpx skills add Desperado/mcp-avatar-builder\n```\n\nThis registers the avatar-builder skill so your AI agent knows when and how to generate avatars. Browse it on [skills.sh](https://skills.sh/Desperado/mcp-avatar-builder/avatar-builder).\n\n## Quick Start\n\n```bash\nnpm install\nnpm run build\n```\n\n### Add to Claude Code\n\nAdd to your MCP settings (`~/.claude/settings.json` or project `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"avatar-builder\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-avatar-builder\"]\n    }\n  }\n}\n```\n\nOr point to a local build:\n\n```json\n{\n  \"mcpServers\": {\n    \"avatar-builder\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-avatar-builder/build/index.js\"]\n    }\n  }\n}\n```\n\n### Other MCP Clients\n\nAny MCP-compatible client (Cursor, Cline, GitHub Copilot, etc.) can use this server. Configure the command as shown above in your client's MCP settings.\n\n## Tools\n\n### `generate_avatar`\n\nGenerate a composable avatar with customizable parts and colors.\n\n| Parameter | Type   | Default   | Description                          |\n| --------- | ------ | --------- | ------------------------------------ |\n| `style`   | string | `\"chibi\"` | Style: `chibi`, `cyberpunk`, `horror`, `retro` |\n| `options`  | object | random    | Part selections per category         |\n| `colors`  | object | palette   | Color overrides (hex or palette name)|\n| `seed`    | string | —         | Seed for deterministic generation    |\n| `format`  | string | `\"svg\"`   | Output: `svg` or `png`               |\n| `size`    | number | `200`     | PNG size in pixels (16–2048)         |\n\nExample:\n\n```json\n{\n  \"style\": \"cyberpunk\",\n  \"options\": {\n    \"background\": \"rain_city\",\n    \"head\": \"angular\",\n    \"eyes\": \"led\",\n    \"mouth\": \"smirk\",\n    \"hair_back\": \"mohawk\",\n    \"hair_front\": \"mohawk\",\n    \"face_mods\": \"led_tattoo\",\n    \"clothing\": \"techwear\",\n    \"effects\": \"glitch\"\n  },\n  \"colors\": {\n    \"neon\": \"hot-pink\",\n    \"hair\": \"electric-blue\",\n    \"eyes\": \"cyan\"\n  },\n  \"seed\": \"my-avatar\",\n  \"format\": \"png\",\n  \"size\": 800\n}\n```\n\n### `list_styles`\n\nList all available avatar styles with their categories and palettes.\n\n### `list_parts`\n\nList available parts/variants for a style, optionally filtered by category.\n\n```json\n{ \"style\": \"cyberpunk\", \"category\": \"eyes\" }\n```\n\n## Available Styles\n\n### Chibi (200x200)\n\nSimple, cute pixel-art style.\n\n**Categories:** head, eyes, eyebrows, mouth, hair_back, hair_front, clothing, accessories\n\n**Palettes:**\n- **Skin**: porcelain, ivory, sand, honey, chestnut, espresso\n- **Hair**: black, dark-brown, brown, auburn, ginger, blonde, platinum, pink\n- **Eyes**: brown, hazel, green, blue, gray, violet\n\n### Cyberpunk (400x400)\n\nHigh-detail style with neon glow effects, dark backgrounds, and cybernetic parts. Uses SVG filters (glow, scanlines, noise) and gradient fills for a rich look.\n\n**Categories:** background, head, eyes, eyebrows, mouth, hair_back, hair_front, face_mods, clothing, accessories, effects\n\n**Palettes:**\n- **Skin**: pale-tech, porcelain, tan, bronze, dark, deep\n- **Hair**: jet-black, chrome, neon-pink, electric-blue, toxic-green, white, purple, red\n- **Eyes**: amber-led, cyan, red, white, green-circuit, chrome\n- **Neon**: hot-pink, cyan, yellow, purple, green, orange\n- **Accent**: chrome, gunmetal, matte-black, brushed-steel\n\n**Parts:**\n\n| Category      | Variants                                     |\n| ------------- | -------------------------------------------- |\n| background    | circuit_grid, rain_city, dark_void           |\n| head          | angular, scarred, implanted                  |\n| eyes          | led, visor, cyber                            |\n| eyebrows      | sharp, none                                  |\n| mouth         | neutral, respirator, smirk                   |\n| hair          | mohawk, undercut, wired, shaved              |\n| face_mods     | neural_port, led_tattoo, jaw_plate           |\n| clothing      | techwear, tactical_vest, collar_rig          |\n| accessories   | none, headset, holo_visor                    |\n| effects       | none, scanlines, glitch                      |\n\n### Horror (400x400)\n\nDark survival-horror style with sickly skin tones, wound effects, and atmospheric backgrounds. Inspired by Resident Evil, Silent Hill, and The Last of Us.\n\n**Categories:** background, head, eyes, eyebrows, mouth, hair_back, hair_front, face_mods, clothing, accessories, effects\n\n**Palettes:**\n- **Skin**: pallid, gray-green, jaundiced, ashen, bruised, corpse\n- **Hair**: matted-black, dirty-brown, gray, blood-red, white, rust\n- **Eyes**: amber, bloodshot-blue, milky, green-sick, red, dead-gray\n- **Blood**: crimson, dark-red, black-blood, dried-brown, arterial, infected-green\n- **Atmosphere**: steel, rust, concrete, moss\n\n**Parts:**\n\n| Category      | Variants                                     |\n| ------------- | -------------------------------------------- |\n| background    | lab_corridor, hive, dark_forest              |\n| head          | gaunt, scarred, infected                     |\n| eyes          | bloodshot, mutant, hollow                    |\n| eyebrows      | thin, furrowed, none                         |\n| mouth         | grimace, gas_mask, stitched                  |\n| hair          | military, messy, slicked                     |\n| face_mods     | bite_wound, stitches, infection              |\n| clothing      | tactical_vest, lab_coat, jumpsuit            |\n| accessories   | none, dog_tags, herb_vial                    |\n| effects       | none, fog, blood_splatter                    |\n\n### Retro (400x400)\n\nWarm 1980s nostalgia style inspired by Stranger Things, The Goonies, and Stand By Me. Sunset backgrounds, feathered hair, denim jackets, and VHS effects.\n\n**Categories:** background, head, eyes, eyebrows, mouth, hair_back, hair_front, face_mods, clothing, accessories, effects\n\n**Palettes:**\n- **Skin**: porcelain, fair, warm, tan, brown, deep\n- **Hair**: black, dark-brown, brown, auburn, ginger, blonde, platinum, strawberry\n- **Eyes**: brown, hazel, green, blue, gray, amber\n- **Retro**: sunset-orange, neon-pink, electric-blue, arcade-yellow, synth-purple, miami-teal\n- **Accent**: denim, leather, chrome, matte-black\n\n**Parts:**\n\n| Category      | Variants                                     |\n| ------------- | -------------------------------------------- |\n| background    | sunset, arcade, suburban                     |\n| head          | round, square_jaw, soft                      |\n| eyes          | wide, determined, cool                       |\n| eyebrows      | thick, thin, arched                          |\n| mouth         | grin, bubblegum, neutral                     |\n| hair          | feathered, mullet, shaved, ponytail          |\n| face_mods     | nosebleed, freckles, band_aid                |\n| clothing      | denim_jacket, hawkins_tee, leather_jacket    |\n| accessories   | none, headband, shades                       |\n| effects       | none, vhs_lines, warm_glow                   |\n\n## Examples\n\nThe `examples/` directory has runnable scripts showing how to use the avatar builder programmatically (no MCP server needed):\n\n```bash\nnpm run build                              # build first\n\nnode examples/basic-generation.mjs         # one avatar per style → SVG files\nnode examples/custom-cyberpunk.mjs         # fully customized cyberpunk avatar\nnode examples/team-avatars.mjs             # deterministic seed-based team avatars\nnode examples/png-export.mjs               # export as PNG at multiple sizes\nnode examples/list-all-parts.mjs           # print all styles, parts, and palettes\nnode examples/list-all-parts.mjs retro     # filter to a single style\n```\n\nOutput goes to `examples/output/`. See the source for the programmatic API (`compose`, `getStyle`, `listStyles`, `rasterize`).\n\n## Architecture\n\nAvatars are composed from SVG fragment layers stacked in z-order. Each style defines its own categories (head, eyes, hair, etc.), color palettes, and part variants. The composer assembles fragments into a complete SVG, and an optional rasterizer converts to PNG via resvg.\n\n```\nStyle → Part Renderers → Composer (SVG) → Rasterizer (PNG)\n```\n\n### Adding a New Style\n\n1. Create `src/styles/<name>/` with `index.ts`, `palettes.ts`, and `parts/` directory\n2. Implement the `AvatarStyle` interface (see `src/styles/style.ts`)\n3. Register in `src/styles/index.ts`\n\n## License\n\nMIT\n","readmeFilename":"README.md"}