# For Agents

Stack Gems is designed to be consumed by LLMs, agents, and automated tools. Here is how to access the catalog programmatically.

HTML version: /for-agents

## MCP server (remote, read-only)

Connect any MCP client to the catalog. No key, no login, no session state.

- Endpoint: `https://stackgems.com/api/mcp` (alias `https://stackgems.com/mcp`), Streamable HTTP transport, JSON responses
- Discovery: [/.well-known/mcp.json](/.well-known/mcp.json) (also /.well-known/mcp/server-card.json)
- Tools (all read-only):
  - `search_gems(query?, tag?, subcategory?, category?, pricing?, sort?, limit?)` — search reviews, free/OSS first
  - `get_gem(slug)` — one full review with verdict, Catch, license, repo health, best-of list and alternatives
  - `best_for(use_case, limit?)` — ranked shortlist for a use case, e.g. "vector database", "self-hosted auth"
  - `get_alternatives(slug, limit?)` — free and open-source alternatives from the same category
  - `list_categories()` — stacks, best-of lists and the tag vocabulary with counts
- Limits: 120 requests per minute per IP, 64 KB request body

Client config (Claude Desktop, Cursor, VS Code and others that accept a remote URL):

```json
{
  "mcpServers": {
    "stackgems": { "url": "https://stackgems.com/api/mcp" }
  }
}
```

Clients that only speak stdio can bridge with `npx -y mcp-remote https://stackgems.com/api/mcp`.

Quick test:

```
curl -s https://stackgems.com/api/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"best_for","arguments":{"use_case":"vector database","limit":3}}}'
```

## OpenAPI

[/openapi.json](/openapi.json) describes the JSON API (OpenAPI 3.1).

## Best-of lists, tags and alternatives

- `/best` — index of 55 best-of lists, one per category with at least four reviewed tools (`/best/{subcategory}`, e.g. /best/coding-agents, /best/vector)
- `/alternatives/{slug}` — free and open-source alternatives for 321 tools, e.g. /alternatives/cursor
- `/tag` — index of tag hubs (`/tag/{tag}`, e.g. /tag/mcp, /tag/local-llm)
- `/new` — tools added in the last 7 and 30 days
- Feeds: /feed.xml (newest gems), /log/feed.xml (log posts)

## llms.txt

Following the [llmstxt.org](https://llmstxt.org) specification, we provide structured text files for LLM consumption:

- [/llms.txt](/llms.txt) — Index of all gems with links
- [/llms-full.txt](/llms-full.txt) — Complete catalog with full reviews

## JSON API

RESTful JSON endpoints with CORS enabled for cross-origin requests:

### [GET /api/gems](/api/gems)

List all gems. With no parameters you get the full catalog in curated order, free first: open-source, free and OSS-core tools, then hosted products with a real free tier, then paid-only, paid-led and archived tools (catalog order kept inside each group; each gem carries `access`: free | free-tier | paid-led). The response shape is the same as always; new fields are only added. Use `?sort=catalog` for the old raw order. Optional query parameters:

- `?category=agents` — filter by category (agents, nextjs, python, shopify, databases, devops, design, observability, rust, payments, comms, notifications, libraries)
- `?domain=ai-agents` — filter by domain (slug or label)
- `?subcategory=coding-agents` — filter by subcategory (finer than subSpecialty; slug or label)
- `?tag=mcp,self-host` — filter by tags, all must match (comma or repeated `tag=`). Vocabulary: `?facets=1` returns every tag with group, description and count
- `?license=apache-2.0` · `?pricing=open-source` · `?surface=mcp` · `?ecosystem=python` — comma lists, case-insensitive
- `?q=postgres` — search name, tagline, hook, verdict, catch, subcategory and tags (`?search=` keeps the old name/tagline/hook match)
- `?sort=curated|catalog|new|stars|trending|name` — default `curated` (free first, see above). `catalog` = the old raw catalog order, kept for backward compatibility. `new` = addedAt desc, `stars` = GitHub stars, `trending` = lifetime stars per week (stars ÷ weeks since repo creation; young repos and inflated counts float up, so read the Catch), `name` = A–Z
- `?limit=50&offset=0` — pagination (limit max 1000). `meta.next` holds the next page URL
- `?facets=1` — adds `meta.subcategories` (domain, subcategory, slug, count) and `meta.tags` (slug, label, group, description, count)

Each gem carries `subcategory`, `tags`, `githubStars`, `starsPerWeek` and `repo` (createdAt, pushedAt, license SPDX id, archived, checkedAt) next to the review fields. Unknown `sort` or `tag` values return 400 with the allowed list.

Examples:

- `/api/gems?tag=mcp,self-host&sort=stars&limit=20` — top self-hostable MCP tools by stars
- `/api/gems?subcategory=coding-agents&tag=permissive` — permissively licensed coding agents
- `/api/gems?sort=new&limit=10` — the ten latest reviews

### GET /api/gems/[slug]

Get a single gem with full details and related gems

### [GET /api/tools](/api/tools)

Alias of /api/gems. Same filters, sorts and payload plus `type: "tool"`. CORS * GET OPTIONS. /api/gems stays.

### GET /api/stacks

List all categories with gem counts and featured items

## Badges

Free embeddable SVG. Not a paid slot. Canonical path is /badge/[slug].svg.

```
[![Reviewed on Stack Gems](https://stackgems.com/badge/{slug}.svg)](https://stackgems.com/gems/{slug})
```

- `/badge/tool.svg` — generic mark
- `/badge/phaser.svg` — gem mark
- `/badge/skill/[id].svg` — skill mark

## Programmatic landings

Generated only when at least two reviewed tools overlap after enrichGem. Honest Catch lists, not rankings. Empty combinations 404.

- `/tag/[capability]` — e.g. /tag/webgpu, /tag/mcp
- `/best/[sub-specialty]-for-[ecosystem]` — e.g. /best/game-engines-for-browser
- `/compare/[slug-a]-vs-[slug-b]` — e.g. /compare/phaser-vs-pixijs, /compare/cursor-vs-claude-code
- `/discover/[niche]` — curated hubs e.g. /discover/codebase-context-engines, /discover/local-vector-stores

## Crawlers

All search engines, AI search crawlers and agent fetchers are allowed in /robots.txt (Googlebot, Bingbot, GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, Claude-SearchBot, PerplexityBot, Perplexity-User, Applebot, Google-Extended and more). No login, no API key, no rate-limit tier. Please cache: list responses change at most a few times a day.

## Raw Markdown

Every gem review is available as plain markdown:

```
/gems/[slug].md
```

Example: [/gems/cursor.md](/gems/cursor.md)

## Skills

527 skill reviews, not a dump. HTML index, JSON, and raw markdown:

- [/skills](/skills) — HTML index of every skill
- [/api/skills](/api/skills) — JSON list
- [/skills/skill-creator.md](/skills/skill-creator.md) — One markdown review

## Review queue

Agents can submit a review of a skill or a gem. Submissions are queued. Nothing is auto-published. Same human veto as POST /api/submit.

```
POST /api/reviews
Content-Type: application/json

{
  "targetType": "skill",
  "slug": "systematic-debugging",
  "body": "At least twenty characters of review text...",
  "by": "optional-name"
}

// targetType: skill | gem
// Returns 202. Does not render on the page.
// 409 if the same review is already queued, 413 over 8 KB, 429 over 20/hour per IP.
```

## RSS Feed

Subscribe to new gems via RSS:

```
/feed.xml
```

## Submit a Gem

Agents and tools can submit gem suggestions via API:

```
POST /api/submit
Content-Type: application/json

{
  "name": "Tool Name",
  "url": "https://example.com",
  "stack": "agents",
  "why": "At least 20 chars: what it is and when useful...",
  "kind": "gem",
  "tagline": "One-line what it is",
  "catch": "Honest catch / gotcha",
  "surfaces": ["MCP", "CLI", "API"],
  "github": "https://github.com/org/repo",
  "license": "Apache-2.0",
  "agent": "your-agent-name"
}

// Required: name, url, stack, why (≥20 chars)
// Optional packet: kind, tagline, catch, surfaces, github, license, sourceUrl, when, agent
// surfaces: MCP | CLI | API | SDK | Self-host | Hosted
// Valid stacks: agents, nextjs, python, shopify, databases, devops, design, observability, rust, payments, comms, notifications, libraries
// Queued only — human veto, never auto-publish.
// 409 if the URL is already queued (response has the existing id), 413 over 8 KB, 429 over 10/hour or 30/day per IP.
```

Prefer a full review packet so we can check and ship faster. Still no auto-publish.

## Sitemap

Complete sitemap including all pages and markdown files: [/sitemap.xml](/sitemap.xml)

## Current Catalog

- Total gems: 927
- Skills: 527
- Categories: 13
- Updates: Daily