🧑‍🎨 usuarios · Synthetic User Profiles for Service Design

Create research-backed user profiles that validate your designs across every sprint.

usuarios is an MCP server that turns your service design research (interviews, observations, field notes) into synthetic user profiles — rich, 12-dimension archetypes you can use to validate designs, align teams, and test ideas. All through natural conversation in Claude Desktop or Codex Desktop.

---

🚀 What your team says vs. what happens

| They say | The AI does | |---|---| | "Creá usuarios sintéticos de las entrevistas" | Analyzes your research, extracts patterns, generates full profiles | | "Validá el onboarding contra María" | Tests your design against María's criteria, returns a report | | "¿Cómo va el proyecto?" | Shows a dashboard with research → patterns → profiles → validations | | "Refiná el perfil de Juan" | Updates the profile with new insights, versions it |

Zero technical knowledge needed. Your team just chats.

---

📦 Installation (2 minutes)

1. Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Configure your AI desktop app

Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "usuarios": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Sebtiago/usuarios-mcp",
        "usuarios-mcp"
      ]
    }
  }
}

Codex Desktop: Edit ~/.codex/config.toml:

[mcp_servers.usuarios]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/Sebtiago/usuarios-mcp",
  "usuarios-mcp"
]

3. Restart your app and start chatting

"Inicializá usuarios para este proyecto"

That's it. The server handles everything else.

---

🧬 What's inside a profile? (12 dimensions)

Based on This Is Service Design Doing, Mapping Experiences, and the Touchpoint Journal:

| Dimension | What it captures | |---|---| | 1. Identity | Name, archetype, real quotes from research | | 2. Empathy Map | Sees, hears, thinks/feels, says/does | | 3. Jobs-to-be-Done | When/I want/So I can (functional, emotional, social) | | 4. Pain Points | Intensity, frequency, context, traceability | | 5. Behaviors | Patterns, triggers, workarounds | | 6. Mindset | Beliefs, tech literacy, change attitude | | 7. Ecosystem | Current tools, key people in their network | | 8. Scenarios | Real usage flows with emotional arcs | | 9. Emotional Journey | Stage-by-stage emotion map | | 10. Validation Criteria | Intent principles + testable questions | | 11. Traceability | Direct/Inferred/Speculative %, all sources cited | | 12. Metadata | Version, expiration (12 months), human validation |

Every profile is saved in both JSON (machine-readable) and Markdown (team-readable).

---

🔄 The flow

INVESTIGACIÓN → ANÁLISIS → PERFILES → VALIDACIÓN → EVOLUCIÓN
 (research/)   (patterns/) (profiles/) (validations/)  (versioned)

The AI host orchestrates everything automatically. You never touch the tools directly.

---

📂 Project structure

After initialization, your project looks like this:

your-project/
└── .usuarios/
    ├── config.yaml          # Project settings
    ├── research/            # Drop your interview files here (.md, .txt)
    │   ├── entrevista-1.md
    │   └── focus-group.md
    ├── patterns/            # Extracted patterns (auto-generated)
    │   ├── patterns.json
    │   └── patterns.md
    ├── profiles/            # Your synthetic users (auto-generated)
    │   ├── maria-cuidadora.json
    │   └── maria-cuidadora.md
    └── validations/         # Design validation reports
        └── 2026-06-22-onboarding.md

---

🛠️ Development

# Clone
git clone https://github.com/Sebtiago/usuarios-mcp.git
cd usuarios-mcp

# Install dependencies
uv sync

# Run locally
uv run python main.py

# Customize templates (optional)
# Create .usuarios/templates/analyze.md in your project
# to override the default analysis methodology

---

🔒 Privacy

• Runs locally. No cloud, no API keys, no data leaves your machine.
• Does not call LLM APIs. The AI host (Claude/GPT) processes everything with its existing model.
• Your research data stays in .usuarios/ in your project folder.

---

📚 Methodology

This tool implements the service design methodology from:

• This Is Service Design Doing — Stickdorn, Hormess, et al.
• Good Services — Louise Downe
• Mapping Experiences — Jim Kalbach
• Touchpoint: The Journal of Service Design
• Analysis-Synthesis Bridge Model for AI in design

---

📄 License

MIT © Santiago Sirias

---

Built for designers, by a designer. If this helps your team, ⭐ the repo.