HealixPath / PROJECT_SUMMARY.md
mackenzietechdocs's picture DevRubenArevalo's picture
project-init-alpha (#2)
c6a01e9 verified
|
Raw History Blame Contribute Delete
8.37 kB
# 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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
```bash
# Install Node dependencies
npm install
# Install Python dependencies
pip install -r requirements.txt
```
### Development
```bash
# Build TypeScript
npm run build
# Run MCP Server
npm run start
# Run Gradio Interface (in another terminal)
python app.py
```
### Production
```bash
# 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)
```yaml
---
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`):
```env
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