mcp-uxhints
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-uxhints search hints for empty states"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-uxhintsfrom inside your own clone of this repository — npm resolves the localpackage.jsonand fails withcommand 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 buildThen 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 all categories with slugs and hint counts. |
| Paginated hint list, optionally filtered by category slug. |
| Local search over title, excerpt and content; case- and diacritic-insensitive, title matches first. |
| One hint by |
| One random hint, full content as Markdown. |
| 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, | Read first; refreshed when older than the TTL. |
2. Bundled snapshot |
| Ships fresh at publish time; seeds the user cache with zero network. |
3. Live API |
| 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 |
|
| Hours a cached catalog counts as fresh (float; invalid values → 24). |
| OS cache dir¹ | Override where |
| unset | Set to |
¹ ~/.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 ( |
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 |
|
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 toolsget_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Remote MCP for JSON repair, hashing, formatting, IDs, dates, units, and other small tools.
Hacker News MCP — search and retrieve stories from Hacker News
Unofficial UMLS MCP — wraps the NLM UMLS Terminology Services REST API (uts-ws.nlm.nih.gov/rest)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseNot gradedqualityCmaintenanceEnables MCP-aware clients to query and use the you-design catalog of design systems, skills, and plugins at runtime via stdio.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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