Metadata-Version: 2.4
Name: vercel-templates-discovery
Version: 0.2.3
Summary: Agentic CLI for discovering and searching Vercel Templates
Project-URL: Homepage, https://github.com/imKXNNY/vercel-templates-discovery
Project-URL: Repository, https://github.com/imKXNNY/vercel-templates-discovery
Project-URL: Issues, https://github.com/imKXNNY/vercel-templates-discovery/issues
Author-email: Kenny <kenny@example.com>
License: MIT
Keywords: agentic,cli,discovery,scraping,templates,vercel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: fastapi>=0.110.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: responses>=0.25.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Requires-Dist: types-beautifulsoup4>=4.12.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.29.0; extra == 'dev'
Provides-Extra: server
Requires-Dist: fastapi>=0.110.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.29.0; extra == 'server'
Description-Content-Type: text/markdown

# Vercel Templates Discovery

> Agentic CLI for discovering, indexing, and searching [Vercel Templates](https://vercel.com/templates). No public API exists — this tool fills the gap for agents and developers who want a searchable, local catalog with install commands.

## Quick start (Python)

```bash
# Install from PyPI (once published)
pip install vercel-templates-discovery

# Or install locally for development
pip install -e ".[dev]"

# Or run via Docker
docker run --rm ghcr.io/imkxnnny/vercel-templates-discovery:latest vercel-templates --help

# Index the catalog
vercel-templates index

# 3. Search
vercel-templates search "AI chatbot"
vercel-templates search "ecommerce" --limit 3

# 4. Show details
vercel-templates show /templates/next.js/chatbot

# 5. Export to JSON
vercel-templates export --output templates.json
```

## Quick start (TypeScript / WSL)

```bash
# Install globally from npm (published)
npm install -g @imkxnny/vercel-templates-discovery

# Or work locally
cd ts
npm install

# Build once, or run via tsx
npm run build
npm run typecheck:all
npm test

# Index the catalog
npx tsx src/cli.ts index

# Search / show
npx tsx src/cli.ts search "AI chatbot" --json
npx tsx src/cli.ts show /templates/next.js/chatbot --json
```

## Why this exists

Vercel maintains a curated library of high-quality templates, but provides no SDK, CLI, or API for discovering them. This tool:

- Crawls the Vercel Templates gallery (~277 templates).
- Extracts metadata, GitHub URLs, and install commands.
- Stores everything in a local SQLite cache with full-text search.
- Exposes a simple CLI that agents can call or shell out to.

## Architecture

```text
vercel_templates/          # Python implementation
├── config.py              # categories, cache path, constants
├── scraper.py             # crawler + detail extractor + SQLite cache
└── cli.py                 # Typer CLI

ts/                        # TypeScript / Node implementation
├── src/
│   ├── scraper.ts         # crawler + detail extractor
│   ├── db.ts              # SQLite cache + FTS5 search
│   ├── cli.ts             # Commander CLI
│   ├── mcp-server.ts      # stdio JSON-RPC MCP server
│   └── index.ts           # library exports
├── tests/
│   └── scraper.test.ts    # vitest tests
└── package.json
```

The scraper uses `fetch` + `cheerio` + regex to parse Vercel's server-rendered pages and Next.js flight payloads. Because the catalog is small, the entire index can be rebuilt in under a minute.

## Commands

| Command | Description |
|---------|-------------|
| `index` | Crawl and index the full catalog |
| `search QUERY` | Full-text search over titles, descriptions, tags |
| `show SLUG` | Show full details for a template |
| `export` | Dump the indexed catalog to JSON |
| `stats` | Show framework/category counts |
| `serve` | Start the REST API server |

## REST API server

Run the server with:

```bash
vercel-templates serve
# or
vercel-templates serve --host 0.0.0.0 --port 8080
```

Endpoints:

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check |
| `GET /templates?q=...&limit=...` | Search or list templates |
| `GET /templates/{slug}` | Get one template by slug (e.g. `/templates/next.js/chatbot`) |
| `GET /categories` | List frameworks and use cases |

## Agentic usage

The CLI is designed to be easy for agents to consume:

```bash
# JSON output for downstream parsing
vercel-templates search "AI chatbot" --json
vercel-templates show /templates/next.js/chatbot --json
```

### MCP server

An MCP (Model Context Protocol) server is included for direct agent integration:

```bash
# Start the MCP server
python -m vercel_templates.mcp_server
# or
vercel-templates-mcp
```

Available tools:
- `search_templates(query, limit)` — search the catalog
- `get_template(slug)` — get full details for a template
- `list_categories()` — list available categories/frameworks

Example MCP client config (Claude Desktop / Cursor):

```json
{
  "mcpServers": {
    "vercel-templates": {
      "command": "python",
      "args": ["-m", "vercel_templates.mcp_server"]
    }
  }
}
```

### Hermes skill

A Hermes skill wrapper is provided under `skills/vercel-templates/`. Copy or symlink the skill into your Hermes profile's `skills/` directory:

```bash
# Windows native Hermes example
copy /Y skills\vercel-templates %LOCALAPPDATA%\hermes\skills\vercel-templates
# or Hermes profile path: ~/.hermes/profiles/default/skills/vercel-templates
```

The skill exposes the same three tools as the MCP server and can be used directly by Hermes agents.

## Project status

See [docs/PROJECT_PLAN.md](docs/PROJECT_PLAN.md) for the roadmap, milestones, and backlog.

## License

MIT
