# Reported issues for Releases

Pod holds 22 of 88 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Releases](/mcp/releases).

## Most discussed

### Source kind enum — Phase B (CLI) + post-merge tracking

Tracks the Phase B work that lands after the Phase A PR (`source-kind-plan`) merges and the package bumps publish to npm.

## Background

Phase A added a nullable `kind` enum on `products` and `sources` with read/write/filter wiring across the API + MCP. See [the Phase A PR](#) and `docs/superpowers/plans/2026-05-19-source-kind-enum.md` for the design.

**Kind values:** `platform | sdk | mobile | desktop | docs | integration | tool` — defined in `@buildinternet/releases-core/kinds`.

**Resolutio

[Read the thread](https://github.com/buildinternet/releases/issues/1080) · 2026-05-19 · closed · 6 comments

### Finish OpenAPI 3.1 spec coverage + validator middleware + CI gate

## Goal

Bring the OpenAPI 3.1 spec at [`GET /v1/openapi.json`](https://api.releases.sh/v1/openapi.json) — and the Scalar reference UI at [`/v1/docs`](https://api.releases.sh/v1/docs) — to "shippable as the public API reference." Today the plumbing from #750 is live, but only **3 of 32 route files** (`orgs.ts`, `sources.ts`, `products.ts`) carry `describeRoute(...)` annotations. Everything else is silently absent from the spec.

Pair the spec with public discoverability via [RFC 9727 (`/.well-kn

[Read the thread](https://github.com/buildinternet/releases/issues/894) · 2026-05-12 · closed · 5 comments

### Instrument agent/API consumption + define a demand north-star metric

## Summary

Instrument the **consumer-demand** side of the product and pick a north-star metric for it. Today the only usage instrumentation measures **our** costs and surfaces, not consumer demand:

- `usage_log` (`workers/api/src/routes/status.ts`) — *our* AI token spend per source/operation.
- `search_queries` — web search log (~16/day, per project notes).
- `telemetry_events` — CLI command names (deliberately PII-clean for the OSS contract).

There is no unified view of **who is consuming th

[Read the thread](https://github.com/buildinternet/releases/issues/1700) · 2026-06-20 · closed · 4 comments

### Umbrella: webhook delivery post-v1 follow-ups (#343)

## Context

Webhook delivery v1 (#343, closed) shipped almost the entire design: the consumer worker (`workers/webhooks/`), publisher fan-out (`workers/api/src/webhooks/`), `webhook-delivery` + `webhook-dlq` queues, master-derived HMAC signing, per-sub rate limiting, auto-disable, the 7-day replay endpoint, Analytics Engine telemetry, the API CRUD/`rotate-secret`/`test`/`deliveries` routes, `docs/webhooks.md`, the `releases webhook verify` CLI, and an (unspecced) email-alerting subsystem. The we

[Read the thread](https://github.com/buildinternet/releases/issues/1508) · 2026-06-08 · open · 4 comments

### Weekly agent sandbox: compiled CLI can't traverse TLS-intercepting proxy — curl fallback shipped, CLI/MCP follow-ups

## Context

The weekly scheduled maintenance routine (a sandboxed cloud agent) runs behind a **TLS-intercepting egress proxy**. The compiled `releases` CLI (a `bun build --compile` binary) cannot complete API requests there:

- Environment verified: CLI `0.73.0 (bun 1.3.13, linux-x64)`; proxy CA readable at `/root/.ccr/ca-bundle.crt`.
- Setting `NODE_EXTRA_CA_CERTS` / `SSL_CERT_FILE` / `NODE_USE_SYSTEM_CA=1` does **not** fix it. The error is `socket connection was closed unexpectedly`, **not** a

[Read the thread](https://github.com/buildinternet/releases/issues/2163) · 2026-07-23 · open · 3 comments

### Consolidate MCP and custom agent tools; add tool-UX evals

## Context

Anthropic published [Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents) — core argument: consolidate related operations into purpose-driven tools, treat tool descriptions like onboarding docs, drive iteration with evals.

Our current surface has some low-friction wins:

- **MCP read surface (14 tools):** four separate `list_*` tools + `search_registry` all answer "find entities." `get_organization` forces a second round-trip to `get

[Read the thread](https://github.com/buildinternet/releases/issues/459) · 2026-04-21 · closed · 3 comments

### webhooks: Phase B self-service subscriptions (identity blocker now resolved)

Part of the webhook delivery post-v1 follow-ups (parent #343, now closed). **Closed — Phase B shipped** (MCP deferred to #1678).

## Context

The original webhook design (#343) deferred Phase B solely because no first-party user identity layer existed. That blocker is resolved (Better Auth, `relu_` user keys, OAuth/roles).

## Resolved design decisions

| Question | Decision |
| -------- | -------- |
| **Ownership** | `webhook_subscriptions.user_id` — user-owned rows for self-serve; admin-provis

[Read the thread](https://github.com/buildinternet/releases/issues/1506) · 2026-06-08 · closed · 2 comments

### OAuth provider sub-project 5: MCP + REST resource-server JWT verification

OAuth "Sign in with Releases" **sub-project 5 of 5**: accept the AS's JWT access tokens as a resource server on the MCP + REST surfaces.

## Context

- The AS (#1479) issues JWT access tokens (JWKS at `/api/auth/jwks`) carrying `scope` and a `https://releases.sh/role` claim (#1480).
- Nothing currently *consumes* those tokens — the MCP worker and the REST API still authenticate via the existing `relk_`/`relu_`/static key lanes. This sub-project makes them verify and honor the OAuth JWTs so a "Si

[Read the thread](https://github.com/buildinternet/releases/issues/1483) · 2026-06-07 · closed · 2 comments

## Most recent

### chore(mcp): keep the registry listing in lockstep with the hosted server

The official listing `sh.releases/mcp` is already live. Version bumps are still a manual two-file edit, and a few fields that clients read from the registry never made it into `workers/mcp/server.json`. Sibling work on uploads.sh (buildinternet/uploads #854 / #855) is a concrete pattern to copy, without changing the remote-only listing or the "publish when `server.json` changes" deploy job.

## Problem

Three version numbers exist. Only two are supposed to agree:

- `workers/mcp/server.json` `ve

[Read the thread](https://github.com/buildinternet/releases/issues/2247) · 2026-08-26 · open · 0 comments

### chore(mcp): adopt MCP spec 2026-07-28 and TypeScript SDK v2

MCP spec `2026-07-28` shipped alongside the stable v2 TypeScript SDK (`@modelcontextprotocol/server@2.0.0`, `@modelcontextprotocol/client@2.0.0`); the monolithic `@modelcontextprotocol/sdk` is retired at v1. This tracks adopting it across our MCP surface. Sibling work in `buildinternet/sunny`: [#773](https://github.com/buildinternet/sunny/issues/773), Phase-1 PR [#774](https://github.com/buildinternet/sunny/pull/774).

Design doc: `docs/superpowers/specs/2026-07-29-mcp-sdk-v2-design.md`.

## Whe

[Read the thread](https://github.com/buildinternet/releases/issues/2189) · 2026-07-29 · open · 1 comment

### Evaluate enabling Workers Cache on workers/mcp + workers/webhooks (with the fail-closed pattern)

#1984 enabled Workers Cache only on `workers/api`. The other workers still run every request through the isolate:

- **`workers/mcp`**: serves cacheable GET surfaces — `/.well-known/*` (OAuth protected-resource metadata), the landing/docs responses (already set `Cache-Control: public` headers at `src/index.ts:26,83` and `well-known.ts:74`). MCP tool traffic itself is POST/SSE and wouldn't be affected (only GET/HEAD are cached). The KV `mcpread:v1` read-through (`lib/read-cache.ts`) stays regardl

[Read the thread](https://github.com/buildinternet/releases/issues/1990) · 2026-07-07 · closed · 1 comment

### Adopt slugged webUrl on remaining surfaces: MCP, feeds, webhooks, digest emails

#1905 shipped friendly release URLs (`/release/rel_<id>-<slug>`) with `webUrl` on the REST detail and latest-list responses. The remaining read surfaces were deliberately deferred and still emit bare-ID links (which work — they 308 to canonical — but skip the crawler/AI-legibility benefit of the slugged form).

## Surfaces to adopt

- **MCP** (`workers/mcp/`): `get_release`, `get_latest_releases`, `whats_changed`, `get_personalized_feed`, collection releases — include `webUrl` in tool results. N

[Read the thread](https://github.com/buildinternet/releases/issues/1906) · 2026-07-04 · closed · 1 comment

### @releases/design-system: post-Phase-2 polish (named prop exports, build-dep lockfile)

## @releases/design-system — post-Phase-2 polish

Low-priority cleanup carried over from #1765 (parity guard), deferred during Phase 1/2 as non-blocking. Now that Phase 2 (#1764, merged in #1768) makes the web app consume the package, these are worth tidying — but neither is urgent.

### 1. Named `XxxProps` exports for the inline-prop components
9 of the package's components export a named `XxxProps` interface (`ButtonProps`, `InputProps`, …); 7 still use inline anonymous prop types: `Aside`, `S

[Read the thread](https://github.com/buildinternet/releases/issues/1769) · 2026-06-25 · closed · 0 comments

### Workspaces: public REST/CLI/MCP surface (/v1/workspaces)

Follow-up to #1740 (Workspaces foundation; tracking #1739).

The foundation drives Better Auth's `/api/auth/organization/*` endpoints from the **web client only**. There's intentionally no first-party public surface yet.

## Build
- `/v1/workspaces` REST surface for the authenticated **user** principal (session / `relu_` / OAuth JWT — same gate as follows/webhooks, NOT `relk_`/root/anonymous): list, create, get, set-active.
- CLI: `releases workspace {list,create,switch}` (writes under `releases

[Read the thread](https://github.com/buildinternet/releases/issues/1742) · 2026-06-24 · open · 0 comments

### GET /v1/tokens/me 401s for OAuth-JWT principals (no oauth_ branch)

## Summary

`GET /v1/tokens/me` returns **401** for a valid "Sign in with Releases" OAuth-JWT bearer, even though the same token authenticates and authorizes normally on every other route. The handler has no `oauth_` branch — it assumes a `token`-kind identity is DB-backed.

## Detail

`resolveAuthUncached` maps a verified OAuth JWT to `{ kind: "token", tokenId: "oauth_<sub>", scopes }` (`workers/api/src/middleware/auth.ts`). The `/tokens/me` handler (`workers/api/src/routes/api-tokens.ts`) bran

[Read the thread](https://github.com/buildinternet/releases/issues/1733) · 2026-06-23 · closed · 0 comments

### Attribute internal/system callers in consumption + rate-limit telemetry (segment internal demand, speed triage)

## Problem

All internal traffic that uses the shared static root key (`RELEASES_API_KEY`) surfaces in telemetry as a single, undifferentiated `principal: root, audience: internal` bucket. We can't distinguish, among internal callers:

- managed **worker** agents (source fetch/update sessions)
- the managed **discovery** coordinator
- the **discovery worker** (Cloudflare) executing on behalf of agents
- **cron** jobs (poll-fetch, staleness, digests, …)
- **MCP → API** internal service-binding ca

[Read the thread](https://github.com/buildinternet/releases/issues/1731) · 2026-06-23 · open · 0 comments

### MCP relu_ keys bucket per-key, not per-account (rate-limit tier) — expose userId from /v1/tokens/me

## Problem

The account rate-limit tier (#1726) buckets on the **userId** so all of an account's credentials share one 300/min budget — the account is the unit being gated. This holds on the API worker (OAuth strips the `oauth_` prefix → `<sub>` = userId; `relu_` keys bucket on the resolved `userId`).

**Exception:** on the **MCP worker**, `relu_` user keys bucket **per-key** (`relu_<keyId>`), not per-account. MCP resolves identity by introspecting `GET /v1/tokens/me` over the service binding, a

[Read the thread](https://github.com/buildinternet/releases/issues/1729) · 2026-06-23 · closed · 0 comments

### Auth brute-force rate limiter is D1-backed — write-amplification DoS risk under distributed attack

## Problem

Better Auth's brute-force rate limiting for `/api/auth/*` is **D1-backed** (`rateLimit: { storage: "database" }` in `workers/api/src/auth/index.ts:1403-1405`), keyed per-row in the `rate_limit` table. This means **every tracked auth attempt incurs a D1 read + write** (upsert the counter for that key).

That turns the protection mechanism into a database write-amplification vector: a distributed brute-force or credential-stuffing attack against the sign-in / register endpoints drives 

[Read the thread](https://github.com/buildinternet/releases/issues/1728) · 2026-06-23 · closed · 0 comments

### Add dev-vars example templates for workers/{mcp,discovery,webhooks} (post-#1655)

## Context

Follow-up from PR #1655 (advisor audit). Plan 004 added a checked-in `workers/api/.dev.vars.example` template (the `.dev.vars` file is git-ignored, so fresh clones previously had no enumeration of the worker secrets needed to run `dev:api`). That plan scoped to `workers/api` and deferred the sibling workers.

The other three workers each have a real, git-ignored `.dev.vars` with no checked-in example: `workers/mcp`, `workers/discovery`, `workers/webhooks`.

## Proposal

For each work

[Read the thread](https://github.com/buildinternet/releases/issues/1657) · 2026-06-18 · closed · 0 comments

### Roll out extract-toolloop for large-body sources (cost win, flag-gated, never enabled)

## Context

Surfaced by an `/improve` audit (2026-06-18, commit `dc75b91c`). The two-tier extraction path (`extractFromBody()` → one-shot for ≤50K-token bodies, multi-round tool-use loop for larger) exists and is gated behind `extract-toolloop-enabled` / per-source `metadata.extractStrategy = "toolloop"` (see `docs/architecture/extract.md`, `packages/adapters/src/extract/extract-with-tools.ts`). The tool-loop pulls body slices on demand and is documented as a token-cost win on monolithic JSON/HT

[Read the thread](https://github.com/buildinternet/releases/issues/1653) · 2026-06-18 · closed · 1 comment

### MCP search: adopt @releases/lib/entity-match for entity hits (parity with /v1/search relevance)

#1583 fixed `/v1/search`'s entity sections: the `LIKE %q%` candidate fetch is now post-filtered and ranked in TS by `@releases/lib/entity-match` (camel-aware word boundaries, TLD-never-matches domain matching, tiered ranking exact > name prefix > name word > slug/domain/URL > category). The MCP worker's `search` tool was deliberately left out of that PR.

MCP still runs its own inline entity SQL in `workers/mcp/src/tools.ts` — raw substring `likeContains` matching ordered by name:

- orgs: ~line

[Read the thread](https://github.com/buildinternet/releases/issues/1587) · 2026-06-11 · closed · 0 comments

### Surface hosted-video links (Wistia/Loom/etc.) in release bodies as thumbnail/embed

## Summary

Release bodies sometimes contain links to **hosted video** (Wistia, Loom, Vimeo, YouTube, etc.) that currently render as a plain text link — easy to miss and not very accessible. We should detect well-known video-embed providers in release content and surface a **preview thumbnail** (ideally mirrored to R2 like other media) and/or an inline embed.

## Concrete example

Robin's "May 2026 Product Update" (`rel_VEZGMd94SgSB5zNqCoSgM`) has, inline in its markdown body:

```
[Video](https

[Read the thread](https://github.com/buildinternet/releases/issues/1549) · 2026-06-09 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/buildinternet/releases/issues).