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.