terminal-love-mcp

MCP server over Terminal Trove — search the catalog and pull TUI/CLI design references (screenshots, demo GIFs, install commands, metadata) so an agent can 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 when designing 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 server scrapes the (clean, stable) HTML and the site's Typesense search endpoint, caches politely to disk, and exposes everything as MCP tools — including returning screenshots as viewable image blocks 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

1. search_tools / search_catalog / browse_category → find candidate TUIs
2. get_tool → read structure, install, screenshot URLs
3. view_screenshot → actually see the layout to learn from
4. 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 in src/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.