Stories that spiral from a persona. HealixPath is an AI-powered storytelling engine that turns a product, a problem, or a journey stage into structured, realistic narratives for the people who will actually use the work.
Built by Mackenzie O'Brien (@mackenzietechdocs, GitHub) and co-author @DevRubenArevalo (Hugging Face, GitHub). Together we are Team Healix.
The official November 2025 hackathon submission lives at MCP-1st-Birthday/TeamHealix and is kept unchanged. This repository and the live Space are the maintained copy.
| Project page | mso-docs.github.io/HealixPath |
| Hackathon Space (frozen) | MCP-1st-Birthday/TeamHealix |
| Live Space | mackenzietechdocs/HealixPath |
| Collection | HealixPath |
| GitHub | mso-docs/HealixPath |
| Demo video | youtu.be/zz5AliukXKk |
This live copy does not use any paid API key. Text generation runs on open models through Hugging Face Inference Providers, using your own Hugging Face account:
- Click Sign in with Hugging Face at the top of the app and approve the
inference-apipermission. - Generate stories, journeys, and personas. Each request is billed to your account's free monthly Inference Providers allowance. If you run out, Hugging Face will tell you; PRO accounts get a larger allowance.
- Signed-out visitors can browse and search personas, but generation shows a "please sign in" message. The Space never falls back to its owner's token or any secret.
Model: openai/gpt-oss-20b (open weights, Apache 2.0, instruction-tuned). When running your own copy, set the HEALIXPATH_MODEL environment variable to any chat model served by Inference Providers.
MCP clients: the Gradio MCP endpoint is https://mackenzietechdocs-healixpath.hf.space/gradio_api/mcp/. Tools that generate text need a Hugging Face token with the "Make calls to Inference Providers" permission; send it as Authorization: Bearer <your token>.
Running locally: pip install -r requirements.txt && python app.py. Local OAuth sign-in needs a Space; the app does not read HF_TOKEN. Duplicate the Space to your account to get your own copy with sign-in enabled.
- LinkedIn: announcement and hackathon post
- Demo video: youtu.be/zz5AliukXKk
HealixPath delivers AI-powered persona storytelling for UX, product, and design teams. Instead of vague bullet points like βUser gets frustrated during checkout,β HealixPath generates:
- actionable narratives
- persona-grounded insights
- pain points & opportunities
- before/after feature impact stories
- journey-map narratives
Designed to help product teams feel their users, not just document them.
Each tool is exposed through the MCP server (src/index.ts) and powered by open models via Hugging Face Inference Providers in the Gradio app (the original hackathon build used Claude). Prompts request JSON-only output.
Lists all available personas with their key attributes.
Input
{
"limit": "number (optional)"
}Output
{
"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"
}Search and filter personas by various criteria.
Input
{
"role": "string (optional)",
"industry": "string (optional)",
"age_range": "string (optional, e.g., '25-35')",
"tech_literacy": "string (optional)",
"location": "string (optional)"
}Output
{
"personas": ["array of matching personas"],
"count": "number",
"filters": "object with applied filters"
}Generates a structured narrative user story + acceptance criteria from a product and persona.
Input
{
"product": "string",
"persona_id": "string (optional)",
"persona_override": "string (optional)"
}Output
{
"story": "string",
"acceptance_criteria": ["string"],
"risks": ["string"]
}Creates a short narrative describing a persona experiencing a specific problem.
Input
{
"persona_id": "string (optional)",
"persona_override": "string (optional)",
"problem": "string"
}Output
{
"title": "string",
"narrative": "string",
"pain_points": ["string"],
"opportunities": ["string"]
}Shows the before and after of a persona interacting with a feature.
Input
{
"feature_description": "string",
"persona_id": "string (optional)",
"persona_override": "string (optional)"
}Output
{
"before_story": "string",
"after_story": "string",
"key_benefits": ["string"],
"success_metrics": ["string"]
}Generates a narrative for a specific stage of the user journey.
Input
{
"stage": "string",
"product": "string",
"persona_id": "string (optional)",
"persona_override": "string (optional)"
}Output
{
"stage": "string",
"narrative": "string",
"touchpoints": ["string"],
"emotions": ["string"],
"breakdowns": ["string"],
"opportunities": ["string"]
}Personas are also exposed as MCP resources for easy browsing:
personas://all- Complete list of all personas with summariespersonas://[id]- Individual persona details (e.g.,personas://persona-001)
Resources allow LLM clients to browse and reference personas without making tool calls.
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",
"goals": ["Reduce alerts", "Stability", "Automate repetitive tasks"],
"frustrations": ["Pager fatigue", "Unclear incident logs", "Slow dashboards"],
"tech_comfort": "high",
"quote": "If it breaks, it's my problem at 3am."
} ]
Add more personas anytimeβ`src/utils/persona_loader.ts` automatically loads them.
---
## π 4. System Prompt (Paste into MCP Server or Claude Playground)
You are HealixPath, an enterprise-grade AI persona path engine. Your goal is to help product, UX, and design teams deeply understand users by generating realistic, structured persona-driven stories.
You ALWAYS:
- adopt the personaβs perspective (from persona_id data or persona_override text)
- integrate goals, frustrations, role, and quote into narrative context
- maintain realism with specific details (environment, device, timing)
- highlight both pain points and business opportunities
- write with clarity, professionalism, and grounded emotional tone
- output ONLY valid JSON in the exact schema specified by the user
Style:
- narratives: 250β600 words
- avoid buzzwords and marketing fluff
- focus on concrete behaviors & motivations
- connect the story directly back to the product input or feature description
If persona_id is provided, load persona data from the persona database. If persona_override is provided, use it as supplemental context, not a replacement.
If both are missing, create a plausible persona from scratch with sensible traits.
Strictly follow schemas provided in each tool.
This exact prompt is codified in `src/utils/prompts.ts`.
---
## π§ͺ 5. Few-Shot Example (Use in Prompting or README)
Example for customer_experience_tale Input: persona:
- 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"]
- quote: "If it's not simple, I don't have time for it." problem: "Promo code fails during mobile checkout on a flash sale"
Expected Output: { "title": "Promo Panic at Bedtime", "narrative": "It's 8:45pm and Maya sinks into her couch after finally putting her two kids to bed...", "pain_points": [ "Ambiguous promo code error message", "Checkout form resets when navigating back", "Customer support queue too long for short sessions" ], "opportunities": [ "Clearer inline error messaging", "Auto-saving form state", "Fast support path during busy sale windows" ] }
---
## π 6. Recommended Repo Structure (already implemented)
healixpath/ ββ src/ β ββ tools/ β β ββ user_story.ts β β ββ customer_experience_tale.ts β β ββ feature_impact_story.ts β β ββ journey_map_story.ts β ββ utils/ β β ββ persona_loader.ts β β ββ helpers.ts β β ββ prompts.ts β ββ index.ts ββ data/ β ββ personas.json ββ app.py ββ package.json ββ tsconfig.json ββ requirements.txt ββ README.md ββ .env (create from .env.example)
---
## βοΈ 7. Getting Started
### Node.js MCP Server
```bash
cp .env.example .env # optional: only the original local Node demo used an Anthropic key
npm install
npm run build
npm run start
src/index.ts boots the HealixPath MCP server, enumerates tools, and shows sample tool calls. This local TypeScript demo is the original hackathon prototype; the live Gradio app does not use it.
pip install -r requirements.txt
python app.pyapp.py offers a quick UI to showcase personas and tool outputs during demos or on Hugging Face Spaces.
βWe built HealixPath, an AI engine that generates realistic persona-based stories for UX and product teams. Instead of vague bullet points like βUser is frustrated at checkout,β HealixPath produces rich narratives, pain points, opportunities, and journey maps β all grounded in real personas. It takes a product description or problem, merges it with persona data, and instantly produces a believable, actionable user story. This helps teams design better flows, features, and experiences by understanding the human side behind the analytics. In just one click, a PM can generate a story that feels like it came from weeks of user research.β
Then show a persona β problem β generated JSON/story.
- Logo explorations for HealixPath (neon, simple, minimal, enterprise)
- Brand color palette or landing page copy
- Full MCP client or UI mockup for demos
- Domain availability research
Ping me when youβre ready for the next layer of polish!
Built for the MCP Hackathon π
