starcat-recommend-api

Self-hostable support API for Starcat similar-repository recommendations.

Starcat is a native macOS app that turns GitHub Stars into a searchable, organized and AI-assisted knowledge base. It supports README rendering, tags, private notes, release tracking, repository health signals, AI summaries, semantic search, browser plugin workflows and self-hostable support APIs.

_中文说明

Preferred install method:

brew tap starcat-app/starcat
brew trust starcat-app/starcat
brew install --cask starcat

Useful links:

• Home and downloads: https://starcat.ink
• Public support and release notes: https://github.com/starcat-app/starcat-pro
• Starcat App Homebrew tap: https://github.com/starcat-app/homebrew-starcat
• CLI / MCP: starcat-cli / Homebrew tap
• AI Agent Skill: https://github.com/starcat-app/starcat-skill
• Browser plugins: Chrome / Safari
• Localization: https://github.com/starcat-app/starcat-localization

Self-hostable support APIs:

• starcat-sharing-api
• starcat-trending-api
• starcat-weekly-api
• starcat-wiki-api
• starcat-recommend-api
• starcat-discovery-api

Starcat provides hosted defaults for normal users. This API is open source so advanced users can inspect it, run it locally, or deploy their own instance.

Backend service for Starcat similar-repository recommendations.

The initial version proxies SimRepo's unofficial Qdrant Recommend API through the server, providing the Starcat macOS client with a stable /api/v1/repos/{repo_id}/recommendations contract. The client neither connects directly to SimRepo nor stores a SimRepo key. The provider can later be replaced within this service by Starcat's own recommendation provider.

Endpoints

Method	Path	Auth	Description
GET	/healthz	No	Process health check
GET	/api/v1/ping	Yes	Starcat client connectivity probe
GET	/api/v1/repos/{repo_id}/recommendations?limit=10&offset=0	Yes	Similar repository recommendations

The authenticated ping response includes the service identity and the build version injected from the release tag:

{"schema_version":1,"data":{"service":"recommend","version":"1.2.3","ok":true}}

Environment

cp .env.example .env

Required:

• API_KEYS: comma-separated Bearer tokens accepted by Starcat clients.
• SIMREPO_API_KEY: SimRepo Qdrant read-only key. Keep it server-side only.

Optional:

• PORT: defaults to 5005.
• SIMREPO_ENDPOINT: defaults to SimRepo's Qdrant recommend endpoint.
• CACHE_TTL_SUCCESS_SECONDS: defaults to 7 days.
• CACHE_TTL_EMPTY_SECONDS: defaults to 1 hour.
• CACHE_TTL_ERROR_SECONDS: defaults to 10 minutes.

Local Development

go mod tidy
go run ./cmd/server

Smoke test:

curl http://127.0.0.1:5005/healthz
curl -H "Authorization: Bearer $API_KEY" http://127.0.0.1:5005/api/v1/ping
curl -H "Authorization: Bearer $API_KEY" \
  "http://127.0.0.1:5005/api/v1/repos/41881900/recommendations?limit=10&offset=0"

Quality Gates

go test ./...
go test -race ./...
go vet ./...
go build ./...

Provider Boundary

The current provider chain is:

RecommendHandler -> CachedProvider -> SimRepoProvider -> SimRepo Qdrant API

CachedProvider keeps at most 10,000 repoID:limit:offset entries. Expired entries are removed on read; when capacity is reached, the entry with the earliest expiry is evicted.

Future providers should keep the response DTO stable:

ContentEmbeddingProvider
StarcatBehaviorProvider
HybridProvider