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.

Related MCP server: mcp-cli-catalog

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 — tool-page/catalog cache lifetime (default 6h)

• TTROVE_SEARCH_TTL_MS — search-response cache lifetime (default 1h; fresher than pages)

• TTROVE_LOG_LEVEL — pino level (default info; logs go to stderr, never stdout)

• GITHUB_TOKEN — raises the rate limit for get_repo_stats / get_tool with_stars

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.

Resources

Tool pages are also exposed as MCP resources, so a client can read a tool's structured JSON by URI without spending a tool call:

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.