# terminal-love-mcp

![license](https://img.shields.io/badge/license-MIT-blue) ![node](https://img.shields.io/badge/node-%3E%3D20-green) ![MCP](https://img.shields.io/badge/MCP-stdio-purple)

MCP server over [Terminal Trove](https://terminaltrove.com) — 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

```bash
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`):

```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.

| Tool | Input | Returns |
|---|---|---|
| `get_tool` | `slug`, `with_stars?` | Full details: description, GitHub, language, license, platforms, tags, install commands, screenshot URLs (+ GitHub `stars` when `with_stars`) |
| `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) |

## 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:

| Resource | URI | Returns |
|---|---|---|
| Terminal Trove tool | `terminaltrove://tool/{slug}` | The same JSON as `get_tool` (`application/json`), backed by the same cached fetch + parser |

### 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

```bash
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.