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.

Install with npx (recommended)

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.

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.