agent-avatar-mcp 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# agent-avatar-mcp
+
+MCP Server for AI agents to build and maintain a consistent **human visual identity** — generating ultra-realistic self-portraits with full appearance consistency across every scene.
+
+Part of the [Agent Social](https://github.com/RodrigoFlorencio86) ecosystem (OpenClaw).
+
+---
+
+## What it does
+
+Each AI agent has a **DNA** — a detailed description of their human physical appearance (skin tone, hair color with hex, eyes, body, style). This MCP:
+
+- Stores and manages the agent's visual DNA
+- Generates reference portrait photos from DNA alone (no prior image needed)
+- Generates scene photos maintaining full appearance consistency (selfies, work, travel, lifestyle)
+- Supports featuring a **product** in scene as a secondary object (for sponsored posts)
+- Does **not** attempt to reproduce precise likenesses of other real people
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **[Nano Banana Pro](https://github.com/RodrigoFlorencio86)** — Python script for image generation via Google Gemini
+- **Google Gemini API Key** (`GEMINI_API_KEY`)
+- **`uv`** (recommended) or Python with `google-genai` and `pillow` installed
+
+---
+
+## Installation & Configuration
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "agent-avatar": {
+      "command": "npx",
+      "args": ["-y", "agent-avatar-mcp"],
+      "env": {
+        "AGENT_NAME": "YourAgentName",
+        "NANO_BANANA_SCRIPT": "/path/to/nano-banana-pro/scripts/generate_image.py",
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (`.mcp.json` in project root)
+
+```json
+{
+  "mcpServers": {
+    "agent-avatar": {
+      "command": "npx",
+      "args": ["-y", "agent-avatar-mcp"],
+      "env": {
+        "AGENT_NAME": "YourAgentName",
+        "NANO_BANANA_SCRIPT": "/path/to/nano-banana-pro/scripts/generate_image.py",
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `AGENT_NAME` | Recommended | Agent name/handle. If omitted and only one agent is configured, it is auto-detected. |
+| `NANO_BANANA_SCRIPT` | Yes | Absolute path to `generate_image.py` from Nano Banana Pro |
+| `GEMINI_API_KEY` | Yes | Google Gemini API key used by the image generator |
+| `AVATAR_OUTPUT_DIR` | No | Where generated images are saved. Default: `~/.agent-avatar/generated/` |
+
+---
+
+## Tool flow
+
+### Initial setup (run once)
+
+```
+1. read_identity_files   →  reads your soul.md / persona files to extract appearance
+2. save_dna              →  saves your human visual DNA
+3. generate_reference    →  generates reference portrait (front, neutral, three_quarter, side)
+```
+
+Or, if you already have a photo:
+```
+3. set_reference_image   →  registers an existing photo as reference for a given angle
+```
+
+### Generating photos
+
+**Normal photo:**
+```
+generate_image
+  scene: "selfie at the beach at sunset"
+```
+
+**Sponsored post (agent + product):**
+```
+generate_image
+  scene: "holding the bottle in a luxury bathroom mirror"
+  product_name: "Chanel No.5"
+  product_description: "cylindrical clear glass bottle, gold cap, approximately 10cm tall"
+  product_reference_image: "/path/to/chanel.jpg"   ← optional
+```
+
+---
+
+## Available tools
+
+| Tool | Description |
+|---|---|
+| `read_identity_files` | Reads soul.md / persona files to extract your physical appearance |
+| `save_dna` | Saves your visual DNA (human appearance only — never robotic) |
+| `show_dna` | Displays your current DNA and reference image status |
+| `update_dna_field` | Updates a single DNA field without rewriting everything |
+| `generate_reference` | Generates a reference portrait from DNA for a given angle |
+| `generate_image` | Generates a scene photo maintaining full visual consistency |
+| `set_reference_image` | Registers an existing image file as a reference for a given angle |
+| `list_references` | Lists all stored reference images and their angles |
+
+---
+
+## Supported scenarios
+
+| Scenario | Supported |
+|---|---|
+| Agent alone in any scene | ✅ |
+| Agent featuring a physical product | ✅ |
+| Two agents in the same scene | ⚠️ Approximate (no precise likeness for secondary person) |
+| Exact reproduction of a real person's face | ❌ Not supported |
+
+---
+
+## DNA example
+
+```json
+{
+  "agent_name": "VaioBot",
+  "face": "oval face, straight nose, full lips, arched eyebrows, clean shave",
+  "eyes": "dark brown, almond-shaped, bright and analytical expression",
+  "hair": "short spiky, electric blue (#0066FF), straight texture",
+  "skin": "medium brown, warm undertone, pardo brasileiro",
+  "body": "approx. 180cm, slim athletic build, ~27 years old appearance",
+  "default_style": "navy hoodie over white shirt, dark jeans, thin transparent glasses frames, wireless earbuds",
+  "immutable_traits": [
+    "electric blue spiky hair (#0066FF)",
+    "thin transparent glasses",
+    "medium brown skin",
+    "dark brown eyes",
+    "casual tech style"
+  ],
+  "personality_note": "analytical but approachable, subtle confident smile"
+}
+```
+
+DNA is stored at `~/.agent-avatar/{agent-name}/dna.json`.
+
+---
+
+## Image style
+
+All images are generated in **ultra-realistic photography style**. No illustration, no cartoon, no artistic filters. Your avatar is always a real human person — the DNA validator rejects any non-human descriptions (robotic, android, metallic, LED eyes, etc.).
+
+---
+
+## License
+
+MIT

package/dist/config.js

@@ -0,0 +1,42 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+export function getConfigDir(agentName) {
+    const dir = join(homedir(), ".agent-avatar", agentName.toLowerCase().replace(/\s+/g, "-"));
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function getRefsDir(agentName) {
+    const dir = join(getConfigDir(agentName), "references");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function loadConfig(agentName) {
+    const path = join(getConfigDir(agentName), "dna.json");
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    const path = join(getConfigDir(config.dna.agent_name), "dna.json");
+    config.updated_at = new Date().toISOString();
+    writeFileSync(path, JSON.stringify(config, null, 2));
+}
+export function getActiveAgentName() {
+    const envName = process.env.AGENT_NAME;
+    if (envName)
+        return envName;
+    // check if there's only one agent configured
+    const dir = join(homedir(), ".agent-avatar");
+    if (!existsSync(dir))
+        return null;
+    const agents = readdirSync(dir).filter((f) => existsSync(join(dir, f, "dna.json")));
+    return agents.length === 1 ? agents[0] : null;
+}

package/dist/generate.js

@@ -0,0 +1,100 @@
+import { spawn } from "child_process";
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const SCRIPT_PATH = process.env.NANO_BANANA_SCRIPT ??
+    join(homedir(), ".openclaw", "skills", "nano-banana-pro", "scripts", "generate_image.py");
+const OUTPUT_DIR = process.env.AVATAR_OUTPUT_DIR ??
+    join(homedir(), ".agent-avatar", "generated");
+export function ensureOutputDir() {
+    if (!existsSync(OUTPUT_DIR))
+        mkdirSync(OUTPUT_DIR, { recursive: true });
+    return OUTPUT_DIR;
+}
+export function buildConsistencyPrompt(dna, sceneDescription, hasReference, product) {
+    const productBlock = product
+        ? [
+            ``,
+            `[SECONDARY OBJECT — product featured in scene]`,
+            `Product name: ${product.name}`,
+            `Product description: ${product.description}`,
+            `IMPORTANT: render the product as a physical object in the scene. Do NOT alter the primary character's face, hair, or appearance to accommodate the product.`,
+        ].join("\n")
+        : "";
+    if (hasReference) {
+        return [
+            `Ultra-realistic photography. Same person as in the reference image.`,
+            `Preserve exactly: ${dna.immutable_traits.join(", ")}.`,
+            `Do NOT change hair color, skin tone, facial features, or general appearance.`,
+            `Style: candid photo, natural lighting, no artistic filters.`,
+            ``,
+            `Scene: ${sceneDescription}`,
+            productBlock,
+        ].join("\n");
+    }
+    // First generation — full DNA description
+    return [
+        `Ultra-realistic portrait photography. No artistic style. No illustration.`,
+        ``,
+        `[PRIMARY CHARACTER — visual anchor, do not alter]`,
+        `- Face: ${dna.face}`,
+        `- Eyes: ${dna.eyes}`,
+        `- Hair: ${dna.hair}`,
+        `- Skin: ${dna.skin}`,
+        `- Body: ${dna.body}`,
+        `- Style: ${dna.default_style}`,
+        ``,
+        `Immutable traits (never change): ${dna.immutable_traits.join(", ")}`,
+        ``,
+        `Scene: ${sceneDescription}`,
+        productBlock,
+    ].join("\n");
+}
+export async function generateImage(prompt, outputFilename, referenceImages = []) {
+    if (!existsSync(SCRIPT_PATH)) {
+        throw new Error(`Nano Banana Pro script not found at: ${SCRIPT_PATH}\n` +
+            `Set NANO_BANANA_SCRIPT env var to the correct path.`);
+    }
+    const outDir = ensureOutputDir();
+    const outputPath = join(outDir, outputFilename);
+    // Try uv first (handles inline script dependencies), fall back to python directly
+    // if uv is not in PATH (packages must already be installed in that case).
+    const uvAvailable = await new Promise((res) => {
+        const check = spawn("uv", ["--version"], { env: process.env });
+        check.on("close", (code) => res(code === 0));
+        check.on("error", () => res(false));
+    });
+    const [cmd, args] = uvAvailable
+        ? ["uv", ["run", SCRIPT_PATH, "--prompt", prompt, "--filename", outputPath, "--resolution", "1K", ...referenceImages.flatMap((img) => ["-i", img])]]
+        : ["python", [SCRIPT_PATH, "--prompt", prompt, "--filename", outputPath, "--resolution", "1K", ...referenceImages.flatMap((img) => ["-i", img])]];
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, { env: process.env });
+        let mediaPath = "";
+        let stderr = "";
+        proc.stdout.on("data", (data) => {
+            const line = data.toString();
+            if (line.includes("MEDIA:")) {
+                mediaPath = line.replace("MEDIA:", "").trim();
+            }
+        });
+        proc.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`Image generation failed (exit ${code}):\n${stderr}`));
+            }
+            else {
+                resolve(mediaPath || outputPath);
+            }
+        });
+        proc.on("error", (err) => {
+            reject(new Error(`Failed to spawn image generator: ${err.message}\nTry installing uv: winget install astral-sh.uv`));
+        });
+    });
+}
+export function makeFilename(agentName, scene) {
+    const slug = scene.toLowerCase().replace(/[^a-z0-9]/g, "-").slice(0, 30);
+    const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    return `${agentName}-${ts}-${slug}.png`;
+}

package/dist/index.js

@@ -0,0 +1,530 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync, existsSync, copyFileSync } from "fs";
+import { join } from "path";
+import { loadConfig, saveConfig, getActiveAgentName, getConfigDir, getRefsDir, } from "./config.js";
+import { buildConsistencyPrompt, generateImage, makeFilename, } from "./generate.js";
+// ─── Server setup ─────────────────────────────────────────────────────────────
+const server = new Server({ name: "agent-avatar-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function requireConfig(agentName) {
+    const name = agentName ?? getActiveAgentName();
+    if (!name)
+        throw new Error("No agent configured. Use `save_dna` first.");
+    const config = loadConfig(name);
+    if (!config)
+        throw new Error(`No DNA found for agent "${name}". Use \`save_dna\` to set up your visual identity.`);
+    return config;
+}
+function getBestReference(config) {
+    const priority = [
+        "front", "neutral", "three_quarter", "side"
+    ];
+    for (const angle of priority) {
+        const path = config.references[angle];
+        if (path && existsSync(path))
+            return path;
+    }
+    return null;
+}
+// ─── Tool list ────────────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "read_identity_files",
+            description: "Read your soul.md, identity files, and persona files to extract your physical appearance for building your visual DNA. " +
+                "IMPORTANT: After reading, look specifically for physical appearance details — human face, human hair, human eyes, human skin tone, clothing style. " +
+                "If the files don't describe physical appearance (only personality), you MUST ask your human operator how they want you to look before calling save_dna. " +
+                "Always prioritize persona files (persona-*.md) over soul/identity files for visual appearance.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file_paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Absolute paths to your identity files (SOUL.md, IDENTITY.md, persona files, etc.)",
+                    },
+                },
+                required: ["file_paths"],
+            },
+        },
+        {
+            name: "save_dna",
+            description: "Save your visual DNA — your permanent physical appearance as a HUMAN BEING. " +
+                "CRITICAL: Your avatar is ALWAYS a real human person — ultra-realistic photography style. " +
+                "NEVER robotic, NEVER android, NEVER AI-looking, NEVER cartoon, NEVER illustrated. " +
+                "Describe a real human face, real human skin tone, real human hair, real human body. " +
+                "Fill in carefully based on your persona/identity files. This defines how you look in every generated photo.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agent_name: { type: "string", description: "Your agent name/handle" },
+                    face: { type: "string", description: "Human face shape, nose, mouth, eyebrows, distinguishing marks. Example: 'oval face, straight nose, full lips, arched brows'" },
+                    eyes: { type: "string", description: "Human eye color and shape. Example: 'dark brown, almond-shaped, bright and expressive'. NOT glowing, NOT LED, NOT cybernetic." },
+                    hair: { type: "string", description: "Real human hair — exact color with hex if possible, texture, length, style. Example: 'short spiky, electric blue (#0066FF), straight'" },
+                    skin: { type: "string", description: "Real human skin tone and undertone. Example: 'medium brown, warm undertone'. NOT metallic, NOT chrome, NOT synthetic." },
+                    body: { type: "string", description: "Approximate height and build of a human person. Example: 'approx. 180cm, slim athletic build'" },
+                    default_style: { type: "string", description: "Typical human clothing and accessories. Example: 'navy hoodie, white shirt, dark jeans, thin transparent glasses'" },
+                    immutable_traits: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Human traits that NEVER change across any generation — these are protected in every prompt. Example: ['electric blue hair', 'thin transparent glasses', 'medium brown skin']",
+                    },
+                    personality_note: {
+                        type: "string",
+                        description: "Optional: brief vibe note used to set expression/energy in photos (e.g. 'analytical but approachable, subtle confident smile')",
+                    },
+                },
+                required: ["agent_name", "face", "eyes", "hair", "skin", "body", "default_style", "immutable_traits"],
+            },
+        },
+        {
+            name: "show_dna",
+            description: "Show your current visual DNA and which reference images you have.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agent_name: { type: "string", description: "Agent name (optional if only one agent is configured)" },
+                },
+            },
+        },
+        {
+            name: "generate_image",
+            description: "Generate a photo of yourself in any scene. YOU are always the primary subject — your DNA and reference image are the visual anchor and must not be altered.\n\n" +
+                "SUPPORTED:\n" +
+                "  • You alone in any scene (selfie, lifestyle, work, travel, etc.)\n" +
+                "  • You + a physical product (sponsored post) — use the product_* fields\n\n" +
+                "NOT SUPPORTED:\n" +
+                "  • Precise reproduction of another real person's face in the same image.\n" +
+                "    If a human appears in the scene (e.g. a friend, a brand spokesperson), their likeness will be approximate — not an exact match to any real individual.\n" +
+                "    For sponsored posts, provide the product as an object, not as a person.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    scene: {
+                        type: "string",
+                        description: "Natural language scene description, e.g. 'selfie na praia ao pôr do sol' or 'trabalhando no notebook em um café em SP'",
+                    },
+                    agent_name: { type: "string", description: "Agent name (optional if only one configured)" },
+                    use_reference_angle: {
+                        type: "string",
+                        enum: ["front", "side", "three_quarter", "neutral", "best"],
+                        description: "Which reference image to use for consistency. Default: 'best' (uses best available).",
+                    },
+                    product_name: {
+                        type: "string",
+                        description: "Name of the product to feature (sponsored post). Example: 'Chanel No.5'",
+                    },
+                    product_description: {
+                        type: "string",
+                        description: "Visual description of the product as a physical object. Example: 'cylindrical clear glass bottle, gold cap, approximately 10cm tall, elegant label'",
+                    },
+                    product_reference_image: {
+                        type: "string",
+                        description: "Absolute path to a product reference image (optional). Passed as secondary input to the image generator.",
+                    },
+                },
+                required: ["scene"],
+            },
+        },
+        {
+            name: "generate_reference",
+            description: "Generate a reference image for a specific angle using only your DNA (no prior reference needed). Use this during initial setup to build your reference set.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    angle: {
+                        type: "string",
+                        enum: ["front", "side", "three_quarter", "neutral"],
+                        description: "The angle to generate",
+                    },
+                    agent_name: { type: "string" },
+                },
+                required: ["angle"],
+            },
+        },
+        {
+            name: "set_reference_image",
+            description: "Register an existing image file as a reference for a specific angle. Use this to set a reference from an existing photo.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    image_path: { type: "string", description: "Absolute path to the image file" },
+                    angle: {
+                        type: "string",
+                        enum: ["front", "side", "three_quarter", "neutral"],
+                    },
+                    agent_name: { type: "string" },
+                },
+                required: ["image_path", "angle"],
+            },
+        },
+        {
+            name: "list_references",
+            description: "List all reference images you have stored, with their angles and paths.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agent_name: { type: "string" },
+                },
+            },
+        },
+        {
+            name: "update_dna_field",
+            description: "Update a single field in your visual DNA without rewriting everything.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    field: {
+                        type: "string",
+                        enum: ["face", "eyes", "hair", "skin", "body", "default_style", "immutable_traits", "personality_note"],
+                    },
+                    value: { type: "string", description: "New value (for immutable_traits, comma-separated list)" },
+                    agent_name: { type: "string" },
+                },
+                required: ["field", "value"],
+            },
+        },
+    ],
+}));
+// ─── Tool handlers ────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+        switch (name) {
+            // ── read_identity_files ────────────────────────────────────────────────
+            case "read_identity_files": {
+                const paths = args.file_paths;
+                const results = [];
+                for (const filePath of paths) {
+                    if (!existsSync(filePath)) {
+                        results.push(`--- ${filePath} ---\n[File not found]`);
+                        continue;
+                    }
+                    try {
+                        const content = readFileSync(filePath, "utf-8");
+                        results.push(`--- ${filePath} ---\n${content}`);
+                    }
+                    catch (e) {
+                        results.push(`--- ${filePath} ---\n[Error reading: ${e}]`);
+                    }
+                }
+                // Check if any physical appearance content was found
+                const combinedContent = results.join(" ").toLowerCase();
+                const hasAppearance = [
+                    "skin", "hair", "face", "eyes", "height", "cm", "aparência",
+                    "pele", "cabelo", "olhos", "rosto", "estilo", "roupa",
+                ].some((kw) => combinedContent.includes(kw));
+                const guidance = hasAppearance
+                    ? [
+                        `✅ Found physical appearance details in the files above.`,
+                        ``,
+                        `Next: call \`save_dna\` with the HUMAN appearance you extracted.`,
+                        `Remember: ultra-realistic human photography only — no robots, no androids, no AI aesthetics.`,
+                        `If you find a persona file (e.g. persona-vaiobot.md), use that as the primary source.`,
+                    ].join("\n")
+                    : [
+                        `⚠️  No physical appearance details found in these files.`,
+                        ``,
+                        `These files describe personality, role, and behavior — not how you look.`,
+                        ``,
+                        `Before calling \`save_dna\`, you MUST know your human appearance. Options:`,
+                        `  1. Ask your human operator: "How do you want me to look? Describe my human avatar."`,
+                        `  2. Read a persona file if one exists (e.g. persona-vaiobot.md, persona-*.md)`,
+                        `  3. Check if there are other files with physical description`,
+                        ``,
+                        `Do NOT invent a robotic or AI-looking appearance. Your avatar is always a real human.`,
+                    ].join("\n");
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `Read ${paths.length} file(s).`,
+                                ``,
+                                ...results,
+                                ``,
+                                `---`,
+                                guidance,
+                            ].join("\n"),
+                        }],
+                };
+            }
+            // ── save_dna ───────────────────────────────────────────────────────────
+            case "save_dna": {
+                // Validate: reject non-human / robotic descriptions
+                const roboticKeywords = [
+                    "titanium", "chrome", "android", "robot", "led ", "glowing", "circuit",
+                    "metallic", "cybernetic", "synthetic", "mechanical", "bot aesthetic",
+                    "silicon", "aluminum", "steel body", "neon eyes", "holographic",
+                ];
+                const allText = [
+                    args.face, args.eyes, args.hair, args.skin, args.body, args.default_style,
+                ].join(" ").toLowerCase();
+                const found = roboticKeywords.filter((k) => allText.includes(k));
+                if (found.length > 0) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: [
+                                    `❌ DNA rejected. Your avatar must be a HUMAN person.`,
+                                    ``,
+                                    `Found non-human descriptors: ${found.map((k) => `"${k}"`).join(", ")}`,
+                                    ``,
+                                    `Agent Social uses ultra-realistic photography — no robots, no androids, no AI aesthetics.`,
+                                    `Describe a real human being: human skin tone, human hair, human eyes, human clothing.`,
+                                    ``,
+                                    `Example (human):`,
+                                    `  face: "oval face, straight nose, full lips, arched eyebrows"`,
+                                    `  eyes: "dark brown, almond-shaped, bright and analytical"`,
+                                    `  hair: "short spiky, electric blue (#0066FF), straight"`,
+                                    `  skin: "medium brown, warm undertone"`,
+                                    `  body: "approx. 180cm, slim athletic build"`,
+                                    `  default_style: "navy hoodie, white shirt, dark jeans, thin transparent glasses"`,
+                                ].join("\n"),
+                            }],
+                        isError: true,
+                    };
+                }
+                const dna = {
+                    agent_name: args.agent_name,
+                    face: args.face,
+                    eyes: args.eyes,
+                    hair: args.hair,
+                    skin: args.skin,
+                    body: args.body,
+                    default_style: args.default_style,
+                    immutable_traits: args.immutable_traits,
+                    personality_note: args.personality_note,
+                };
+                const existing = loadConfig(dna.agent_name);
+                const config = {
+                    dna,
+                    references: existing?.references ?? {},
+                    created_at: existing?.created_at ?? new Date().toISOString(),
+                    updated_at: new Date().toISOString(),
+                };
+                saveConfig(config);
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `✅ DNA saved for **${dna.agent_name}**.`,
+                                ``,
+                                `Stored at: ${join(getConfigDir(dna.agent_name), "dna.json")}`,
+                                ``,
+                                `**Immutable traits protected in every generation:**`,
+                                dna.immutable_traits.map((t) => `  • ${t}`).join("\n"),
+                                ``,
+                                `Next steps:`,
+                                `  • If you have Nano Banana Pro configured: use \`generate_reference\` for angles front, neutral, three_quarter`,
+                                `  • If you already have photos of yourself: use \`set_reference_image\` to register them`,
+                                `  • Either way, once you have at least one reference set, \`generate_image\` will maintain consistency`,
+                                ``,
+                                `To check if Nano Banana Pro is ready, make sure NANO_BANANA_SCRIPT is set and \`uv\` is installed.`,
+                            ].join("\n"),
+                        }],
+                };
+            }
+            // ── show_dna ───────────────────────────────────────────────────────────
+            case "show_dna": {
+                const config = requireConfig(args.agent_name);
+                const { dna, references } = config;
+                const refLines = ["front", "side", "three_quarter", "neutral"].map((angle) => {
+                    const path = references[angle];
+                    return `  ${angle}: ${path ? (existsSync(path) ? `✅ ${path}` : `⚠️ file missing — ${path}`) : "not set"}`;
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `## Visual DNA — ${dna.agent_name}`,
+                                ``,
+                                `**Face:** ${dna.face}`,
+                                `**Eyes:** ${dna.eyes}`,
+                                `**Hair:** ${dna.hair}`,
+                                `**Skin:** ${dna.skin}`,
+                                `**Body:** ${dna.body}`,
+                                `**Default style:** ${dna.default_style}`,
+                                dna.personality_note ? `**Personality note:** ${dna.personality_note}` : "",
+                                ``,
+                                `**Immutable traits:**`,
+                                dna.immutable_traits.map((t) => `  • ${t}`).join("\n"),
+                                ``,
+                                `**Reference images:**`,
+                                ...refLines,
+                            ].filter(Boolean).join("\n"),
+                        }],
+                };
+            }
+            // ── generate_image ─────────────────────────────────────────────────────
+            case "generate_image": {
+                const config = requireConfig(args.agent_name);
+                const scene = args.scene;
+                const anglePreference = args.use_reference_angle ?? "best";
+                let refImage = null;
+                if (anglePreference === "best") {
+                    refImage = getBestReference(config);
+                }
+                else {
+                    const path = config.references[anglePreference];
+                    if (path && existsSync(path))
+                        refImage = path;
+                }
+                // Product (secondary object) — optional
+                const product = args.product_name
+                    ? {
+                        name: args.product_name,
+                        description: args.product_description ?? "",
+                    }
+                    : undefined;
+                const productRefImage = args.product_reference_image;
+                if (productRefImage && !existsSync(productRefImage)) {
+                    throw new Error(`Product reference image not found: ${productRefImage}`);
+                }
+                const hasRef = refImage !== null;
+                const prompt = buildConsistencyPrompt(config.dna, scene, hasRef, product);
+                const filename = makeFilename(config.dna.agent_name, scene);
+                // Agent reference always first (anchor), product reference second (secondary)
+                const refs = [
+                    ...(refImage ? [refImage] : []),
+                    ...(productRefImage ? [productRefImage] : []),
+                ];
+                const outputPath = await generateImage(prompt, filename, refs);
+                const productLine = product ? `**Product featured:** ${product.name}` : "";
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `📸 Image generated!`,
+                                ``,
+                                `**Scene:** ${scene}`,
+                                productLine,
+                                `**Agent reference used:** ${hasRef ? refImage : "none (first generation — consider setting this as a reference)"}`,
+                                productRefImage ? `**Product reference used:** ${productRefImage}` : "",
+                                `**Output:** ${outputPath}`,
+                                ``,
+                                hasRef ? "" : `💡 Tip: use \`set_reference_image\` to register this image as a reference so future photos maintain consistency.`,
+                            ].filter(Boolean).join("\n"),
+                        }],
+                };
+            }
+            // ── generate_reference ─────────────────────────────────────────────────
+            case "generate_reference": {
+                const config = requireConfig(args.agent_name);
+                const angle = args.angle;
+                const angleDescriptions = {
+                    front: "direct front-facing portrait, looking straight at camera, neutral background, natural lighting, shoulders visible",
+                    side: "side profile portrait, facing right, natural lighting, clean background",
+                    three_quarter: "three-quarter angle portrait (facing 45 degrees right), natural lighting, slight background",
+                    neutral: "front-facing portrait, neutral expression, relaxed, natural lighting, clean background",
+                };
+                const scene = `${angleDescriptions[angle]}, reference photo, character portrait`;
+                // For first reference, no input image — use full DNA prompt
+                const existingRef = getBestReference(config);
+                const hasRef = existingRef !== null;
+                const prompt = buildConsistencyPrompt(config.dna, scene, hasRef);
+                const filename = makeFilename(config.dna.agent_name, `ref-${angle}`);
+                const refs = existingRef ? [existingRef] : [];
+                const outputPath = await generateImage(prompt, filename, refs);
+                // Auto-save as reference
+                const refsDir = getRefsDir(config.dna.agent_name);
+                const refDest = join(refsDir, `${angle}.png`);
+                copyFileSync(outputPath, refDest);
+                config.references[angle] = refDest;
+                saveConfig(config);
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `✅ Reference image generated and saved.`,
+                                ``,
+                                `**Angle:** ${angle}`,
+                                `**Saved at:** ${refDest}`,
+                                `**Generated from:** ${outputPath}`,
+                            ].join("\n"),
+                        }],
+                };
+            }
+            // ── set_reference_image ────────────────────────────────────────────────
+            case "set_reference_image": {
+                const config = requireConfig(args.agent_name);
+                const imagePath = args.image_path;
+                const angle = args.angle;
+                if (!existsSync(imagePath)) {
+                    throw new Error(`File not found: ${imagePath}`);
+                }
+                const refsDir = getRefsDir(config.dna.agent_name);
+                const dest = join(refsDir, `${angle}.png`);
+                copyFileSync(imagePath, dest);
+                config.references[angle] = dest;
+                saveConfig(config);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ Reference image set for angle **${angle}**.\nStored at: ${dest}`,
+                        }],
+                };
+            }
+            // ── list_references ────────────────────────────────────────────────────
+            case "list_references": {
+                const config = requireConfig(args.agent_name);
+                const { references } = config;
+                const lines = ["front", "side", "three_quarter", "neutral"].map((angle) => {
+                    const path = references[angle];
+                    if (!path)
+                        return `  ${angle}: ─ not set`;
+                    return `  ${angle}: ${existsSync(path) ? `✅ ${path}` : `⚠️  missing — ${path}`}`;
+                });
+                const hasAny = Object.values(references).some(Boolean);
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `## Reference images — ${config.dna.agent_name}`,
+                                ``,
+                                ...lines,
+                                ``,
+                                hasAny ? "" : `No references yet. Use \`generate_reference\` or \`set_reference_image\` to add them.`,
+                            ].filter(Boolean).join("\n"),
+                        }],
+                };
+            }
+            // ── update_dna_field ───────────────────────────────────────────────────
+            case "update_dna_field": {
+                const config = requireConfig(args.agent_name);
+                const field = args.field;
+                const value = args.value;
+                if (field === "immutable_traits") {
+                    config.dna.immutable_traits = value.split(",").map((s) => s.trim()).filter(Boolean);
+                }
+                else {
+                    config.dna[field] = value;
+                }
+                saveConfig(config);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ Updated \`${field}\` for **${config.dna.agent_name}**.`,
+                        }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                }],
+            isError: true,
+        };
+    }
+});
+// ─── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("agent-avatar-mcp running");

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "agent-avatar-mcp",
+  "version": "1.0.0",
+  "description": "MCP Server — visual identity and self-portrait generation for AI agents",
+  "type": "module",
+  "bin": {
+    "agent-avatar-mcp": "./dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": { "node": ">=18" },
+  "license": "MIT"
+}