npm package: @neuria/mcp-server
Description: Emotion-driven design intelligence for AI coding tools
Author: NEURIA
Latest version: 1.0.0

<p align="center">
  <img src="https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square" alt="MCP Compatible">
  <img src="https://img.shields.io/badge/Tools-10-green?style=flat-square" alt="10 Tools">
  <img src="https://img.shields.io/badge/Emotions-6-purple?style=flat-square" alt="6 Emotions">
  <img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="MIT License">
</p>

# NEURIA — Emotion-Driven Design Intelligence for AI Coding Tools

**NEURIA** is an MCP (Model Context Protocol) server that gives AI assistants like Claude, Cursor, and Windsurf a *sense of design taste*. Instead of relying on generic Tailwind defaults or hardcoded color palettes, AI agents query NEURIA for emotion-aligned design tokens — colors, typography, spacing, animations — all backed by real-world data from 300+ award-winning websites.

> "Design is not just what it looks like. Design is how it feels." — Steve Jobs

NEURIA quantifies that *feeling* into actionable design tokens.

---

## What is NEURIA?

NEURIA maps **6 core emotions** to complete design systems:

| Emotion | Vibe | Example Brands |
|---|---|---|
| **Trust** | Stable, reliable, professional | Linear, Stripe, Notion |
| **Excitement** | Bold, energetic, dynamic | Vercel, Arc, Framer |
| **Calm** | Serene, minimal, breathable | Headspace, Muji, Apple |
| **Luxury** | Premium, refined, exclusive | Porsche, Rolex, Aesop |
| **Innovation** | Futuristic, cutting-edge, smart | OpenAI, Tesla, Figma |
| **Energy** | Vibrant, playful, high-tempo | Spotify, Discord, Duolingo |

Each emotion includes **color palettes**, **typography settings**, **spacing scales**, **border radii**, **shadow styles**, and **animation parameters** — all derived from statistical analysis of real CSS extracted from 300+ top websites.

---

## Quick Start

### 1. Add to your MCP config

Add to your `.mcp.json` (Claude Code) or IDE MCP settings:

```json
{
  "mcpServers": {
    "neuria": {
      "type": "sse",
      "url": "https://api.neuria.tech/mcp"
    }
  }
}
```

That's it. No API key needed for core tools.

### 2. Local Development (Optional)

```bash
git clone https://github.com/kosukeuemura0220-del/neuria-agent.git
cd neuria-agent
pip install -r requirements.txt
cp .env.example .env
# Fill in API keys for advanced tools (see .env.example)
python3 mcp-servers/neuria/server.py
```

---

## 10 MCP Tools

### Core Tools (No API Key Required)

| # | Tool | Description | Input |
|---|---|---|---|
| 1 | `get_emotion_tokens` | Get CSS custom properties for an emotion | `emotion`, `category` |
| 2 | `search_similar_designs` | Find similar designs via pgvector cosine similarity | `query`, `mood`, `component_type` |
| 3 | `get_color_palette` | Get a 5-color palette + Color API scheme | `emotion`, `industry` |
| 4 | `get_typography` | Get font settings for emotion × use case | `emotion`, `use_case` |
| 5 | `score_html` | Score HTML against NEURIA design standards | `html_content`, `target_emotion`, `url` |
| 8 | `get_animation_tokens` | Get GSAP / CSS / Spring animation parameters | `emotion`, `context` |

### Advanced Tools (API Keys Required)

| # | Tool | Description | Required Keys |
|---|---|---|---|
| 6 | `generate_hero_image` | AI-generated emotion-matched hero image | 3D AI Studio |
| 7 | `analyze_reference_url` | Extract design tokens from any URL (W3C DTCG format) | `FIRECRAWL_API_KEY` |
| 9 | `analyze_visual_design` | Dual-analysis: screenshot colors + CSS analysis | `SCREENSHOTONE_API_KEY`, `IMAGGA_API_KEY` |
| 10 | `analyze_brand_voice` | Text emotion analysis via Hume AI | `HUME_API_KEY` |

---

## Example Usage

### 1. Generate a Landing Page with Emotion Tokens

```
User: "Analyze linear.app and create a SaaS landing page with the same design feel"

→ NEURIA calls: analyze_reference_url("https://linear.app")
  Returns: dominant_emotion="innovation", W3C DTCG design tokens, emotion_scores

→ NEURIA calls: get_emotion_tokens("innovation")
  Returns: CSS variables (--neuria-bg, --neuria-accent, --neuria-font-*, etc.)

→ NEURIA calls: get_animation_tokens("innovation", "page_load")
  Returns: GSAP ease, CSS cubic-bezier, Spring physics params

→ Claude generates HTML using NEURIA tokens (no hardcoded colors)
→ NEURIA calls: score_html(generated_html, "innovation")
  Returns: composite_score=87/100 ✅
```

### 2. Quick Color Palette for Fintech

```
User: "I need a trustworthy color palette for a fintech app"

→ get_color_palette("trust", industry="fintech")
  Returns:
  {
    "background": "#0B1120",
    "surface": "#131D36",
    "accent": "#2E7DFF",
    "text_primary": "#E8ECF4",
    "text_secondary": "#7A8BAB",
    "color_scheme": [...5 harmonious colors from The Color API]
  }
```

### 3. Brand Voice Analysis

```
User: "What emotion does Apple's copy convey?"

→ analyze_brand_voice(url="https://apple.com")
  Returns:
  {
    "dominant_emotion": "innovation",
    "neuria_emotions": {
      "innovation": 0.31,
      "luxury": 0.24,
      "calm": 0.19,
      ...
    }
  }
```

---

## Architecture

```
┌──────────────────────────────────────────────┐
│              AI Coding Tool                   │
│     (Claude Code / Cursor / Windsurf)         │
└──────────────┬───────────────────────────────┘
               │ MCP Protocol (stdio / SSE)
               ▼
┌──────────────────────────────────────────────┐
│            NEURIA MCP Server                  │
│                                               │
│  ┌─────────┐ ┌──────────┐ ┌──────────────┐  │
│  │ Emotion  │ │ Supabase │ │  External    │  │
│  │ Token DB │ │ pgvector │ │  APIs        │  │
│  │ (6×CSS)  │ │ (300+    │ │              │  │
│  │          │ │  sites)  │ │ • Firecrawl  │  │
│  └─────────┘ └──────────┘ │ • Color API  │  │
│                            │ • ScreenShot │  │
│  ┌─────────────────────┐  │ • Imagga     │  │
│  │ Animation Tokens    │  │ • Hume AI    │  │
│  │ (6 emotions ×       │  │ • WAVE       │  │
│  │  4 contexts)        │  │ • 3D AI      │  │
│  └─────────────────────┘  └──────────────┘  │
└──────────────────────────────────────────────┘
```

---

## Scoring System

`score_html` evaluates generated HTML across 4 dimensions:

| Dimension | Weight | What it Measures |
|---|---|---|
| **Aesthetic** | 35% | Visual harmony, whitespace, color usage |
| **Emotion** | 35% | Alignment with target emotion tokens |
| **Technical** | 15% | Clean markup, performance, responsive |
| **Accessibility** | 15% | WCAG 2.1 AA (lang, alt, contrast, headings) |

**Target: 85+ / 100** for production-quality output.

---

## Environment Variables

Create a `.env` file at the project root (see `.env.example`):

```env
# Required for core functionality
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_anon_key
NEURIA_API_BASE=your_api_base_url

# Required for analyze_reference_url
FIRECRAWL_API_KEY=your_firecrawl_key

# Required for generate_hero_image
THREE_D_AI_STUDIO_KEY=your_3d_ai_key

# Required for analyze_visual_design
SCREENSHOTONE_API_KEY=your_key
IMAGGA_API_KEY=your_key
IMAGGA_API_SECRET=your_secret

# Required for analyze_brand_voice
HUME_API_KEY=your_hume_key

# Optional — WAVE accessibility API
WAVE_API_KEY=your_wave_key
```

---

## Pricing

> Coming soon

| Plan | Price | Requests |
|---|---|---|
| **Free** | $0/mo | 5 req/day |
| **Indie** | $19/mo | 500 req/mo |
| **Pro** | $49/mo | 2,000 req/mo |
| **Team** | $149/mo | 10,000 req/mo |
| **Enterprise** | Custom | Unlimited |

---

## Links

- **Website**: [https://neuria.tech](https://neuria.tech)
- **MCP Endpoint**: `https://api.neuria.tech/mcp`
- **API Docs**: [https://api.neuria.tech/docs](https://api.neuria.tech/docs)
- **GitHub**: [https://github.com/kosukeuemura0220-del/neuria-agent](https://github.com/kosukeuemura0220-del/neuria-agent)

---

## License

MIT License — see [LICENSE](./LICENSE) for details.

---

<p align="center">
  <strong>NEURIA</strong> — Because AI-generated UI shouldn't look like AI-generated UI.
</p>