Added AI-powered persona generator that creates 1-5 custom personas with UUIDs based on natural language descriptions, which can then be used across all storytelling tools to generate multiple stories simultaneously.

README.md

@@ -40,9 +40,63 @@ Designed to help product teams feel their users, not just document them.
 
 ## 🛠️ 2. MCP-Compatible Tools
 
-Each tool is exposed through the MCP server (`src/index.ts`) and powered by Claude via the `@anthropic-sdk/sdk`. Schemas are enforced through Anthropic’s JSON mode so outputs are always valid.
+Each tool is exposed through the MCP server (`src/index.ts`) and powered by Claude via the `@anthropic-sdk/sdk`. Schemas are enforced through Anthropic's JSON mode so outputs are always valid.
 
-### 1. `user_story`
+### 1. `list_personas`
+Lists all available personas with their key attributes.
+
+**Input**
+```json
+{
+  "limit": "number (optional)"
+}
+```
+
+**Output**
+```json
+{
+  "personas": [
+    {
+      "id": "string",
+      "name": "string",
+      "age": "number",
+      "location": "string",
+      "job_title": "string",
+      "industry": "string",
+      "tech_literacy": "string",
+      "primary_goals": ["string"],
+      "pain_points": ["string"],
+      "user_story": "string"
+    }
+  ],
+  "total": "number"
+}
+```
+
+### 2. `search_personas`
+Search and filter personas by various criteria.
+
+**Input**
+```json
+{
+  "role": "string (optional)",
+  "industry": "string (optional)",
+  "age_range": "string (optional, e.g., '25-35')",
+  "tech_literacy": "string (optional)",
+  "location": "string (optional)"
+}
+```
+
+**Output**
+```json
+{
+  "personas": ["array of matching personas"],
+  "count": "number",
+  "filters": "object with applied filters"
+}
+```
+
+### 3. `user_story`
 Generates a structured narrative user story + acceptance criteria from a product and persona.
 
 **Input**
@@ -63,7 +117,7 @@ Generates a structured narrative user story + acceptance criteria from a product
 }
 ```
 
-### 2. `customer_experience_tale`
+### 4. `customer_experience_tale`
 Creates a short narrative describing a persona experiencing a specific problem.
 
 **Input**
@@ -85,7 +139,7 @@ Creates a short narrative describing a persona experiencing a specific problem.
 }
 ```
 
-### 3. `feature_impact_story`
+### 5. `feature_impact_story`
 Shows the before and after of a persona interacting with a feature.
 
 **Input**
@@ -107,7 +161,7 @@ Shows the before and after of a persona interacting with a feature.
 }
 ```
 
-### 4. `journey_map_story`
+### 6. `journey_map_story`
 Generates a narrative for a specific stage of the user journey.
 
 **Input**
@@ -134,20 +188,31 @@ Generates a narrative for a specific stage of the user journey.
 
 ---
 
-## 🧬 3. Persona Data (`data/personas.json`)
+## 📦 3. MCP Resources
 
-```json
-[
-  {
-    "id": "busy_parent",
-    "name": "Busy Parent",
-    "role": "Working parent of two kids",
-    "goals": ["Save time", "Reduce mental load", "Keep kids on schedule"],
-    "frustrations": ["Too many apps", "Slow support", "Juggling work and home"],
-    "tech_comfort": "medium",
-    "quote": "If it's not simple, I don't have time for it."
-  },
-  {
+Personas are also exposed as MCP resources for easy browsing:
+
+- `personas://all` - Complete list of all personas with summaries
+- `personas://[id]` - Individual persona details (e.g., `personas://persona-001`)
+
+Resources allow LLM clients to browse and reference personas without making tool calls.
+
+---
+
+## 🧬 4. Persona Data (`data/personas.json`)
+
+The persona database contains detailed user profiles with:
+- Demographics (age, location, income, education)
+- Job information (title, industry, experience)
+- Technology preferences (literacy level, devices, apps)
+- Goals and motivations
+- Pain points and frustrations
+- Purchasing habits and interests
+- Personality traits and communication style
+
+Example personas include marketing managers, developers, healthcare directors, customer support specialists, and more across various industries and demographics.
+
+---
     "id": "ops_engineer",
     "name": "Ops Engineer",
     "role": "On-call site reliability engineer",

app.py

@@ -72,16 +72,54 @@ User Story: {p.get("user_story", "")}"""
     return "Persona: Default user"
 
 
+def format_persona_from_json(persona_obj: dict) -> str:
+    """Format a persona object (from generated personas) into context string."""
+    job_title = persona_obj.get("job", {}).get("title", "Unknown")
+    industry = persona_obj.get("job", {}).get("industry", "Unknown")
+    age = persona_obj.get("age", "Unknown")
+    location_city = persona_obj.get("location", {}).get("city", "Unknown")
+    goals = persona_obj.get("goals", {}).get("primary_goals", [])
+    pain_points = persona_obj.get("pain_points", [])
+    motivations = persona_obj.get("motivations", [])
+    
+    return f"""Persona: {persona_obj.get("name", "Unknown")}
+Age: {age}
+Location: {location_city}
+Title: {job_title}
+Industry: {industry}
+Background: {persona_obj.get("background", "")}
+Goals: {', '.join(goals) if goals else "N/A"}
+Pain Points: {', '.join(pain_points) if pain_points else "N/A"}
+Motivations: {', '.join(motivations) if motivations else "N/A"}
+User Story: {persona_obj.get("user_story", "")}"""
+
+
 def build_persona_profile(persona_name: str, persona_override: str):
-    """Return the persona label for display and the context payload."""
+    """Return the persona label for display and the context payload. Returns (label, contexts_list) where contexts_list is a list of persona contexts."""
+    # Check if persona_override contains JSON (generated persona)
+    if persona_override and persona_override.strip():
+        stripped = persona_override.strip()
+        if stripped.startswith('{') or stripped.startswith('['):
+            try:
+                persona_json = json.loads(stripped)
+                # If it's an array, return all personas
+                if isinstance(persona_json, list) and len(persona_json) > 0:
+                    contexts = [format_persona_from_json(p) for p in persona_json if isinstance(p, dict)]
+                    return f"{len(contexts)} Generated Personas", contexts
+                # If it's a single persona object, use it directly
+                elif isinstance(persona_json, dict) and 'id' in persona_json:
+                    return persona_json.get('name', 'Generated Persona'), [format_persona_from_json(persona_json)]
+            except json.JSONDecodeError:
+                pass  # Fall through to custom persona handling
+    
     if persona_name == CUSTOM_PERSONA_LABEL:
         custom_label = persona_override.strip() or "Custom Persona"
         context = get_persona_context("", custom_label)
-        return custom_label, context
+        return custom_label, [context]
 
     persona_id = persona_options.get(persona_name, "busy_parent")
     context = get_persona_context(persona_id)
-    return persona_name or "Persona", context
+    return persona_name or "Persona", [context]
 
 
 def toggle_custom_persona(selected_value: str):
@@ -114,8 +152,8 @@ def generate_with_claude(system_prompt: str, user_prompt: str) -> str:
         }, indent=2)
 
 def generate_user_story(product: str, persona_name: str, persona_override: str):
-    """Generate a user story for the given product and persona."""
-    _, persona_context = build_persona_profile(persona_name, persona_override)
+    """Generate a user story for the given product and persona(s)."""
+    _, persona_contexts = build_persona_profile(persona_name, persona_override)
     
     system_prompt = """You are an expert UX writer and product strategist. 
 Generate a structured user story in JSON format with the following fields:
@@ -125,23 +163,28 @@ Generate a structured user story in JSON format with the following fields:
 
 Return ONLY valid JSON, no additional text."""
 
-    user_prompt = f"""{persona_context}
+    results = []
+    for idx, persona_context in enumerate(persona_contexts):
+        user_prompt = f"""{persona_context}
 
 Generate a user story for this persona using the product: {product}
 
 Format as JSON with the keys: story, acceptance_criteria (array), risks (array)"""
 
-    response = generate_with_claude(system_prompt, user_prompt)
-    try:
-        # Try to parse and re-format as pretty JSON
-        data = json.loads(response)
-        return json.dumps(data, indent=2)
-    except:
-        return response
+        response = generate_with_claude(system_prompt, user_prompt)
+        try:
+            data = json.loads(response)
+            if len(persona_contexts) > 1:
+                data['persona_index'] = idx + 1
+            results.append(data)
+        except:
+            results.append({"error": "Failed to parse response", "raw": response})
+    
+    return json.dumps(results if len(results) > 1 else results[0], indent=2)
 
 def generate_experience_tale(problem: str, persona_name: str, persona_override: str):
     """Generate a customer experience tale."""
-    _, persona_context = build_persona_profile(persona_name, persona_override)
+    _, persona_contexts = build_persona_profile(persona_name, persona_override)
     
     system_prompt = """You are an expert in customer experience and user research.
 Generate a narrative about a persona experiencing a problem in JSON format with:
@@ -152,22 +195,28 @@ Generate a narrative about a persona experiencing a problem in JSON format with:
 
 Return ONLY valid JSON, no additional text."""
 
-    user_prompt = f"""{persona_context}
+    results = []
+    for idx, persona_context in enumerate(persona_contexts):
+        user_prompt = f"""{persona_context}
 
 Describe how this persona experiences this problem: {problem}
 
 Format as JSON with keys: title, narrative, pain_points (array), opportunities (array)"""
 
-    response = generate_with_claude(system_prompt, user_prompt)
-    try:
-        data = json.loads(response)
-        return json.dumps(data, indent=2)
-    except:
-        return response
+        response = generate_with_claude(system_prompt, user_prompt)
+        try:
+            data = json.loads(response)
+            if len(persona_contexts) > 1:
+                data['persona_index'] = idx + 1
+            results.append(data)
+        except:
+            results.append({"error": "Failed to parse response", "raw": response})
+    
+    return json.dumps(results if len(results) > 1 else results[0], indent=2)
 
 def generate_feature_impact(feature: str, persona_name: str, persona_override: str):
     """Generate a before/after feature impact story."""
-    _, persona_context = build_persona_profile(persona_name, persona_override)
+    _, persona_contexts = build_persona_profile(persona_name, persona_override)
     
     system_prompt = """You are an expert at showing product impact through user narratives.
 Generate a before/after story in JSON format with:
@@ -178,22 +227,28 @@ Generate a before/after story in JSON format with:
 
 Return ONLY valid JSON, no additional text."""
 
-    user_prompt = f"""{persona_context}
+    results = []
+    for idx, persona_context in enumerate(persona_contexts):
+        user_prompt = f"""{persona_context}
 
 Show the before/after impact of this feature on the persona's experience: {feature}
 
 Format as JSON with keys: before_story, after_story, key_benefits (array), success_metrics (array)"""
 
-    response = generate_with_claude(system_prompt, user_prompt)
-    try:
-        data = json.loads(response)
-        return json.dumps(data, indent=2)
-    except:
-        return response
+        response = generate_with_claude(system_prompt, user_prompt)
+        try:
+            data = json.loads(response)
+            if len(persona_contexts) > 1:
+                data['persona_index'] = idx + 1
+            results.append(data)
+        except:
+            results.append({"error": "Failed to parse response", "raw": response})
+    
+    return json.dumps(results if len(results) > 1 else results[0], indent=2)
 
 def generate_journey_story(stage: str, product: str, persona_name: str, persona_override: str):
     """Generate a journey map narrative."""
-    _, persona_context = build_persona_profile(persona_name, persona_override)
+    _, persona_contexts = build_persona_profile(persona_name, persona_override)
     
     system_prompt = """You are an expert in customer journey mapping and experience design.
 Generate a journey stage narrative in JSON format with:
@@ -206,18 +261,218 @@ Generate a journey stage narrative in JSON format with:
 
 Return ONLY valid JSON, no additional text."""
 
-    user_prompt = f"""{persona_context}
+    results = []
+    for idx, persona_context in enumerate(persona_contexts):
+        user_prompt = f"""{persona_context}
 
 Describe this persona's experience at the '{stage}' stage of their journey with {product}.
 
 Format as JSON with keys: stage, narrative, touchpoints (array), emotions (array), breakdowns (array), opportunities (array)"""
 
-    response = generate_with_claude(system_prompt, user_prompt)
+        response = generate_with_claude(system_prompt, user_prompt)
+        try:
+            data = json.loads(response)
+            if len(persona_contexts) > 1:
+                data['persona_index'] = idx + 1
+            results.append(data)
+        except:
+            results.append({"error": "Failed to parse response", "raw": response})
+    
+    return json.dumps(results if len(results) > 1 else results[0], indent=2)
+
+# Persona browser functions
+def search_personas_func(role: str, industry: str, age_range: str, tech_literacy: str, location: str):
+    """Search personas based on filters."""
+    filtered = personas
+    
+    # Apply filters
+    if role and role.strip():
+        filtered = [p for p in filtered if role.lower() in p.get("job", {}).get("title", "").lower()]
+    
+    if industry and industry.strip():
+        filtered = [p for p in filtered if industry.lower() in p.get("job", {}).get("industry", "").lower()]
+    
+    if age_range and age_range.strip():
+        try:
+            min_age, max_age = map(int, age_range.split("-"))
+            filtered = [p for p in filtered if min_age <= p.get("age", 0) <= max_age]
+        except:
+            pass
+    
+    if tech_literacy and tech_literacy.strip():
+        filtered = [p for p in filtered if tech_literacy.lower() in p.get("technology", {}).get("tech_literacy", "").lower()]
+    
+    if location and location.strip():
+        filtered = [p for p in filtered 
+                   if location.lower() in p.get("location", {}).get("city", "").lower() or
+                      location.lower() in p.get("location", {}).get("state", "").lower() or
+                      location.lower() in p.get("location", {}).get("country", "").lower()]
+    
+    # Format results as a table
+    if not filtered:
+        return "No personas found matching the criteria.", ""
+    
+    result_lines = [f"**Found {len(filtered)} persona(s):**\n"]
+    
+    for p in filtered[:20]:  # Limit to 20 results
+        name = p.get("name", "Unknown")
+        age = p.get("age", "?")
+        title = p.get("job", {}).get("title", "Unknown")
+        industry_val = p.get("job", {}).get("industry", "Unknown")
+        city = p.get("location", {}).get("city", "Unknown")
+        tech_lit = p.get("technology", {}).get("tech_literacy", "Unknown")
+        
+        result_lines.append(f"• **{name}** ({age}) - {title} @ {industry_val} | {city} | Tech: {tech_lit}")
+    
+    return "\n".join(result_lines), json.dumps(filtered[0] if filtered else {}, indent=2)
+
+def list_all_personas():
+    """List all personas with summary info."""
+    result_lines = [f"**Total Personas: {len(personas)}**\n"]
+    
+    # Group by industry
+    by_industry = {}
+    for p in personas:
+        industry = p.get("job", {}).get("industry", "Other")
+        if industry not in by_industry:
+            by_industry[industry] = []
+        by_industry[industry].append(p)
+    
+    result_lines.append("**By Industry:**")
+    for industry, persona_list in sorted(by_industry.items()):
+        result_lines.append(f"• {industry}: {len(persona_list)} personas")
+    
+    result_lines.append("\n**All Personas:**")
+    for p in personas[:20]:  # Show first 20
+        name = p.get("name", "Unknown")
+        age = p.get("age", "?")
+        title = p.get("job", {}).get("title", "Unknown")
+        city = p.get("location", {}).get("city", "Unknown")
+        result_lines.append(f"• **{name}** ({age}) - {title} | {city}")
+    
+    if len(personas) > 20:
+        result_lines.append(f"\n_... and {len(personas) - 20} more personas_")
+    
+    return "\n".join(result_lines)
+
+def show_persona_details(persona_index: int):
+    """Show detailed information about a specific persona."""
+    if 0 <= persona_index < len(personas):
+        p = personas[persona_index]
+        return json.dumps(p, indent=2)
+    return "Persona not found"
+
+def generate_personas_func(description: str, count: int):
+    """Generate random personas based on description using Claude AI."""
+    if not description or not description.strip():
+        return json.dumps({"error": "Please provide a description"}, indent=2)
+    
+    if count < 1 or count > 5:
+        return json.dumps({"error": "Count must be between 1 and 5"}, indent=2)
+    
+    if not client:
+        return json.dumps({"error": "Anthropic API key not configured"}, indent=2)
+    
+    system_prompt = """You are a persona generation expert. Generate realistic, diverse user personas based on the provided description.
+
+CRITICAL REQUIREMENTS:
+1. Return ONLY valid JSON - no markdown, no code blocks, no explanations
+2. Return a JSON array of persona objects
+3. Each persona must follow the exact structure provided in the example
+4. Ensure diversity in all randomized fields (location, income, education, tech literacy, devices, etc.)
+5. All personas must match the core description provided by the user
+6. Generate exactly the number of personas requested
+
+PERSONA STRUCTURE (follow this exactly):
+{
+  "id": "UUID (e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890')",
+  "name": "Full Name",
+  "age": number,
+  "gender": "Male/Female/Nonbinary",
+  "location": {
+    "address": "street address",
+    "city": "city",
+    "state": "state/province",
+    "country": "country"
+  },
+  "demographics": {
+    "income": "$XX,000/year",
+    "education_level": "education level",
+    "marital_status": "status",
+    "household_size": number
+  },
+  "job": {
+    "title": "job title",
+    "industry": "industry",
+    "experience_years": number,
+    "employment_type": "Full-time/Part-time/Freelance/etc"
+  },
+  "background": "brief background description",
+  "interests": ["interest1", "interest2", "interest3"],
+  "purchasing_habits": {
+    "online_shopping_frequency": "frequency",
+    "preferred_platforms": ["platform1", "platform2"],
+    "average_spend_per_month": "$XXX",
+    "brand_loyalty_level": "Low/Medium/High/Very High"
+  },
+  "technology": {
+    "tech_literacy": "Low/Medium/High/Very High",
+    "devices_used": ["device1", "device2"],
+    "favorite_apps": ["app1", "app2", "app3"]
+  },
+  "goals": {
+    "primary_goals": ["goal1", "goal2"],
+    "secondary_goals": ["goal1", "goal2"]
+  },
+  "pain_points": ["pain1", "pain2"],
+  "motivations": ["motivation1", "motivation2"],
+  "personality": {
+    "traits": ["trait1", "trait2"],
+    "communication_style": "style description"
+  },
+  "user_story": "As a [role], I want [goal] so [benefit].",
+  "acceptance_criteria": ["criteria1", "criteria2"]
+}"""
+    
+    user_prompt = f"""Generate {count} diverse user persona{'s' if count > 1 else ''} that match this description:
+
+"{description}"
+
+Requirements:
+- Generate exactly {count} persona{'s' if count > 1 else ''}
+- Each persona MUST match the core description: "{description}"
+- Randomize other attributes for diversity (locations worldwide, various incomes, different tech literacy levels, diverse jobs/industries, etc.)
+- Ensure realistic consistency within each persona
+- Use diverse names from various cultures
+- Return ONLY the JSON array, no other text
+
+Return format: [persona1, persona2, ...]"""
+    
     try:
-        data = json.loads(response)
-        return json.dumps(data, indent=2)
-    except:
-        return response
+        response = client.messages.create(
+            model=model,
+            max_tokens=4096,
+            messages=[{"role": "user", "content": f"{system_prompt}\n\n{user_prompt}"}]
+        )
+        
+        response_text = response.content[0].text if response.content else ""
+        
+        # Clean up response (remove markdown code blocks if present)
+        cleaned_response = response_text.strip()
+        if cleaned_response.startswith("```json"):
+            cleaned_response = cleaned_response.replace("```json", "").replace("```", "").strip()
+        elif cleaned_response.startswith("```"):
+            cleaned_response = cleaned_response.replace("```", "").strip()
+        
+        # Validate JSON
+        personas_data = json.loads(cleaned_response)
+        if not isinstance(personas_data, list):
+            return json.dumps({"error": "Response is not an array"}, indent=2)
+        
+        return json.dumps(personas_data, indent=2)
+    
+    except Exception as e:
+        return json.dumps({"error": f"Failed to generate personas: {str(e)}"}, indent=2)
 
 # Build the Gradio interface
 with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
@@ -230,7 +485,88 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
     """)
     
     with gr.Tabs():
-        # Tab 1: User Story
+        # Tab 0: Persona Browser (NEW!)
+        with gr.Tab("🔍 Persona Browser"):
+            gr.Markdown("""
+            ### Discover & Search Personas
+            **New Feature:** Browse all 30 personas and filter by multiple criteria
+            """)
+            
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("#### Filters")
+                    role_filter = gr.Textbox(label="Role/Job Title", placeholder="e.g., manager, developer, director")
+                    industry_filter = gr.Textbox(label="Industry", placeholder="e.g., healthcare, tech, e-commerce")
+                    age_filter = gr.Textbox(label="Age Range", placeholder="e.g., 25-35, 40-50")
+                    tech_filter = gr.Textbox(label="Tech Literacy", placeholder="e.g., high, moderate, low")
+                    location_filter = gr.Textbox(label="Location", placeholder="e.g., San Diego, Toronto, USA")
+                    
+                    search_btn = gr.Button("🔍 Search Personas", variant="primary")
+                    list_all_btn = gr.Button("📋 List All Personas")
+                    
+                with gr.Column(scale=2):
+                    gr.Markdown("#### Search Results")
+                    search_results = gr.Markdown(value="Click 'List All Personas' to see all available personas.")
+                    
+                    gr.Markdown("#### Persona Details (JSON)")
+                    persona_details = gr.Textbox(label="Full Persona Data", lines=20, interactive=False)
+            
+            search_btn.click(
+                search_personas_func,
+                inputs=[role_filter, industry_filter, age_filter, tech_filter, location_filter],
+                outputs=[search_results, persona_details]
+            )
+            
+            list_all_btn.click(
+                list_all_personas,
+                outputs=search_results
+            )
+        
+        # Tab 1: Generate Personas (NEW!)
+        with gr.Tab("✨ Generate Personas"):
+            gr.Markdown("""
+            ### AI-Powered Persona Generator
+            **New Feature:** Generate random, realistic personas based on any description
+            
+            Examples:
+            - "people who love to cook but never have time to in their 20-30s"
+            - "sandwich enthusiasts who are 50+ years old"
+            - "tech-savvy students interested in sustainable fashion"
+            """)
+            
+            with gr.Row():
+                with gr.Column(scale=2):
+                    persona_description = gr.Textbox(
+                        label="Persona Description",
+                        placeholder="e.g., people who love to cook but never have time to in their 20-30s",
+                        lines=3
+                    )
+                with gr.Column(scale=1):
+                    persona_count = gr.Slider(
+                        label="Number of Personas",
+                        minimum=1,
+                        maximum=5,
+                        value=3,
+                        step=1
+                    )
+            
+            generate_personas_btn = gr.Button("✨ Generate Personas", variant="primary", size="lg")
+            
+            gr.Markdown("#### Generated Personas (JSON)")
+            generated_personas_output = gr.Textbox(
+                label="Personas",
+                lines=25,
+                interactive=False,
+                placeholder="Generated personas will appear here..."
+            )
+            
+            generate_personas_btn.click(
+                generate_personas_func,
+                inputs=[persona_description, persona_count],
+                outputs=generated_personas_output
+            )
+        
+        # Tab 2: User Story
         with gr.Tab("User Story"):
             gr.Markdown("### Generate Structured User Stories")
             with gr.Row():
@@ -242,8 +578,9 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                     value=default_persona_choice,
                 )
                 persona_custom = gr.Textbox(
-                    label="Or Custom Persona",
-                    placeholder="Describe your custom persona",
+                    label="Or Custom Persona / Generated Persona JSON",
+                    placeholder="Paste generated persona JSON here or describe your custom persona",
+                    lines=3,
                     visible=False,
                 )
                 persona_name.change(
@@ -259,7 +596,7 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                 outputs=user_story_output
             )
         
-        # Tab 2: Experience Tale
+        # Tab 3: Experience Tale
         with gr.Tab("Experience Tale"):
             gr.Markdown("### Generate Customer Experience Narratives")
             with gr.Row():
@@ -271,8 +608,9 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                     value=default_persona_choice,
                 )
                 persona_custom_2 = gr.Textbox(
-                    label="Or Custom Persona",
-                    placeholder="Describe your custom persona",
+                    label="Or Custom Persona / Generated Persona JSON",
+                    placeholder="Paste generated persona JSON here or describe your custom persona",
+                    lines=3,
                     visible=False,
                 )
                 persona_name_2.change(
@@ -290,7 +628,7 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                 outputs=tale_output
             )
         
-        # Tab 3: Feature Impact
+        # Tab 4: Feature Impact
         with gr.Tab("Feature Impact"):
             gr.Markdown("### Generate Before/After Feature Impact Stories")
             with gr.Row():
@@ -302,8 +640,9 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                     value=default_persona_choice,
                 )
                 persona_custom_3 = gr.Textbox(
-                    label="Or Custom Persona",
-                    placeholder="Describe your custom persona",
+                    label="Or Custom Persona / Generated Persona JSON",
+                    placeholder="Paste generated persona JSON here or describe your custom persona",
+                    lines=3,
                     visible=False,
                 )
                 persona_name_3.change(
@@ -321,7 +660,7 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                 outputs=impact_output
             )
         
-        # Tab 4: Journey Map
+        # Tab 5: Journey Map
         with gr.Tab("Journey Map"):
             gr.Markdown("### Generate Journey Map Narratives")
             with gr.Row():
@@ -334,8 +673,9 @@ with gr.Blocks(title="HealixPath - AI Persona Storytelling") as demo:
                     value=default_persona_choice,
                 )
                 persona_custom_4 = gr.Textbox(
-                    label="Or Custom Persona",
-                    placeholder="Describe your custom persona",
+                    label="Or Custom Persona / Generated Persona JSON",
+                    placeholder="Paste generated persona JSON here or describe your custom persona",
+                    lines=3,
                     visible=False,
                 )
                 persona_name_4.change(

src/index.ts

@@ -2,6 +2,8 @@ import "dotenv/config";
 import {
   loadPersonas,
   getPersona,
+  formatPersonaSummary,
+  searchPersonas,
   type Persona,
 } from "./utils/persona_loader.js";
 import { generateUserStory, type UserStoryInput } from "./tools/user_story.js";
@@ -17,6 +19,7 @@ import {
   generateJourneyMapStory,
   type JourneyMapStoryInput,
 } from "./tools/journey_map_story.js";
+import { generatePersonas } from "./tools/generate_personas.js";
 
 interface ToolSchema {
   name: string;
@@ -28,6 +31,13 @@ interface ToolSchema {
   };
 }
 
+interface ResourceSchema {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
 class HealixPathServer {
   private personas: Map<string, Persona>;
 
@@ -37,6 +47,52 @@ class HealixPathServer {
 
   getTools(): ToolSchema[] {
     return [
+      {
+        name: "list_personas",
+        description:
+          "List all available personas with their key attributes (id, name, age, location, job title, industry, tech literacy, goals, pain points)",
+        input_schema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Optional: Maximum number of personas to return (default: all)",
+            },
+          },
+          required: [],
+        },
+      },
+      {
+        name: "search_personas",
+        description:
+          "Search and filter personas by role/job title, industry, age range, tech literacy, or location",
+        input_schema: {
+          type: "object",
+          properties: {
+            role: {
+              type: "string",
+              description: "Filter by job title or role (partial match, case-insensitive)",
+            },
+            industry: {
+              type: "string",
+              description: "Filter by industry (partial match, case-insensitive)",
+            },
+            age_range: {
+              type: "string",
+              description: "Filter by age range (format: 'min-max', e.g., '25-35')",
+            },
+            tech_literacy: {
+              type: "string",
+              description: "Filter by tech literacy level (e.g., 'high', 'moderate', 'low')",
+            },
+            location: {
+              type: "string",
+              description: "Filter by location - city, state, or country (partial match)",
+            },
+          },
+          required: [],
+        },
+      },
       {
         name: "user_story",
         description:
@@ -51,7 +107,7 @@ class HealixPathServer {
             persona_id: {
               type: "string",
               description:
-                "ID of the persona to use (busy_parent, ops_engineer, product_manager)",
+                "ID of the persona to use (use list_personas to see available IDs)",
             },
             persona_override: {
               type: "string",
@@ -139,13 +195,106 @@ class HealixPathServer {
           required: ["stage", "product"],
         },
       },
+      {
+        name: "generate_personas",
+        description:
+          "Generate random user personas based on a natural language description. Creates realistic, diverse personas matching the specified criteria with randomized attributes for variety.",
+        input_schema: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description:
+                "Natural language description of the personas to generate (e.g., 'people who love to cook but never have time to in their 20-30s', 'sandwich enthusiasts who are 50+ years old')",
+            },
+            count: {
+              type: "number",
+              description:
+                "Number of personas to generate (minimum: 1, maximum: 5, default: 1)",
+            },
+          },
+          required: ["description", "count"],
+        },
+      },
     ];
   }
 
+  getResources(): ResourceSchema[] {
+    const resources: ResourceSchema[] = [
+      {
+        uri: "personas://all",
+        name: "All Personas",
+        description: "Complete list of all available personas with their full details",
+        mimeType: "application/json",
+      },
+    ];
+
+    // Add individual persona resources
+    for (const [id, persona] of this.personas.entries()) {
+      resources.push({
+        uri: `personas://${id}`,
+        name: `${persona.name} - ${persona.job?.title || persona.role || "User"}`,
+        description: `Detailed information about ${persona.name}`,
+        mimeType: "application/json",
+      });
+    }
+
+    return resources;
+  }
+
+  async readResource(uri: string): Promise<string> {
+    if (uri === "personas://all") {
+      const allPersonas = Array.from(this.personas.values()).map(formatPersonaSummary);
+      return JSON.stringify(allPersonas, null, 2);
+    }
+
+    // Handle individual persona URIs
+    if (uri.startsWith("personas://")) {
+      const personaId = uri.replace("personas://", "");
+      const persona = this.personas.get(personaId);
+      
+      if (!persona) {
+        return JSON.stringify({ error: `Persona not found: ${personaId}` });
+      }
+
+      return JSON.stringify(persona, null, 2);
+    }
+
+    return JSON.stringify({ error: `Unknown resource URI: ${uri}` });
+  }
+
   async processTool(
     toolName: string,
     toolInput: Record<string, unknown>
   ): Promise<string> {
+    // Handle list_personas tool
+    if (toolName === "list_personas") {
+      const limit = typeof toolInput.limit === "number" ? toolInput.limit : undefined;
+      const allPersonas = Array.from(this.personas.values()).map(formatPersonaSummary);
+      const personas = limit ? allPersonas.slice(0, limit) : allPersonas;
+      return JSON.stringify({ personas, total: this.personas.size }, null, 2);
+    }
+
+    // Handle search_personas tool
+    if (toolName === "search_personas") {
+      const filters = {
+        role: typeof toolInput.role === "string" ? toolInput.role : undefined,
+        industry: typeof toolInput.industry === "string" ? toolInput.industry : undefined,
+        age_range: typeof toolInput.age_range === "string" ? toolInput.age_range : undefined,
+        tech_literacy: typeof toolInput.tech_literacy === "string" ? toolInput.tech_literacy : undefined,
+        location: typeof toolInput.location === "string" ? toolInput.location : undefined,
+      };
+
+      const results = searchPersonas(this.personas, filters);
+      const summaries = results.map(formatPersonaSummary);
+      
+      return JSON.stringify({ 
+        personas: summaries, 
+        count: summaries.length,
+        filters: Object.fromEntries(Object.entries(filters).filter(([_, v]) => v !== undefined))
+      }, null, 2);
+    }
+
     let persona: Persona | undefined;
 
     // Load persona if specified
@@ -185,6 +334,18 @@ class HealixPathServer {
           return JSON.stringify(journeyStory);
         }
 
+        case "generate_personas": {
+          const description = typeof toolInput.description === "string" ? toolInput.description : "";
+          const count = typeof toolInput.count === "number" ? toolInput.count : 1;
+          
+          if (!description) {
+            return JSON.stringify({ error: "Description is required" });
+          }
+          
+          const personas = await generatePersonas({ description, count });
+          return personas; // Already JSON stringified
+        }
+
         default:
           return JSON.stringify({ error: `Unknown tool: ${toolName}` });
       }
@@ -208,28 +369,46 @@ async function main(): Promise<void> {
     console.log(`  ${tool.description}`);
   });
 
-  console.log("\n\nAvailable Personas:");
-  console.log(
-    "- busy_parent: Working parent juggling multiple responsibilities"
-  );
-  console.log("- ops_engineer: On-call SRE managing infrastructure");
-  console.log("- product_manager: PM at a healthcare startup");
+  console.log("\n\nAvailable Resources:");
+  server.getResources().slice(0, 5).forEach((resource) => {
+    console.log(`\n- ${resource.uri}`);
+    console.log(`  ${resource.description}`);
+  });
+  console.log(`\n... and ${server.getResources().length - 5} more persona resources`);
 
   console.log("\n\n📝 Example Tool Calls:");
   console.log("---");
 
+  // Example 0: List Personas
+  const listResult = await server.processTool("list_personas", { limit: 3 });
+  console.log("\n0. List Personas (first 3):");
+  console.log(listResult);
+
+  // Example 0b: Search Personas
+  const searchResult = await server.processTool("search_personas", {
+    industry: "healthcare",
+    tech_literacy: "moderate"
+  });
+  console.log("\n0b. Search Personas (Healthcare + Moderate Tech):");
+  console.log(searchResult);
+
+  // Example 0c: Read Resource
+  const resourceResult = await server.readResource("personas://all");
+  console.log("\n0c. Read Resource (all personas summary - truncated):");
+  console.log(resourceResult.substring(0, 500) + "...");
+
   // Example 1: User Story
   const userStoryResult = await server.processTool("user_story", {
     product: "Healthcare appointment scheduling app",
-    persona_id: "busy_parent",
+    persona_id: "persona-001",
   });
-  console.log("\n1. User Story for Busy Parent:");
+  console.log("\n1. User Story:");
   console.log(userStoryResult);
 
   // Example 2: Customer Experience Tale
   const taleResult = await server.processTool("customer_experience_tale", {
     problem: "Mobile app crashes during checkout",
-    persona_id: "busy_parent",
+    persona_id: "persona-001",
   });
   console.log("\n2. Customer Experience Tale:");
   console.log(taleResult);
@@ -237,7 +416,7 @@ async function main(): Promise<void> {
   // Example 3: Feature Impact Story
   const impactResult = await server.processTool("feature_impact_story", {
     feature_description: "One-click scheduling with automatic reminders",
-    persona_id: "busy_parent",
+    persona_id: "persona-001",
   });
   console.log("\n3. Feature Impact Story:");
   console.log(impactResult);
@@ -246,11 +425,19 @@ async function main(): Promise<void> {
   const journeyResult = await server.processTool("journey_map_story", {
     stage: "adoption",
     product: "Healthcare platform",
-    persona_id: "ops_engineer",
+    persona_id: "persona-003",
   });
   console.log("\n4. Journey Map Story:");
   console.log(journeyResult);
 
+  // Example 5: Generate Personas
+  const generateResult = await server.processTool("generate_personas", {
+    description: "people who love to cook but never have time to in their 20-30s",
+    count: 2,
+  });
+  console.log("\n5. Generate Personas (cooking enthusiasts, 20-30s, time-constrained):");
+  console.log(generateResult);
+
   console.log("\n\n✅ HealixPath Server is ready to serve MCP clients!");
 }
 

src/tools/generate_personas.ts

@@ -0,0 +1,144 @@
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+interface GeneratePersonasParams {
+  description: string;
+  count: number;
+}
+
+export async function generatePersonas(params: GeneratePersonasParams): Promise<string> {
+  const { description, count } = params;
+
+  // Validate count
+  if (count < 1 || count > 5) {
+    return "Error: Count must be between 1 and 5 personas.";
+  }
+
+  const systemPrompt = `You are a persona generation expert. Generate realistic, diverse user personas based on the provided description.
+
+CRITICAL REQUIREMENTS:
+1. Return ONLY valid JSON - no markdown, no code blocks, no explanations
+2. Return a JSON array of persona objects
+3. Each persona must follow the exact structure provided in the example
+4. Ensure diversity in all randomized fields (location, income, education, tech literacy, devices, etc.)
+5. All personas must match the core description provided by the user
+6. Generate exactly the number of personas requested
+
+PERSONA STRUCTURE (follow this exactly):
+{
+  "id": "UUID (e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890')",
+  "name": "Full Name",
+  "age": number,
+  "gender": "Male/Female/Nonbinary",
+  "location": {
+    "address": "street address",
+    "city": "city",
+    "state": "state/province",
+    "country": "country"
+  },
+  "demographics": {
+    "income": "$XX,000/year",
+    "education_level": "education level",
+    "marital_status": "status",
+    "household_size": number
+  },
+  "job": {
+    "title": "job title",
+    "industry": "industry",
+    "experience_years": number,
+    "employment_type": "Full-time/Part-time/Freelance/etc"
+  },
+  "background": "brief background description",
+  "interests": ["interest1", "interest2", "interest3"],
+  "purchasing_habits": {
+    "online_shopping_frequency": "frequency",
+    "preferred_platforms": ["platform1", "platform2"],
+    "average_spend_per_month": "$XXX",
+    "brand_loyalty_level": "Low/Medium/High/Very High"
+  },
+  "technology": {
+    "tech_literacy": "Low/Medium/High/Very High",
+    "devices_used": ["device1", "device2"],
+    "favorite_apps": ["app1", "app2", "app3"]
+  },
+  "goals": {
+    "primary_goals": ["goal1", "goal2"],
+    "secondary_goals": ["goal1", "goal2"]
+  },
+  "pain_points": ["pain1", "pain2"],
+  "motivations": ["motivation1", "motivation2"],
+  "personality": {
+    "traits": ["trait1", "trait2"],
+    "communication_style": "style description"
+  },
+  "user_story": "As a [role], I want [goal] so [benefit].",
+  "acceptance_criteria": ["criteria1", "criteria2"]
+}`;
+
+  const userPrompt = `Generate ${count} diverse user persona${count > 1 ? 's' : ''} that match this description:
+
+"${description}"
+
+Requirements:
+- Generate exactly ${count} persona${count > 1 ? 's' : ''}
+- Each persona MUST match the core description: "${description}"
+- Randomize other attributes for diversity (locations worldwide, various incomes, different tech literacy levels, diverse jobs/industries, etc.)
+- Ensure realistic consistency within each persona
+- Use diverse names from various cultures
+- Return ONLY the JSON array, no other text
+
+Return format: [persona1, persona2, ...]`;
+
+  try {
+    const message = await client.messages.create({
+      model: "claude-3-5-sonnet-20241022",
+      max_tokens: 8000,
+      messages: [
+        {
+          role: "user",
+          content: `${systemPrompt}\n\n${userPrompt}`,
+        },
+      ],
+    });
+
+    const responseText = message.content[0].type === "text" ? message.content[0].text : "";
+    
+    // Clean up response (remove markdown code blocks if present)
+    let cleanedResponse = responseText.trim();
+    if (cleanedResponse.startsWith("```json")) {
+      cleanedResponse = cleanedResponse.replace(/^```json\s*/, "").replace(/```\s*$/, "").trim();
+    } else if (cleanedResponse.startsWith("```")) {
+      cleanedResponse = cleanedResponse.replace(/^```\s*/, "").replace(/```\s*$/, "").trim();
+    }
+
+    // Validate JSON
+    try {
+      const personas = JSON.parse(cleanedResponse);
+      if (!Array.isArray(personas)) {
+        throw new Error("Response is not an array");
+      }
+      
+      // Return formatted JSON
+      return JSON.stringify(personas, null, 2);
+    } catch (parseError) {
+      console.error("JSON Parse Error:", parseError);
+      console.error("Response:", cleanedResponse);
+      return `Error: Failed to parse generated personas. Raw response:\n${cleanedResponse}`;
+    }
+
+  } catch (error: any) {
+    console.error("Error generating personas:", error);
+    
+    // Fallback response
+    return JSON.stringify([
+      {
+        error: "Failed to generate personas with AI",
+        message: error.message || "Unknown error",
+        fallback_note: "The persona generation tool requires a valid Anthropic API key and internet connection."
+      }
+    ], null, 2);
+  }
+}

src/utils/persona_loader.ts

@@ -4,12 +4,57 @@ import { join } from "path";
 export interface Persona {
   id: string;
   name: string;
-  role: string;
-  goals: string[];
-  frustrations: string[];
-  tech_comfort: string;
-  quote: string;
+  age?: number;
+  gender?: string;
+  location?: {
+    address?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+  };
+  demographics?: {
+    income?: string;
+    education_level?: string;
+    marital_status?: string;
+    household_size?: number;
+  };
+  job?: {
+    title?: string;
+    industry?: string;
+    experience_years?: number;
+    employment_type?: string;
+  };
+  background?: string;
+  interests?: string[];
+  purchasing_habits?: {
+    online_shopping_frequency?: string;
+    preferred_platforms?: string[];
+    average_spend_per_month?: string;
+    brand_loyalty_level?: string;
+  };
+  technology?: {
+    tech_literacy?: string;
+    devices_used?: string[];
+    favorite_apps?: string[];
+  };
+  goals?: {
+    primary_goals?: string[];
+    secondary_goals?: string[];
+  };
   pain_points?: string[];
+  motivations?: string[];
+  personality?: {
+    traits?: string[];
+    communication_style?: string;
+  };
+  user_story?: string;
+  acceptance_criteria?: string[];
+  
+  // Legacy fields for backward compatibility
+  role?: string;
+  frustrations?: string[];
+  tech_comfort?: string;
+  quote?: string;
   needs?: string[];
 }
 
@@ -36,14 +81,105 @@ export function getPersona(personaId: string, personas: Map<string, Persona>): P
 }
 
 export function formatPersonaContext(persona: Persona): string {
+  const jobTitle = persona.job?.title || persona.role || "Unknown";
+  const industry = persona.job?.industry || "Unknown";
+  const age = persona.age || "Unknown";
+  const city = persona.location?.city || "Unknown";
+  const primaryGoals = persona.goals?.primary_goals || persona.goals as any as string[] || [];
+  const painPoints = persona.pain_points || persona.frustrations || [];
+  const motivations = persona.motivations || [];
+  const techLiteracy = persona.technology?.tech_literacy || persona.tech_comfort || "Unknown";
+  
   return `
 Persona: ${persona.name}
-Role: ${persona.role}
-Goals: ${persona.goals.join(", ")}
-Frustrations: ${persona.frustrations.join(", ")}
-Tech Comfort Level: ${persona.tech_comfort}
-Quote: "${persona.quote}"
-${persona.pain_points ? `Pain Points: ${persona.pain_points.join(", ")}` : ""}
-${persona.needs ? `Needs: ${persona.needs.join(", ")}` : ""}
+Age: ${age}
+Location: ${city}
+Title: ${jobTitle}
+Industry: ${industry}
+Background: ${persona.background || "N/A"}
+Goals: ${Array.isArray(primaryGoals) ? primaryGoals.join(", ") : "N/A"}
+Pain Points: ${Array.isArray(painPoints) ? painPoints.join(", ") : "N/A"}
+Motivations: ${Array.isArray(motivations) ? motivations.join(", ") : "N/A"}
+Tech Literacy: ${techLiteracy}
+${persona.user_story ? `User Story: ${persona.user_story}` : ""}
+${persona.quote ? `Quote: "${persona.quote}"` : ""}
 `.trim();
 }
+
+export function formatPersonaSummary(persona: Persona): any {
+  return {
+    id: persona.id,
+    name: persona.name,
+    age: persona.age,
+    location: persona.location?.city ? `${persona.location.city}, ${persona.location.state || persona.location.country}` : "Unknown",
+    job_title: persona.job?.title || persona.role || "Unknown",
+    industry: persona.job?.industry || "Unknown",
+    tech_literacy: persona.technology?.tech_literacy || persona.tech_comfort || "Unknown",
+    primary_goals: persona.goals?.primary_goals || [],
+    pain_points: persona.pain_points || persona.frustrations || [],
+    user_story: persona.user_story || "",
+  };
+}
+
+export function searchPersonas(
+  personas: Map<string, Persona>,
+  filters: {
+    role?: string;
+    industry?: string;
+    age_range?: string;
+    tech_literacy?: string;
+    location?: string;
+  }
+): Persona[] {
+  const results: Persona[] = [];
+  
+  for (const persona of personas.values()) {
+    let matches = true;
+    
+    // Filter by role/job title
+    if (filters.role) {
+      const personaRole = (persona.job?.title || persona.role || "").toLowerCase();
+      if (!personaRole.includes(filters.role.toLowerCase())) {
+        matches = false;
+      }
+    }
+    
+    // Filter by industry
+    if (filters.industry && matches) {
+      const personaIndustry = (persona.job?.industry || "").toLowerCase();
+      if (!personaIndustry.includes(filters.industry.toLowerCase())) {
+        matches = false;
+      }
+    }
+    
+    // Filter by age range (e.g., "20-30", "30-40")
+    if (filters.age_range && persona.age && matches) {
+      const [minAge, maxAge] = filters.age_range.split("-").map(Number);
+      if (persona.age < minAge || persona.age > maxAge) {
+        matches = false;
+      }
+    }
+    
+    // Filter by tech literacy
+    if (filters.tech_literacy && matches) {
+      const personaTech = (persona.technology?.tech_literacy || persona.tech_comfort || "").toLowerCase();
+      if (!personaTech.includes(filters.tech_literacy.toLowerCase())) {
+        matches = false;
+      }
+    }
+    
+    // Filter by location
+    if (filters.location && matches) {
+      const personaLocation = `${persona.location?.city || ""} ${persona.location?.state || ""} ${persona.location?.country || ""}`.toLowerCase();
+      if (!personaLocation.includes(filters.location.toLowerCase())) {
+        matches = false;
+      }
+    }
+    
+    if (matches) {
+      results.push(persona);
+    }
+  }
+  
+  return results;
+}