# 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