# uxspot MCP server

The UX reference your AI assistant can call — and now, the one that draws.

[uxspot.io](https://uxspot.io) is a free, curated UX reference: a 203-term glossary (every term with a plain-English definition and a "why it matters"), an AI x UX tools directory, 5 interactive checklists, a 78-topic Learn UX curriculum, and Spot Check, a daily UX vocabulary game. This repository documents the remote [Model Context Protocol](https://modelcontextprotocol.io) server that exposes all of it as callable tools for Claude, Cursor, and any other MCP client.

- **Endpoint:** `https://uxspot.io/mcp` — remote, Streamable HTTP, stateless
- **Landing page and live demo:** [uxspot.io/mcp-server](https://uxspot.io/mcp-server)
- **Auth:** none — no key, no account, no rate-limit signup
- **Privacy:** every tool is read-only over public uxspot.io content. The server never sees your project, files, or account.
- **Sibling project:** the [uxspot Figma plugin](https://github.com/dockster/uxspot-figma-plugin) — the same reference as a design mentor inside Figma, [live on Figma Community](https://www.figma.com/community/plugin/1667975729954963487).

## Install

**Claude Code**

```sh
claude mcp add --transport http uxspot https://uxspot.io/mcp
```

**Claude Desktop** — Settings → Connectors → Add custom connector, with URL `https://uxspot.io/mcp`.

**Cursor** — add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "uxspot": { "url": "https://uxspot.io/mcp" }
  }
}
```

**Gemini app (Spark)** — Settings → Connected apps → add a custom app, and paste `https://uxspot.io/mcp` as the URL (just the URL — the JSON below is Antigravity's format, not Spark's). If a credentials step appears under Advanced, leave it empty; uxspot never asks for a key.

**Gemini (Antigravity)** — the IDE and CLI that replaced Gemini CLI. Add to `~/.gemini/config/mcp_config.json`, then `/mcp` in the CLI to confirm:

```json
{
  "mcpServers": {
    "uxspot": { "serverUrl": "https://uxspot.io/mcp" }
  }
}
```

Gemini Enterprise is the one Gemini door that stays closed: it requires an admin-registered OAuth connector, and uxspot is keyless by design.

**Any other MCP client** that supports the Streamable HTTP transport: point it at `https://uxspot.io/mcp`.

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `search_glossary` | `query` | Matching UX terms with definitions and source URLs |
| `define_term` | `term` | One term in full: definition, why it matters, reference numbers, a terminal diagram for spatial concepts, and the source URL |
| `list_ux_tools` | `category?` | The curated AI x UX tools directory, optionally filtered |
| `list_checklists` | — | The 5 checklists with topic and item counts |
| `get_checklist` | `slug` | One checklist in full: every topic and item |
| `search_curriculum` | `query` | Matching Learn UX topics with HTML and Markdown URLs |
| `get_curriculum` | — | The full Learn UX syllabus outline |
| `spot_check` | — | One round of the Spot Check vocabulary game: a term, a definition that may or may not fit, the answer, and the explanation |

Every answer cites its uxspot.io source URL, so you (and your assistant) can verify it.

## What an answer looks like

`define_term("60-30-10")` returns, verbatim:

```
**60-30-10 rule**
A color-proportion guideline borrowed from interior design: roughly 60% of a
screen in a dominant, usually neutral color, 30% in a secondary color, and 10%
in an accent reserved for emphasis — enough color to guide the eye without
competing for it.

**Why it matters** — Screens that feel colorful but calm almost always follow
some version of this split. Inverting it — letting the accent become the
majority — is why loud interfaces feel loud: when everything asks for
attention with color, nothing gets it.

**The numbers**
- 60% — dominant, usually neutral
- 30% — secondary, supporting surfaces
- 10% — accent, reserved for emphasis and actions

┌────────────────────────────────────┐
│                                    │
│      60% — dominant, neutral       │
│                                    │
├─────────────────────────┬──────────┤
│    30% — secondary      │ 10%      │
│                         │ accent   │
└─────────────────────────┴──────────┘

Source: https://uxspot.io/glossary/60-30-10-rule
```

## The terminal diagrams

37 spatial concepts — proportion, position, hierarchy, flow — answer with hand-drawn box art: the Z-pattern's scan path, the information-architecture tree with its misfiled page, the journey map's emotional dip, the empathy map's quadrants, the modal punched through a dimmed page.

The set is deliberately bounded. Terms whose specimen needs **color** (contrast ratios, eye-tracking heat), **motion** (skeleton shimmer), or **interaction** (Fitts's law's timer, the Zeigarnik checklist) don't get a worse imitation — they point to their live interactive example on uxspot.io instead. And some things monospace physically cannot show: a kerning diagram in a terminal would be a lie about its own subject, since every glyph is the same width by definition.

Every diagram is hand-authored, never generated, in [`src/lib/glossaryAscii.ts`](src/lib/glossaryAscii.ts) — inspectable like everything else here, and the file records the full adjudication of what is drawn, what points to a live demo, and why.

## Try it

Ask your assistant things like:

- "What's the Z-pattern? Draw it."
- "What's an affordance in UX — and where can I read more?"
- "List AI tools for UX research"
- "Give me the accessibility checklist"
- "Search the curriculum for usability testing"
- "Quiz me on UX vocabulary" (runs Spot Check, round by round)

## How it is built

The server is a single Cloudflare Pages Function in front of the static uxspot.io site. Each POST is a complete JSON-RPC exchange (stateless Streamable HTTP — no sessions, no database), and the tools read the same structured data that powers the live site, so responses are always in sync with what is published. The tool descriptions even self-count from the data files, so the numbers above cannot drift.

The code in [`server/`](server/) and the diagram map in [`src/lib/`](src/lib/) are a read-only mirror of the deployed function, published here for transparency and for MCP directory listings. The source of truth lives in the main uxspot site repository; the data files the function imports (`glossary.json`, `tools.json`, `checklists.json`, `curriculum.ts`) live there too, so this mirror is for reading, not building.

## License

The server code in this repository is released under the [MIT License](LICENSE). The uxspot.io content the tools serve (definitions, checklists, curriculum) remains © Soufiane Chraibi and is licensed for use via the site and this API, not for bulk redistribution.