terminal-love-mcp

license node MCP

MCP server over Terminal Trove — search the catalog and pullTUI/CLI design references (screenshots, demo GIFs, install commands, metadata) so an agentcan study real terminal UIs while building one.

Built for wiring into the Vanta agent, but works with any MCP client.

Why

Terminal Trove curates hundreds of CLI/TUI tools, each page carrying the gold you want whendesigning a terminal UI: real screenshots + demo GIFs, the GitHub repo, language, license,platform support, and copy-pasteable install commands. There's no public API, so this serverscrapes the (clean, stable) HTML and the site's Typesense search endpoint, caches politely todisk, and exposes everything as MCP tools — including returning screenshots as viewable imageblocks so the agent can actually see the layout.

Install

npm install
npm run build

Wire into Vanta (or any MCP client)

Add to your client's MCP config (e.g. .mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "terminal-love": {
      "command": "node",
      "args": ["/Users/jasonpoindexter/Documents/GitHub/_tools/terminal love mcp/dist/index.js"]
    }
  }
}

Optional env (all have sane defaults — see .env.example):

TTROVE_CACHE_DIR — where HTML/catalog cache lives (default: OS tmp)
TTROVE_CACHE_TTL_MS — cache lifetime (default 6h)
TTROVE_LOG_LEVEL — pino level (default info; logs go to stderr, never stdout)
GITHUB_TOKEN — raises the rate limit for get_repo_stats

Tools

Collection-returning tools share one shape: { count, items, ...context }(e.g. search_tools → { query, count, items }, browse_category → { category, count, items }).Single-entity tools (get_tool, get_repo_stats) return the object directly.

Tool	Input	Returns
`get_tool`	`slug`	Full details: description, GitHub, language, license, platforms, tags, install commands, screenshot URLs
`search_tools`	`query`, `limit?`	Live search results (Terminal Trove Typesense) as tool summaries
`related_tools`	`slug`, `limit?`	Tools sharing the input's primary category
`get_repo_stats`	`github_url?` \| `slug?`	GitHub stars/forks/issues/language/license/topics/pushedAt
`list_categories`	—	All 70+ categories (slug, name, url)
`browse_category`	`category`, `limit?`	Tools in a category (name + description)
`newly_added`	`limit?`	Recently added tools (`/new/`)
`tool_of_the_week`	—	Current pick + archive
`list_screenshots`	`slug`	Screenshot/GIF URLs + dimensions for a tool
`view_screenshot`	`slug?`+`index?` \| `url?`	The image itself as a base64 MCP image block (CDN-host allowlisted, 8 MB cap)
`sync_catalog`	`force?`	Build/refresh the full local catalog index from the sitemap
`search_catalog`	`query`, `limit?`	Offline fuzzy search across the whole catalog (after first sync)

Typical flow for Vanta

search_tools / search_catalog / browse_category → find candidate TUIs
get_tool → read structure, install, screenshot URLs
view_screenshot → actually see the layout to learn from
get_repo_stats → gauge maturity/popularity

Development

npm run dev        # run the server via tsx (stdio)
npm test           # vitest (parsers tested against saved HTML fixtures)
npm run typecheck
npm run smoke      # build + end-to-end stdio smoke test against the live site
npm run demo       # build + simulate the full Vanta research flow
npm run verify     # build + assert every tool against the LIVE site (drift guard, exits non-zero on failure)
npm run inspect    # open the MCP Inspector

Design notes

stdio transport — stdout is the JSON-RPC stream; all logging is forced to stderr.
Polite scraping — 6h disk cache, custom user-agent, retry-with-backoff, 15s timeout.
Pure parsers — all HTML parsing lives in pure functions tested against fixtures insrc/features/*/__fixtures__/, so a Terminal Trove markup change is caught by a failing test.
See DECISIONS.md for locked architectural choices and PARKED.md for deferred ideas.

terminal-love-mcp