Initialize a new usuarios project.

Creates the .usuarios/ directory structure: .usuarios/ config.yaml research/ <- Put interview files here patterns/ <- Analysis results go here profiles/ <- Generated profiles (JSON + MD) validations/ <- Validation reports

Args: project_path: Absolute path to the project directory.

List all research files in the project.

Args: project_path: Absolute path to the project directory.

Generate an analysis prompt from research data.

Reads all research files (or specified subset) and returns a prompt that you (the AI host) should process with your LLM to extract:

• Behavioral patterns

• Pain points

• Goals and motivations

• Environment/context factors

• Key differentiators between user segments

After processing, call save_patterns with the structured result.

Args: project_path: Absolute path to the project directory. source_files: Optional list of specific file names to analyze.

Save extracted research patterns to the project.

Accepts the patterns as a JSON string. The patterns should follow the structure provided by the get_research_prompt output.

Args: project_path: Absolute path to the project directory. patterns: JSON string with the analysis results.

Generate a prompt for creating synthetic user profiles.

Reads the patterns file and returns a prompt with the complete 12-dimension profile schema for you to generate rich synthetic user profiles.

Args: project_path: Absolute path to the project directory. count: Optional number of profiles to generate (default: auto-detect from patterns).

Save a generated synthetic user profile.

Saves both a JSON file (for machine consumption) and a Markdown file (for human consumption). The profile must follow the 12-dimension schema provided by get_generate_prompt.

Args: project_path: Absolute path to the project directory. profile: JSON string with the 12-dimension profile.

List all synthetic user profiles in the project.

Args: project_path: Absolute path to the project directory.

Get a specific profile by ID.

Args: project_path: Absolute path to the project directory. profile_id: The profile identifier (e.g. "maria-cuidadora"). format: Output format: "json" (structured) or "markdown" (human-readable).

Generate a validation prompt for testing a design against a profile.

Reads the specified profile and design document, then returns a prompt for you to evaluate the design against the user's criteria and needs.

Args: project_path: Absolute path to the project directory. profile_id: The profile to validate against (e.g. "maria-cuidadora"). design_file: Path to the design document to validate (relative to project).

Save a validation report.

Args: project_path: Absolute path to the project directory. profile_id: The profile that was validated against. report: JSON string with the validation report.

List all validation reports in the project.

Args: project_path: Absolute path to the project directory.

Get the current project configuration.

Args: project_path: Absolute path to the project directory.

Get a dashboard overview of the entire project.

Shows research files count, patterns status, profiles created, validations run, and project health. Call this FIRST in any workflow to understand the current state.

Args: project_path: Absolute path to the project directory.

Get the complete workflow guide for using usuarios-mcp.

Returns detailed instructions on how to use the server effectively: autonomous workflows, methodology, and UX principles.

Call this when you need a refresher on the correct workflow.