Skip to main content
Glama

mcp-uxhints

MCP (Model Context Protocol) server that exposes the uxhints.com catalog of bite-sized UX and product-design hints as MCP tools over stdio. Content comes from the site's public WordPress REST API (converted to clean Markdown), served through a local cache so tool calls are instant and work offline.

Prerequisite: Node.js 18 or newer. No build step — npx downloads and runs the published package, and the bundled catalog snapshot lets the first tool call work with zero network.

Register the server in your MCP client, then restart the client.

OpenCode

Add to opencode.json:

{
  "mcp": {
    "mcp-uxhints": {
      "type": "local",
      "command": ["npx", "-y", "mcp-uxhints"],
      "enabled": true
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-uxhints": {
      "command": "npx",
      "args": ["-y", "mcp-uxhints"]
    }
  }
}

Note: do not run npx mcp-uxhints from inside your own clone of this repository — npm resolves the local package.json and fails with command not found. Any other directory works.

Related MCP server: you-design-mcp

Install from source (alternative)

For development or pinning a local build:

git clone https://github.com/Mateodioev/mcp-uxhints.git
cd mcp-uxhints
npm install && npm run build

Then point your client at the built file instead of npx:

  • OpenCode: "command": ["node", "/absolute/path/mcp-uxhints/build/index.js"]

  • Claude Desktop: "command": "node", "args": ["/absolute/path/mcp-uxhints/build/index.js"]

Tools

Tool

What it does

list_categories

List all categories with slugs and hint counts.

list_hints

Paginated hint list, optionally filtered by category slug.

search_hints

Local search over title, excerpt and content; case- and diacritic-insensitive, title matches first.

get_hint

One hint by id or slug (exactly one), full content as Markdown.

random_hint

One random hint, full content as Markdown.

refresh_hint_catalog

Force a live sync and rewrite the local cache.

Typical flow: list_categories → list_hints → get_hint. Slugs never include the category prefix (occams-razor-law-in-ux-design, not ux-laws/occams-razor-law-in-ux-design).

Caching

Tool calls read from a local catalog cache (default TTL 24h) instead of hitting the API every time. Resolution order:

Layer

Location

Role

1. User cache

OS cache dir, catalog.json

Read first; refreshed when older than the TTL.

2. Bundled snapshot

catalog.snapshot.json inside the package

Ships fresh at publish time; seeds the user cache with zero network.

3. Live API

uxhints.com

Source of truth for refreshes; if it fails, stale caches are served with a notice in the output.

Not fresh? Call refresh_hint_catalog, or wait for the TTL to expire. A postinstall hook warms the user cache automatically when the bundled snapshot has expired since publish.

Env var

Default

Effect

UXHINTS_CACHE_TTL_HOURS

24

Hours a cached catalog counts as fresh (float; invalid values → 24).

UXHINTS_CACHE_DIR

OS cache dir¹

Override where catalog.json lives.

UXHINTS_NO_CACHE

unset

Set to 1 to bypass all caching and call the live API on every tool call.

¹ ~/.cache/mcp-uxhints on Linux (honors XDG_CACHE_HOME), ~/Library/Caches/mcp-uxhints on macOS, %LOCALAPPDATA%\mcp-uxhints\Cache on Windows.

Details

Topic

Notes

Data source

Public WordPress REST API of uxhints.com (/wp-json/wp/v2)

Content format

WordPress HTML → Markdown at sync time (block comments stripped, entities decoded)

Caching

3 layers: user cache → bundled snapshot → live API (see above)

Resilience

15 s request timeout; live failures fall back to stale caches; all failures surface as MCP tool errors, never crash the server

Scripts

npm run build (tsc), npm run sync:snapshot (regenerate the bundled snapshot), npm start (run the built server)

Credit

All content © uxhints.com by Paul Capcan. This server only wraps the site's public API; it does not host or modify the content.

Available Tools

6 tools
get_hintGet a hintA

Get one uxhints.com hint by id or slug (exactly one is required), with the full content already converted from WordPress HTML to clean Markdown. Results are served from a local catalog cache (default 24h TTL); call refresh_hint_catalog to force an update.

Inputs: id, slug.

list_categoriesList categoriesA

List the hint categories on uxhints.com with hint counts and the slugs to filter list_hints with. Results are served from a local catalog cache (default 24h TTL); call refresh_hint_catalog to force an update.

Inputs: no named parameters.

list_hintsList hintsA

List UX hints from uxhints.com (id, title, slug, link, date, categories), optionally filtered by a category slug from list_categories. Includes total/totalPages for pagination. Results are served from a local catalog cache (default 24h TTL); call refresh_hint_catalog to force an update.

Inputs: page, category, per_page.

random_hintGet a random hintA

Get one random hint from uxhints.com, same shape as get_hint: full content as Markdown. Results are served from a local catalog cache (default 24h TTL); call refresh_hint_catalog to force an update.

Inputs: no named parameters.

refresh_hint_catalogRefresh hint catalogA

Force a live sync of the uxhints.com catalog and rewrite the local cache, bypassing the TTL. Returns the new hint/category counts and fetch timestamp. On failure the existing caches stay untouched.

Inputs: no named parameters.

search_hintsSearch hintsA

Local search over the cached uxhints.com catalog: case-insensitive and diacritic-insensitive substring matching over hint titles, excerpts, and full Markdown content. Title matches rank before content matches. Same result shape and pagination as list_hints. Results are served from a local catalog cache (default 24h TTL); call refresh_hint_catalog to force an update.

Inputs: query (required), page, per_page.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: listing categories, listing hints with filters, searching, fetching a specific hint, retrieving a random hint, and refreshing the cache. There is no overlap in functionality; an agent can easily choose the correct tool based on intent.

    Naming Consistency4/5

    Tool names mostly follow a clear verb_noun pattern (list_, search_, get_, refresh_). 'random_hint' is a slight deviation since 'random' is not a verb, but it still reads as an imperative action and fits the overall snake_case convention. The inconsistency is minor.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a catalog browsing and retrieval service. Each tool serves a unique, essential function without redundancy or bloat. The count is ideal for the domain.

    Completeness5/5

    The tool set covers all common read operations: list all (with category filters), search, get by id/slug, and get random. The refresh tool handles cache maintenance. Since this is a read-only hint catalog, there are no missing CRUD operations; the surface is complete for its purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP gateway and offline catalog CLI that aggregates multiple upstream MCP servers into a single stdio endpoint, and provides tool recommendation and catalog inspection without connecting to upstreams.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-aware clients to query and use the you-design catalog of design systems, skills, and plugins at runtime via stdio.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients such as Claude, Claude Code and Cursor to keyword-search a directory of over 1,000 hand-picked productivity tools, apps, AI tools, courses and books, filtering by category, type, pricing and result limit, and to fetch a single listing by slug, page URL or exact name and list all categories with counts. It runs read-only over stdio with no API key, dependencies or tracking, making only a plain GET of the public catalogue.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to search, record, correct, and review the provenance and version history of memories, and to obtain answers composed from guarded context in which private values are replaced by placeholders and resolved locally on the device. Exposes these capabilities through dependency-free tools over stdio.
      MIT