---
summary: Landing page + SEP-1649 Server Card at /, unified server manifest, directory-based changelog system
breaking: false
---

# 0.6.0 — 2026-04-21

Every HTTP-mode mcp-ts-core server now serves three coordinated surfaces from a single manifest: an HTML landing page at `/`, a SEP-1649 Server Card at `/.well-known/mcp.json`, and the existing `/mcp` status JSON. Zero config required — manifest values flow from `AppConfig`, the definition registries, and `package.json`; optional `landing` config tunes the hero, footer, and brand accent. A new directory-based changelog replaces the monolithic `CHANGELOG.md` with one file per release so agents can read only the versions between old and new.

Closes [#38](https://github.com/cyanheads/mcp-ts-core/issues/38). Deferred polish items (OG image, inspector deep link, sticky ToC, startup timestamp) remain tracked in [#39](https://github.com/cyanheads/mcp-ts-core/issues/39).

## Added

- **HTML landing page at `/`** (`src/mcp-server/transports/http/landing-page.ts`) — self-contained HTML with inlined tokens + primitives (shadcn-inspired), dark mode via `prefers-color-scheme`, zero external assets, <1KB inline JS for clipboard copy. Hero renders server name + clickable version badge + pre-release pill + tagline + auth-status banner + connect snippets (Claude Desktop, `mcp-remote`, `curl`). Sections for Tools/Resources/Prompts with per-definition cards (schema `<details>`, JSON-RPC invocation snippet, "view source" links when `repoRoot` is set). Auto-polish from detected signals: GitHub link cluster, npm/Docker registry links, tool name grouping by shared prefix, section counts. OpenGraph + JSON-LD in `<head>` and `<link rel="alternate">` pointing at the Server Card.
- **SEP-1649 Server Card at `/.well-known/mcp.json`** (`src/mcp-server/transports/http/serverCard.ts`) — machine-readable discovery document. Emits spec-required headers (`Content-Type: application/json`, `X-Content-Type-Options: nosniff`, `Cache-Control: max-age=3600`, `Access-Control-Allow-Origin: *`). Collision-safe: skips mount when `MCP_HTTP_ENDPOINT_PATH` is `/.well-known/mcp.json`.
- **`buildServerManifest()`** (`src/core/serverManifest.ts`) — pure function that produces the single source of truth consumed by all three surfaces. Takes config + definition arrays, returns `ServerManifest` with server identity, transport, protocol versions, capabilities, definitions, framework, auth, and landing sections. GitHub repo auto-detection from `mcpServerHomepage`, pre-release parsing on version, package.json scope → npm URL derivation.
- **`LandingConfig`** (exported from `@cyanheads/mcp-ts-core`) — consumer-facing config: `enabled`, `tagline`, `logo`, `links`, `theme.accent`, `repoRoot`, `changelogUrl`, `requireAuth`, `attribution`. All fields optional; sane defaults for everything.
- **`landing-rules` linter family** (`src/linter/rules/landing-rules.ts`) — startup-time validation of content limits (tagline ≤120 chars, logo ≤24KB when data URI, max 6 links, `repoRoot` matches `^https://github\.com/[^/]+/[^/]+/?$`). Fails loudly at `createApp()` rather than silently at render time.
- **`html` tagged-template util** (`src/utils/formatting/html.ts`) — auto-escaping HTML builder with `SafeHtml`, `escapeHtml`, and `unsafeRaw` for vetted input. Used internally by the landing renderer and exported for future UI surfaces.
- **Directory-based changelog system** (`changelog/<major.minor>.x/<version>.md`) — one file per released version, shipped in the npm package so agents reading `node_modules/@cyanheads/mcp-ts-core/changelog/0.6.x/0.6.0.md` can inspect a specific version without parsing the monolith. Work-in-progress entries live in `changelog/unreleased.md`. `CHANGELOG.md` becomes an auto-generated navigation index (header + link + one-line summary per release).
- **`bun run changelog:build`** + **`changelog:check`** (`scripts/build-changelog.ts`) — regenerate the rollup from per-version files; `--check` exits non-zero on drift. Wired into devcheck as the new `Changelog Sync` step. Per-version frontmatter: `summary` (required, ≤250 chars, no markdown), `breaking` (optional, default `false`, renders a `· ⚠️ Breaking` badge in the rollup).
- **`scripts/split-changelog.ts`** — one-time migration tool that parsed the legacy monolithic `CHANGELOG.md` and split every `## <version>` section into the new directory structure, preserving bodies and inferring dates. Retained for archaeology.

## Changed

- **`ServerMeta` → `ServerManifest`** (internal) — the `ComposedApp` field name changed from `meta` to `manifest`; the type moved from `src/mcp-server/transports/http/httpTypes.ts` to `src/core/serverManifest.ts` and expanded from 2 fields (`definitionCounts`, `extensions`) to a full manifest covering server identity, transport, protocol, capabilities, framework, auth, definitions, and landing config. Not a breaking change for consumers — `ServerMeta` was never exported.
- **`GET /mcp` status JSON** — now sourced from the shared manifest instead of re-reading config + `SUPPORTED_PROTOCOL_VERSIONS` inline. Output shape is identical; the refactor ensures `/mcp`, `/.well-known/mcp.json`, and `/` cannot drift.
- **Skills updated to reference the directory-based changelog**: `maintenance` (v1.4) reads per-version files between old/new rather than a monolith; `polish-docs-meta` (v1.5) and `release` (v1.3) document the release-ize flow (`git mv changelog/unreleased.md changelog/<series>/<version>.md`, fill frontmatter, regenerate).
- **Skill docs consistency pass** — `add-tool` (v1.7), `add-app-tool` (v1.3), `add-prompt` (v1.2), `add-resource` (v1.3), `add-service` (v1.3), `setup` (v1.4), `api-utils` (v2.1), `api-services` (v1.3), `api-context` (v1.1), `design-mcp-server` (v2.5): inlined the `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` reference as prose (was a 4-space indented block treated as code), replaced lingering `new McpError(JsonRpcErrorCode.*, ...)` examples with the error-factory idiom (`invalidParams()`, `invalidRequest()`, `forbidden()`), and swapped `console.log` examples for structured `logger.info`. `add-tool` also adds a note explaining why the per-item partial-success `try/catch` is the deliberate exception to "logic throws, framework catches."
- **CLAUDE.md + AGENTS.md (root and templates)** — added a top-level `## Changelog` section documenting the directory-based format, frontmatter fields, and pre-release consolidation rule. New `changelog:build` / `changelog:check` rows in the Commands table.
- **`docs/tree.md`** — regenerated to show `changelog/`, new scripts, `serverManifest.ts`, landing/server-card modules, and `templates/changelog/`.

## Fixed

- **`ctx.log` examples in skill references** (`api-services/references/graph.md`, `api-utils/references/parsing.md`, `api-utils/references/security.md`) — replaced `console.log` calls that escaped the "no console" rule with structured `ctx.log.info` / `logger.info` calls.

## Tests

- **+5 new test suites** for the manifest + landing surfaces: `serverManifest.test.ts` (368 lines), `landing-rules.test.ts` (118 lines), `landing-page.test.ts` (497 lines), `serverCard.test.ts` (142 lines), `html.test.ts` (141 lines). HTTP transport tests extended to cover the `/`, `/.well-known/mcp.json`, and `landing.enabled=false` paths. Full suite green.
