# Awesome Go package discovery

> A reviewed starter catalog for choosing Go packages using explicit requirements and dated evidence.

- [Agent guide](/agents): JSON and MCP usage.
- [OpenAPI](/openapi.json): Exact REST parameters and response fields.
- [Selection UI](/choose): Filters and two-to-four package comparisons.
- [Agent skill](/skills/awesome-go-discovery/SKILL.md): Downloadable instructions for evidence-based package selection.

## Read-only JSON API

GET /api/v1/packages?category=logging&verifiedOnly=false&limit=5
GET /api/v1/packages/{id}
GET /api/v1/compare?ids={id1},{id2}
GET /api/v1/examples/{id} (package catalog ID)

Search and comparison accept q, category, goVersion, cgo (any|none), platforms
(comma-separated linux,windows), license (any|permissive), capabilities
(comma-separated identifiers), verifiedOnly (true|false), limit (1..20).
Comparison requires two to four distinct IDs. Unknown and repeated keys fail.
Discover valid IDs through search. Unknown resources return 404.
verifiedOnly=true requires a current, version-matched compiled example and
excludes search candidates with any unknown evidence reported by the engine,
including advisory status, even when no related requirement was selected.
Known advisory records also leave reachability unknown. Comparisons retain the
requested packages and show their conflicts and unknowns under the same filters.

## MCP

Connect a Streamable HTTP MCP client to /api/mcp on this site's origin.
The official SDK serves a stateless JSON transport with initialization and four
tools: search_packages, get_package, compare_packages, get_example. No token.
Search tool arguments match REST filters with real booleans, arrays and integers.
Comparison takes ids as an array plus filters. Detail/example tools take id.
Tool outputs contain structuredContent plus equivalent JSON text. Invalid inputs
and missing resources produce tool errors. No arbitrary URL fetch or writes.
POST only; bodies must be application/json and at most 16 KiB. GET and DELETE
are unsupported. Browser Origin must match the configured public site origin.
Requests are rate limited per server process (120/minute per socket address),
with at most 5000 active limiter entries. Behind a proxy, ingress should enforce
per-client limits. HTTP 429 includes Retry-After: 60. URLs are limited to 4 KiB.

## Evidence boundaries

Coverage: HTTP routing, database access, logging, CLI frameworks, configuration.
This starter catalog supplements the full directory. It is not comprehensive.
Responses explain matches, conflicts, unknowns and excluded candidates. Scores
represent deterministic requirement relevance, not an overall quality ranking.
Use metadata dates and source URLs; missing or stale facts remain unknown.
metadata.freshness is current only when fetchedAt is within the last 30 days;
otherwise it is stale. Package and example details apply the same freshness
policy as search: expired advisory checks become unknown, and expired or
version-mismatched compilation becomes unchecked, with an explanatory reason.
Historical observations and timestamps are retained for review.
An unreviewed capability is unknown; only a reviewed unsupported capability is
a conflict. Dependency records come from the recorded go.mod Require entries,
including declared indirect and test dependencies. They are not a full resolved
dependency graph from deps.dev.
Compilation verifies only the displayed snippet and recorded target/compiler.
It does not verify every feature, production readiness or vulnerability reachability.
Version-specific advisory checks are not a guarantee that software is safe.