HealixPath / PROJECT_SUMMARY.md
mackenzietechdocs's picture DevRubenArevalo's picture
project-init-alpha (#2)
c6a01e9 verified
|
Raw History Blame Contribute Delete
8.37 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

HealixPath - Project Summary

🎯 Mission

HealixPath is an enterprise-grade Model Context Protocol (MCP) server and Gradio web interface that generates realistic, actionable user stories grounded in deeply researched personas. It transforms product inputs, personas, problems, and customer journey stages into rich, structured, realistic narratives.

πŸ“ Project Structure

healixpath/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ tools/
β”‚   β”‚   β”œβ”€β”€ user_story.ts              # Generate structured user stories
β”‚   β”‚   β”œβ”€β”€ customer_experience_tale.ts # Create experience narratives
β”‚   β”‚   β”œβ”€β”€ feature_impact_story.ts    # Before/after feature stories
β”‚   β”‚   └── journey_map_story.ts       # Journey stage narratives
β”‚   β”œβ”€β”€ utils/
β”‚   β”‚   β”œβ”€β”€ persona_loader.ts          # Load and manage personas
β”‚   β”‚   └── helpers.ts                 # Utility functions
β”‚   └── index.ts                       # MCP server initialization
β”œβ”€β”€ data/
β”‚   └── personas.json                  # Pre-defined personas
β”œβ”€β”€ app.py                             # Gradio web interface
β”œβ”€β”€ package.json                       # Node.js dependencies
β”œβ”€β”€ tsconfig.json                      # TypeScript configuration
β”œβ”€β”€ requirements.txt                   # Python dependencies
β”œβ”€β”€ README.md                          # Project documentation (with HF Spaces config)
β”œβ”€β”€ DEPLOYMENT.md                      # Deployment guide
β”œβ”€β”€ mcp.config.json                    # MCP server configuration
β”œβ”€β”€ .env.example                       # Environment variables template
└── .gitignore                         # Git ignore patterns

πŸ”Ή Four Core Tools

1. user_story

Generates structured narrative user stories with acceptance criteria and risks.

Input:

  • product: Description of the product/feature
  • persona_id (optional): ID of the persona (busy_parent, ops_engineer, product_manager)
  • persona_override (optional): Custom persona description

Output:

{
  "story": "Detailed narrative (150-300 words)",
  "acceptance_criteria": ["criterion 1", "criterion 2"],
  "risks": ["risk 1", "risk 2"]
}

2. customer_experience_tale

Creates narratives describing a persona experiencing a specific problem.

Input:

  • problem: The problem the persona is experiencing
  • persona_id (optional): ID of the persona
  • persona_override (optional): Custom persona description

Output:

{
  "title": "Compelling title",
  "narrative": "250-400 word story",
  "pain_points": ["pain 1", "pain 2"],
  "opportunities": ["opportunity 1", "opportunity 2"]
}

3. feature_impact_story

Shows before and after of a persona interacting with a feature.

Input:

  • feature_description: Description of the feature
  • persona_id (optional): ID of the persona
  • persona_override (optional): Custom persona description

Output:

{
  "before_story": "300 word narrative without feature",
  "after_story": "300 word narrative with feature",
  "key_benefits": ["benefit 1", "benefit 2"],
  "success_metrics": ["metric 1", "metric 2"]
}

4. journey_map_story

Generates narrative for specific stages of the user journey.

Input:

  • stage: Journey stage (awareness, consideration, adoption, retention)
  • product: Description of the product
  • persona_id (optional): ID of the persona
  • persona_override (optional): Custom persona description

Output:

{
  "stage": "adoption",
  "narrative": "250-300 word narrative",
  "touchpoints": ["touchpoint 1", "touchpoint 2"],
  "emotions": ["emotion 1", "emotion 2"],
  "breakdowns": ["breakdown 1", "breakdown 2"],
  "opportunities": ["opportunity 1", "opportunity 2"]
}

πŸ‘₯ Built-in Personas

1. Busy Parent (busy_parent)

  • Role: Working parent of two kids
  • Goals: Save time, reduce mental load, keep kids on schedule
  • Tech Comfort: Medium
  • Quote: "If it's not simple, I don't have time for it."

2. Ops Engineer (ops_engineer)

  • Role: On-call site reliability engineer
  • Goals: Reduce alerts, improve stability, automate tasks
  • Tech Comfort: High
  • Quote: "If it breaks, it's my problem at 3am."

3. Product Manager (product_manager)

  • Role: PM at a healthcare startup
  • Goals: Understand users deeply, make data-driven decisions, validate quickly
  • Tech Comfort: High
  • Quote: "I need to understand my users' hearts, not just their actions."

πŸš€ Getting Started

Prerequisites

  • Node.js 20+
  • Python 3.10+
  • npm or yarn

Installation

# Install Node dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

Development

# Build TypeScript
npm run build

# Run MCP Server
npm run start

# Run Gradio Interface (in another terminal)
python app.py

Production

# Build for production
npm run build

# Deploy to Hugging Face Spaces
git push  # (after setting up Space repo)

πŸ”§ Configuration

Hugging Face Spaces YAML (in README.md)

---
title: HealixPath
emoji: πŸ’š
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: true
short_description: AI-powered persona storytelling engine
tags:
  - mcp-hackathon
  - building-mcp-track-enterprise
  - healthcare
  - ai
---

Environment Variables

Create .env file (see .env.example):

ANTHROPIC_API_KEY=sk_your_key_here
HF_TOKEN=hf_your_token_here
GRADIO_SERVER_PORT=7860

🌐 User Interfaces

MCP Server (Node.js)

  • Port: Configurable (default 3000)
  • Integration: Works with Claude, other AI models, and custom applications
  • Usage: See src/index.ts for implementation example

Gradio Web Interface (Python)

  • Port: 7860 (Hugging Face Spaces default)
  • Features:
    • Interactive UI with 4 tabs (one for each tool)
    • Pre-loaded personas dropdown
    • Custom persona input
    • Real-time generation

πŸ“š Key Technologies

Backend

  • TypeScript - Type-safe JavaScript
  • Node.js - JavaScript runtime
  • Model Context Protocol (MCP) - Standard interface for AI assistants
  • Anthropic SDK - Claude API integration

Frontend

  • Gradio - Python web framework for ML demos
  • Python - Scripting language

Deployment

  • Hugging Face Spaces - Free hosting for ML demos
  • Docker - Containerization (optional)
  • Git - Version control

🎯 Hackathon Features

✨ Ready for Demo:

  • Complete MCP server implementation
  • Interactive Gradio web UI
  • Pre-loaded sample personas
  • Hugging Face Spaces configuration
  • Full project documentation
  • Example tool calls in index.ts

πŸ”Œ Integration Ready:

  • Works with Claude API (placeholder ready for integration)
  • Standard MCP interface for tools
  • JSON-based I/O for easy integration
  • Extensible persona system

πŸš€ Deploy Ready:

  • One-click deployment to Hugging Face Spaces
  • Docker support for custom deployments
  • Environment variable configuration
  • Logging and monitoring

πŸ“‹ Next Steps for Production

  1. API Integration: Replace placeholder functions with actual Claude API calls
  2. Custom Personas: Add domain-specific personas for your use case
  3. Data Persistence: Connect to database for storing generated stories
  4. Authentication: Add user authentication with Hugging Face OAuth
  5. Caching: Implement Redis for response caching
  6. Testing: Add comprehensive unit and integration tests
  7. Monitoring: Set up error tracking and analytics
  8. Documentation: Add API documentation and user guides

🀝 Contributing

To extend HealixPath:

  1. Add new personas to data/personas.json
  2. Create new tools in src/tools/
  3. Update src/index.ts to register new tools
  4. Add corresponding UI tabs in app.py
  5. Test with MCP server examples

πŸ“„ License

MIT License - See LICENSE file for details

πŸ† Built for MCP Hackathon

HealixPath is an enterprise-ready solution demonstrating the power of MCP in building AI-driven applications for real-world use cases in healthcare, product management, and UX design.


Version: 1.0.0
Last Updated: November 2025
Status: Production Ready for Hackathon Demo