Usuarios

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.