import "dotenv/config"; import { loadPersonas, getPersona, formatPersonaSummary, searchPersonas, type Persona, } from "./utils/persona_loader.js"; import { generateUserStory, type UserStoryInput } from "./tools/user_story.js"; import { generateCustomerExperienceTale, type CustomerExperienceTaleInput, } from "./tools/customer_experience_tale.js"; import { generateFeatureImpactStory, type FeatureImpactStoryInput, } from "./tools/feature_impact_story.js"; import { generateJourneyMapStory, type JourneyMapStoryInput, } from "./tools/journey_map_story.js"; import { generatePersonas } from "./tools/generate_personas.js"; interface ToolSchema { name: string; description: string; input_schema: { type: string; properties: Record; required: string[]; }; } interface ResourceSchema { uri: string; name: string; description: string; mimeType: string; } class HealixPathServer { private personas: Map; constructor() { this.personas = loadPersonas(); } getTools(): ToolSchema[] { return [ { name: "list_personas", description: "List all available personas with their key attributes (id, name, age, location, job title, industry, tech literacy, goals, pain points)", input_schema: { type: "object", properties: { limit: { type: "number", description: "Optional: Maximum number of personas to return (default: all)", }, }, required: [], }, }, { name: "search_personas", description: "Search and filter personas by role/job title, industry, age range, tech literacy, or location", input_schema: { type: "object", properties: { role: { type: "string", description: "Filter by job title or role (partial match, case-insensitive)", }, industry: { type: "string", description: "Filter by industry (partial match, case-insensitive)", }, age_range: { type: "string", description: "Filter by age range (format: 'min-max', e.g., '25-35')", }, tech_literacy: { type: "string", description: "Filter by tech literacy level (e.g., 'high', 'moderate', 'low')", }, location: { type: "string", description: "Filter by location - city, state, or country (partial match)", }, }, required: [], }, }, { name: "user_story", description: "Generate a structured narrative user story with acceptance criteria and risks", input_schema: { type: "object", properties: { product: { type: "string", description: "Description of the product or feature", }, persona_id: { type: "string", description: "ID of the persona to use (use list_personas to see available IDs)", }, persona_override: { type: "string", description: "Custom persona description if persona_id is not provided", }, }, required: ["product"], }, }, { name: "customer_experience_tale", description: "Create a narrative describing a persona experiencing a specific problem", input_schema: { type: "object", properties: { problem: { type: "string", description: "The problem the persona is experiencing", }, persona_id: { type: "string", description: "ID of the persona to use", }, persona_override: { type: "string", description: "Custom persona description if persona_id is not provided", }, }, required: ["problem"], }, }, { name: "feature_impact_story", description: "Show the before and after of a persona interacting with a feature", input_schema: { type: "object", properties: { feature_description: { type: "string", description: "Description of the feature", }, persona_id: { type: "string", description: "ID of the persona to use", }, persona_override: { type: "string", description: "Custom persona description if persona_id is not provided", }, }, required: ["feature_description"], }, }, { name: "journey_map_story", description: "Generate a narrative for a specific stage of the user journey", input_schema: { type: "object", properties: { stage: { type: "string", description: "Journey stage (e.g., awareness, consideration, adoption, retention)", }, product: { type: "string", description: "Description of the product", }, persona_id: { type: "string", description: "ID of the persona to use", }, persona_override: { type: "string", description: "Custom persona description if persona_id is not provided", }, }, required: ["stage", "product"], }, }, { name: "generate_personas", description: "Generate random user personas based on a natural language description. Creates realistic, diverse personas matching the specified criteria with randomized attributes for variety.", input_schema: { type: "object", properties: { description: { type: "string", description: "Natural language description of the personas to generate (e.g., 'people who love to cook but never have time to in their 20-30s', 'sandwich enthusiasts who are 50+ years old')", }, count: { type: "number", description: "Number of personas to generate (minimum: 1, maximum: 5, default: 1)", }, }, required: ["description", "count"], }, }, ]; } getResources(): ResourceSchema[] { const resources: ResourceSchema[] = [ { uri: "personas://all", name: "All Personas", description: "Complete list of all available personas with their full details", mimeType: "application/json", }, ]; // Add individual persona resources for (const [id, persona] of this.personas.entries()) { resources.push({ uri: `personas://${id}`, name: `${persona.name} - ${persona.job?.title || persona.role || "User"}`, description: `Detailed information about ${persona.name}`, mimeType: "application/json", }); } return resources; } async readResource(uri: string): Promise { if (uri === "personas://all") { const allPersonas = Array.from(this.personas.values()).map(formatPersonaSummary); return JSON.stringify(allPersonas, null, 2); } // Handle individual persona URIs if (uri.startsWith("personas://")) { const personaId = uri.replace("personas://", ""); const persona = this.personas.get(personaId); if (!persona) { return JSON.stringify({ error: `Persona not found: ${personaId}` }); } return JSON.stringify(persona, null, 2); } return JSON.stringify({ error: `Unknown resource URI: ${uri}` }); } async processTool( toolName: string, toolInput: Record ): Promise { // Handle list_personas tool if (toolName === "list_personas") { const limit = typeof toolInput.limit === "number" ? toolInput.limit : undefined; const allPersonas = Array.from(this.personas.values()).map(formatPersonaSummary); const personas = limit ? allPersonas.slice(0, limit) : allPersonas; return JSON.stringify({ personas, total: this.personas.size }, null, 2); } // Handle search_personas tool if (toolName === "search_personas") { const filters = { role: typeof toolInput.role === "string" ? toolInput.role : undefined, industry: typeof toolInput.industry === "string" ? toolInput.industry : undefined, age_range: typeof toolInput.age_range === "string" ? toolInput.age_range : undefined, tech_literacy: typeof toolInput.tech_literacy === "string" ? toolInput.tech_literacy : undefined, location: typeof toolInput.location === "string" ? toolInput.location : undefined, }; const results = searchPersonas(this.personas, filters); const summaries = results.map(formatPersonaSummary); return JSON.stringify({ personas: summaries, count: summaries.length, filters: Object.fromEntries(Object.entries(filters).filter(([_, v]) => v !== undefined)) }, null, 2); } let persona: Persona | undefined; // Load persona if specified if (typeof toolInput.persona_id === "string") { const loadedPersona = getPersona(toolInput.persona_id, this.personas); if (!loadedPersona) { return JSON.stringify({ error: `Persona not found: ${toolInput.persona_id}`, }); } persona = loadedPersona; } try { switch (toolName) { case "user_story": { const input = toolInput as unknown as UserStoryInput; const userStory = await generateUserStory(input, persona); return JSON.stringify(userStory); } case "customer_experience_tale": { const input = toolInput as unknown as CustomerExperienceTaleInput; const tale = await generateCustomerExperienceTale(input, persona); return JSON.stringify(tale); } case "feature_impact_story": { const input = toolInput as unknown as FeatureImpactStoryInput; const impactStory = await generateFeatureImpactStory(input, persona); return JSON.stringify(impactStory); } case "journey_map_story": { const input = toolInput as unknown as JourneyMapStoryInput; const journeyStory = await generateJourneyMapStory(input, persona); return JSON.stringify(journeyStory); } case "generate_personas": { const description = typeof toolInput.description === "string" ? toolInput.description : ""; const count = typeof toolInput.count === "number" ? toolInput.count : 1; if (!description) { return JSON.stringify({ error: "Description is required" }); } const personas = await generatePersonas({ description, count }); return personas; // Already JSON stringified } default: return JSON.stringify({ error: `Unknown tool: ${toolName}` }); } } catch (error) { return JSON.stringify({ error: `Failed to process tool: ${error instanceof Error ? error.message : String(error)}`, }); } } } // Example usage and server setup async function main(): Promise { const server = new HealixPathServer(); console.log("šŸš€ HealixPath MCP Server"); console.log("======================="); console.log("\nAvailable Tools:"); server.getTools().forEach((tool) => { console.log(`\n- ${tool.name}`); console.log(` ${tool.description}`); }); console.log("\n\nAvailable Resources:"); server.getResources().slice(0, 5).forEach((resource) => { console.log(`\n- ${resource.uri}`); console.log(` ${resource.description}`); }); console.log(`\n... and ${server.getResources().length - 5} more persona resources`); console.log("\n\nšŸ“ Example Tool Calls:"); console.log("---"); // Example 0: List Personas const listResult = await server.processTool("list_personas", { limit: 3 }); console.log("\n0. List Personas (first 3):"); console.log(listResult); // Example 0b: Search Personas const searchResult = await server.processTool("search_personas", { industry: "healthcare", tech_literacy: "moderate" }); console.log("\n0b. Search Personas (Healthcare + Moderate Tech):"); console.log(searchResult); // Example 0c: Read Resource const resourceResult = await server.readResource("personas://all"); console.log("\n0c. Read Resource (all personas summary - truncated):"); console.log(resourceResult.substring(0, 500) + "..."); // Example 1: User Story const userStoryResult = await server.processTool("user_story", { product: "Healthcare appointment scheduling app", persona_id: "persona-001", }); console.log("\n1. User Story:"); console.log(userStoryResult); // Example 2: Customer Experience Tale const taleResult = await server.processTool("customer_experience_tale", { problem: "Mobile app crashes during checkout", persona_id: "persona-001", }); console.log("\n2. Customer Experience Tale:"); console.log(taleResult); // Example 3: Feature Impact Story const impactResult = await server.processTool("feature_impact_story", { feature_description: "One-click scheduling with automatic reminders", persona_id: "persona-001", }); console.log("\n3. Feature Impact Story:"); console.log(impactResult); // Example 4: Journey Map Story const journeyResult = await server.processTool("journey_map_story", { stage: "adoption", product: "Healthcare platform", persona_id: "persona-003", }); console.log("\n4. Journey Map Story:"); console.log(journeyResult); // Example 5: Generate Personas const generateResult = await server.processTool("generate_personas", { description: "people who love to cook but never have time to in their 20-30s", count: 2, }); console.log("\n5. Generate Personas (cooking enthusiasts, 20-30s, time-constrained):"); console.log(generateResult); console.log("\n\nāœ… HealixPath Server is ready to serve MCP clients!"); } main().catch(console.error);