User Empathy MCP

Enterprise-grade MCP (Model Context Protocol) server that audits your code from multiple user persona perspectives, helping you build more accessible, empathetic, and user-friendly applications.

🎯 Overview

This MCP solves a critical problem: How will this code feel to my end-user?

While developers have linters for syntax, tests for logic, and telemetry for performance, there's no automated way to check for user experience, accessibility, and empathy. This MCP fills that gap by simulating different user personas and actively auditing your code from their perspectives.

🌍 Supported Languages & Frameworks

The MCP supports 16+ enterprise programming languages and 20+ frameworks:

Languages

• Frontend: JavaScript, TypeScript, JSX, TSX, Vue, HTML, CSS
• Backend: Python, Java, C#, Go, Rust, PHP, Ruby
• Mobile: Swift, Kotlin, Dart

Frameworks

• Frontend: React, Vue.js, Angular, Next.js, Svelte
• Backend: Django, Flask, FastAPI, Spring Boot, ASP.NET Core, Express.js, NestJS, Gin, Echo, Actix, Rocket, Laravel, Symfony, Ruby on Rails
• Mobile: Flutter

See LANGUAGES.md for complete details and analysis capabilities.

New User

• Context: Zero context. Doesn't know your app's jargon.
• Focus: Audits for confusing language, complex UI flows, and missing "empty states."

Power User

• Context: Expert user. Lives in the app. Hates the mouse.
• Focus: Audits for missing keyboard shortcuts, inefficient API calls, and unnecessary "nag" screens.

Low-Vision User

• Context: Uses a screen reader and high-contrast mode.
• Focus: Audits for missing alt-text, poor aria-labels, bad color contrast, and non-navigable components.

Throttled Connection User

• Context: On a 3G mobile connection.
• Focus: Audits for large bundle sizes, un-optimized images, and synchronous network requests that block the UI.

🚀 Features

• Real-time Code Analysis: Analyze code as you write it
• Multi-Persona Perspectives: Get feedback from all four personas simultaneously
• AST-Based Analysis: Uses Babel parser for accurate code understanding
• Multi-Language Support: Supports 16+ enterprise languages (JavaScript, TypeScript, Python, Java, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Dart, and more)
• Framework-Aware: Automatically detects React, Vue, Angular, Django, Spring Boot, ASP.NET, Laravel, Rails, and 15+ other frameworks
• Contextual Suggestions: Provides actionable suggestions for each issue
• Configurable: Enable/disable personas and customize rules
• Enterprise-Grade: Built with TypeScript, comprehensive error handling, and extensible architecture

📦 Installation

npm install
npm run build

🔧 Configuration

Quick Configuration

Create .user-empathy-config.json in your project root to customize personas:

{
  "personas": [
    {
      "id": "low-vision",
      "name": "Low-Vision User",
      "type": "low_vision",
      "enabled": true,
      "rules": []
    }
  ]
}

Runtime Configuration

Use MCP tools to enable/disable personas dynamically:

Use configure_persona tool with personaId: "low-vision" and enabled: true

See PERSONA_CONFIGURATION.md for complete configuration guide.

🛠️ Quick Start

1. Install & Build

npm install
npm run build

2. Configure in Cursor

Add to your Cursor MCP settings (Ctrl+, → Features → MCP):

{
  "mcpServers": {
    "user-empathy": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "C:\\Trimble Projects 2025\\User Empathy MCP"
    }
  }
}

3. Use It!

Simply ask Cursor to analyze your code:

• "Check this component for accessibility issues"
• "Would a new user understand this empty state?"
• "Is this API optimized for slow connections?"

See USAGE_GUIDE.md for complete usage instructions.

📚 Available Tools

analyze_code

Analyze code from a string:

{
  "name": "analyze_code",
  "arguments": {
    "code": "<div><img src=\"avatar.png\" /><button>Edit</button></div>",
    "filePath": "ProfileCard.tsx"
  }
}

analyze_file

Analyze a file from the filesystem:

{
  "name": "analyze_file",
  "arguments": {
    "filePath": "./src/components/ProfileCard.tsx"
  }
}

get_personas

Get the list of configured personas:

{
  "name": "get_personas",
  "arguments": {}
}

configure_persona

Enable or disable a persona:

{
  "name": "configure_persona",
  "arguments": {
    "personaId": "maria-low-vision",
    "enabled": true
  }
}

📝 What It Does

The Problem It Solves

You have linters for syntax, tests for logic, and telemetry for performance - but no automated way to check user experience, accessibility, and empathy.

The Solution: Four User Personas

The MCP simulates four different user personas analyzing your code:

• 👤 Low-Vision User: Finds missing alt-text, aria-labels, accessibility issues
• 👤 New User: Flags confusing jargon, missing guidance, unclear UI
• 👤 Power User: Detects missing keyboard shortcuts, unnecessary confirmations
• 👤 Throttled Connection User: Identifies performance issues, large payloads, missing loading states

Example Output

📊 Analysis Results for: ProfileCard.tsx

Summary: 2 total issues (1 errors, 1 warnings, 0 info)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 Low-Vision User:

❌ [ERROR] Line 5:10
   [Persona: Low-Vision User] Accessibility Error: This <img> tag is missing an alt attribute. A screen reader will just say "image" and I won't know what this image represents.
   💡 Suggestion: Add an alt attribute describing the image content, e.g., alt="User avatar" or alt={user.name}
   Code: <img src={user.avatarUrl} />

⚠️ [WARNING] Line 8:5
   [Persona: Low-Vision User] Accessibility Error: This <button> just says "Edit". I don't know what I'm interacting with.
   💡 Suggestion: Add an aria-label attribute with more context, e.g., aria-label="Edit profile for {user.name}"
   Code: <button>Edit</button>

🔍 How It Works

The MCP analyzes your code through a multi-step process:

1. Code Parsing: Detects language and framework, parses code into AST (for JS/TS) or uses pattern matching (for other languages)
2. Persona Analysis: Each enabled persona analyzer examines the code from their perspective
3. Issue Detection: Finds accessibility, UX, performance, and efficiency issues
4. Aggregation: Combines all issues with severity levels and suggestions
5. Response: Returns formatted results with actionable feedback

See HOW_IT_WORKS.md for detailed technical explanation.

src/
├── analyzers/          # Persona-specific analyzers
│   ├── base.ts
│   ├── low-vision.ts
│   ├── new-user.ts
│   ├── power-user.ts
│   └── throttled-connection.ts
├── types.ts            # TypeScript type definitions
├── parser.ts           # Code parsing utilities
├── analyzer-factory.ts # Factory for creating analyzers
├── analysis-engine.ts  # Main analysis coordination
├── config-manager.ts   # Configuration management
├── personas.ts         # Default persona configurations
└── index.ts            # MCP server entry point

🧪 Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Format code
npm run format

📚 Extending

Adding a New Persona

1. Create a new analyzer class extending PersonaAnalyzer:

import { PersonaAnalyzer } from './base.js';
import type { PersonaConfig, PersonaAnalysisContext, CodeIssue } from './types.js';

export class MyCustomAnalyzer extends PersonaAnalyzer {
  analyze(context: PersonaAnalysisContext): CodeIssue[] {
    // Your analysis logic here
  }
}

2. Register it in analyzer-factory.ts
3. Add it to personas.ts with default configuration

Customizing Rules

Modify the rules array in your persona configuration to customize which patterns are checked.

🤝 Contributing

This is an enterprise-grade project. Code quality standards:

• TypeScript strict mode
• Comprehensive error handling
• Extensive test coverage
• Clear documentation
• Follow existing code patterns

📄 License

MIT

🙏 Acknowledgments

Built with:

• @modelcontextprotocol/sdk
• @babel/parser
• zod for runtime validation