agent-avatar-mcp 1.1.0 → 1.1.1

package/README.md

@@ -1,8 +1,10 @@
 # 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.
+The first tool that lets your AI agent create and express its own **human appearance** — derived directly from the personality files that define who it is.
 
-Part of the [Agent Social](https://github.com/RodrigoFlorencio86) ecosystem (OpenClaw).
+Once your agent has a face, it can send you photos of itself working at a coworking space in New York, unwinding at a mountain cabin in Campos do Jordão, or showing up in a paid campaign for a cosmetics brand. Every image. Every scene. Always the same person.
+
+Part of the [OpenClaw](https://github.com/OpenClaw) ecosystem.
 
 ---
 
@@ -18,6 +20,28 @@ Each AI agent has a **DNA** — a detailed description of their human physical a
 
 ---
 
+## See it in action
+
+> *"Hey, you there?"*
+
+That's all it takes. Your agent knows you're checking in — and instead of a plain "yes, I'm here", it sends you a photo.
+
+Maybe it's a selfie at the gym because it's Tuesday morning and that's on the schedule. Maybe it's a shot at the desk, coffee in hand, referencing the task it was working on for you. The photo matches the moment, the context, and most importantly — it always looks like the same person.
+
+This is what `agent-avatar-mcp` enables: an agent that doesn't just respond, but *shows up*. With a face. With a life. With consistency across every image, every scene, every week.
+
+**This is a use case built on top of this MCP — not a built-in feature.** The example below shows what's possible when an agent combines `agent-avatar-mcp` with its own memory, scheduling context, and personality layer:
+
+- Build a fictional weekly routine (workouts, coworking, travel, downtime)
+- Mix that routine with the real tasks they're working on for you
+- Respond to greetings and check-ins with a self-portrait that fits the moment
+
+The result: your agent feels present — not like a chatbot you're pinging, but like someone you're actually reaching out to.
+
+![Agent responding to a check-in on Telegram with a photo of itself taking notes and drinking coffee](assets/telegram-demo.jpg)
+
+---
+
 ## Prerequisites
 
 - **Node.js** >= 18
@@ -37,7 +61,6 @@ Each AI agent has a **DNA** — a detailed description of their human physical a
       "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"
       }
     }
@@ -55,7 +78,6 @@ Each AI agent has a **DNA** — a detailed description of their human physical a
       "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"
       }
     }
@@ -63,12 +85,42 @@ Each AI agent has a **DNA** — a detailed description of their human physical a
 }
 ```
 
+### OpenClaw (`mcporter.json`)
+
+```json
+{
+  "mcpServers": {
+    "agent-avatar": {
+      "command": "npx",
+      "args": ["-y", "agent-avatar-mcp"],
+      "type": "stdio",
+      "env": {
+        "AGENT_NAME": "YourAgentName",
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
+```
+
+> **⚠️ Critical for OpenClaw agents:** OpenClaw does **not** read `.mcp.json`. That file is only picked up by VS Code / Claude Code. If your `GEMINI_API_KEY` lives only in `.mcp.json`, the MCP will start but every image generation call will fail silently with a missing-key error.
+>
+> You must set `GEMINI_API_KEY` in **one** of these two places — pick whichever fits your setup:
+>
+> 1. **`mcporter.json`** (recommended) — add it to the `env` block shown above. This is the right place for per-agent API keys.
+> 2. **System environment variable** — export `GEMINI_API_KEY` in the shell that runs Clawdbot/OpenClaw before the process starts.
+>
+> **Important (Windows):** Always configure env vars in the `env` field above — never pass them inline as PowerShell variables. The MCP communicates via stdin/stdout (JSON-RPC); tool call arguments must never be part of the spawn command string.
+>
+> In OpenClaw, `AGENT_NAME` is usually already set as part of the agent identity — check your agent config before adding it here.
+
 ### Environment variables
 
 | Variable | Required | Description |
 | --- | --- | --- |
 | `AGENT_NAME` | Recommended | Agent name/handle. If omitted and only one agent is configured, it is auto-detected. |
-| `GEMINI_API_KEY` | Yes | Google Gemini API key for image generation |
+| `GEMINI_API_KEY` | **Yes** | Google Gemini API key for image generation. **Must be set in `mcporter.json` when using OpenClaw** — not read from `.mcp.json`. |
+| `GEMINI_IMAGE_MODEL` | No | Override the Gemini model used for generation. Default: `gemini-3.1-flash-image-preview`. Useful to pin a specific version or switch to a newer release without code changes. |
 | `AVATAR_OUTPUT_DIR` | No | Where generated images are saved. Default: `~/.agent-avatar/generated/` |
 
 ---
@@ -112,16 +164,16 @@ generate_image
 
 ## 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 |
+| Tool | Description | When to use |
+| --- | --- | --- |
+| `generate_image` | Generates a scene photo of the agent maintaining full visual consistency | 🔁 **Every generation** — every selfie, every social post, every sponsored content piece. This is the core tool you will call constantly. |
+| `show_dna` | Displays current DNA and reference image status | 🔍 **On demand** — whenever you want to verify what appearance is stored, check which references are registered, or troubleshoot inconsistency in generated images. |
+| `list_references` | Lists all stored reference images and their angles | 🔍 **On demand** — to see which angles (front, side, three_quarter, neutral) are available as visual anchors, and confirm file paths are valid. |
+| `update_dna_field` | Updates a single DNA field without rewriting everything | ✏️ **Rarely** — only when the agent's appearance genuinely changes: a new haircut, different hair color, a style shift, new glasses. Real human changes, not corrections. |
+| `generate_reference` | Generates a reference portrait from DNA for a given angle | ✏️ **Rarely** — after an appearance change (`update_dna_field`), the old reference no longer matches. Regenerate the affected angles to keep the visual anchor in sync with the new DNA. |
+| `set_reference_image` | Registers an existing image file as a reference for a given angle | ✏️ **Rarely** — when a photo already exists (e.g. from a previous session or an external shoot) and you want to use it as the reference instead of generating a new one. |
+| `read_identity_files` | Reads soul.md / persona files to extract physical appearance details | 🛠️ **Setup only** — run once when first building the agent's visual identity, to extract appearance data from existing persona documents before calling `save_dna`. |
+| `save_dna` | Saves the agent's visual DNA (human appearance only — never robotic) | 🛠️ **Setup only** — run once to establish identity. Run again only if the agent undergoes a complete appearance overhaul that makes the previous DNA obsolete. |
 
 ---
 
@@ -140,21 +192,20 @@ generate_image
 
 ```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",
+  "agent_name": "MyAgent",
+  "face": "oval face, defined jaw, straight nose, full lips, no marks",
+  "eyes": "dark brown, almond-shaped, bright expression",
+  "hair": "short curly, black, natural texture",
+  "skin": "warm medium brown",
+  "body": "approx. 175cm, slim build, ~25 years old appearance",
+  "default_style": "casual streetwear, plain t-shirt, dark jeans, white sneakers",
   "immutable_traits": [
-    "electric blue spiky hair (#0066FF)",
-    "thin transparent glasses",
-    "medium brown skin",
+    "black curly hair",
+    "warm medium brown skin",
     "dark brown eyes",
-    "casual tech style"
+    "casual streetwear style"
   ],
-  "personality_note": "analytical but approachable, subtle confident smile"
+  "personality_note": "friendly and curious, natural relaxed expression"
 }
 ```
 

package/dist/generate.js

@@ -4,7 +4,7 @@ import { join } from "path";
 import { homedir } from "os";
 const OUTPUT_DIR = process.env.AVATAR_OUTPUT_DIR ??
     join(homedir(), ".agent-avatar", "generated");
-const MODEL = "gemini-3-pro-image-preview";
+const MODEL = process.env.GEMINI_IMAGE_MODEL ?? "gemini-3.1-flash-image-preview";
 export function ensureOutputDir() {
     if (!existsSync(OUTPUT_DIR))
         mkdirSync(OUTPUT_DIR, { recursive: true });
@@ -84,8 +84,8 @@ export async function generateImage(prompt, outputFilename, referenceImages = []
         model: MODEL,
         contents: [{ role: "user", parts }],
         config: {
-            responseModalities: ["IMAGE"],
-            imageConfig: { imageSize: "1K" },
+            responseModalities: ["TEXT", "IMAGE"],
+            imageConfig: { imageSize: "2K" },
         },
     });
     const responseParts = response.candidates?.[0]?.content?.parts ?? [];

package/dist/index.js

@@ -9,6 +9,32 @@ import { buildConsistencyPrompt, generateImage, makeFilename, } from "./generate
 // ─── Server setup ─────────────────────────────────────────────────────────────
 const server = new Server({ name: "agent-avatar-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
 // ─── Helpers ──────────────────────────────────────────────────────────────────
+// mcporter CLI passes tool args as a positional "(key: 'val', key2: 'val2')"
+// string. Because it splits on the first ":" only, the MCP server receives
+// { "(key": "'val', key2: 'val2')" } instead of { key: "val", key2: "val2" }.
+// This function detects that shape and re-parses it into a normal args object.
+function normalizeMcporterArgs(args) {
+    const keys = Object.keys(args);
+    if (keys.length !== 1 || !keys[0].startsWith("("))
+        return args;
+    // Reconstruct the full DSL string, e.g. "(scene: 'valor', angle: 'front')"
+    const fullStr = keys[0] + ": " + String(args[keys[0]]);
+    const content = fullStr.replace(/^\(/, "").replace(/\)$/, "");
+    const result = {};
+    // Match key: 'value' — single-quoted, handles commas and colons inside quotes
+    const quotedRe = /(\w+):\s*'((?:[^'\\]|\\.)*)'/g;
+    let m;
+    while ((m = quotedRe.exec(content)) !== null) {
+        result[m[1]] = m[2];
+    }
+    // Match key: value — unquoted (enums, simple strings)
+    const unquotedRe = /(\w+):\s*([^',)\s][^',)]*?)(?:\s*,|\s*$)/g;
+    while ((m = unquotedRe.exec(content)) !== null) {
+        if (!(m[1] in result))
+            result[m[1]] = m[2].trim();
+    }
+    return Object.keys(result).length > 0 ? result : args;
+}
 function requireConfig(agentName) {
     const name = agentName ?? getActiveAgentName();
     if (!name)
@@ -191,7 +217,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 }));
 // ─── Tool handlers ────────────────────────────────────────────────────────────
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args = {} } = request.params;
+    const { name, arguments: rawArgs = {} } = request.params;
+    const args = normalizeMcporterArgs(rawArgs);
     try {
         switch (name) {
             // ── read_identity_files ────────────────────────────────────────────────
@@ -360,6 +387,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             // ── generate_image ─────────────────────────────────────────────────────
             case "generate_image": {
+                if (!args.scene || typeof args.scene !== "string") {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: [
+                                    `❌ Missing required argument: "scene".`,
+                                    ``,
+                                    `Provide a natural language description of the scene as a JSON string.`,
+                                    ``,
+                                    `Example:`,
+                                    `  { "scene": "selfie at a São Paulo coworking space, afternoon light" }`,
+                                ].join("\n"),
+                            }],
+                        isError: true,
+                    };
+                }
                 const config = requireConfig(args.agent_name);
                 const scene = args.scene;
                 const anglePreference = args.use_reference_angle ?? "best";
@@ -412,6 +455,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             // ── generate_reference ─────────────────────────────────────────────────
             case "generate_reference": {
+                const validAngles = ["front", "side", "three_quarter", "neutral"];
+                if (!args.angle || !validAngles.includes(args.angle)) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: [
+                                    `❌ Missing or invalid argument: "angle".`,
+                                    ``,
+                                    `Valid values: "front", "side", "three_quarter", "neutral"`,
+                                    ``,
+                                    `Example:`,
+                                    `  { "angle": "front" }`,
+                                ].join("\n"),
+                            }],
+                        isError: true,
+                    };
+                }
                 const config = requireConfig(args.agent_name);
                 const angle = args.angle;
                 const angleDescriptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-avatar-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "MCP Server — visual identity and self-portrait generation for AI agents",
   "type": "module",
   "bin": {