Spaces:
Running
Download PROJECT_SUMMARY.md from mackenzietechdocs/HealixPath: direct link, hf CLI and curl.
- Browser
- Download file 8.37 kB
-
https://huggingface.co/spaces/mackenzietechdocs/HealixPath/resolve/main/PROJECT_SUMMARY.md
- Command line
-
hf download hf://spaces/mackenzietechdocs/HealixPath/PROJECT_SUMMARY.md
-
curl -L -o PROJECT_SUMMARY.md https://huggingface.co/spaces/mackenzietechdocs/HealixPath/resolve/main/PROJECT_SUMMARY.md
A newer version of the Gradio SDK is available: 6.32.0
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/featurepersona_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 experiencingpersona_id(optional): ID of the personapersona_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 featurepersona_id(optional): ID of the personapersona_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 productpersona_id(optional): ID of the personapersona_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.tsfor 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
- API Integration: Replace placeholder functions with actual Claude API calls
- Custom Personas: Add domain-specific personas for your use case
- Data Persistence: Connect to database for storing generated stories
- Authentication: Add user authentication with Hugging Face OAuth
- Caching: Implement Redis for response caching
- Testing: Add comprehensive unit and integration tests
- Monitoring: Set up error tracking and analytics
- Documentation: Add API documentation and user guides
π€ Contributing
To extend HealixPath:
- Add new personas to
data/personas.json - Create new tools in
src/tools/ - Update
src/index.tsto register new tools - Add corresponding UI tabs in
app.py - 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