Summary

Bootstraps this repo with a TypeScript source-of-truth and generated JSON Schema for MCP Server Cards (SEP-2127) — the static metadata document that lets clients discover and connect to a remote MCP server before initialization.

This relaunches work originally proposed against the core spec in modelcontextprotocol#2652 as an experimental extension, since the SEP itself is still under review and the right home for in-flight types is here, not in schema/draft/schema.ts.

What's in the box

• schema.ts — single-file TypeScript source of truth with ServerCard, Server, Remote, Package, Repository, Argument, Input, KeyValueInput, PackageTransport (stdio / streamable-http / sse), and inlined MetaObject / Icon so the file is self-contained.
• schema.json — generated JSON Schema 2020-12, checked in so consumers can grab it without running the toolchain.
• scripts/generate-schema.ts — runs typescript-json-schema --defaultNumberType integer --required --skipLibCheck and applies the same draft-07 → 2020-12 post-processing the upstream MCP spec uses.
• scripts/validate-examples.ts — ajv 2020-12 validator that walks examples/{ServerCard,Server}/{valid,invalid}/ and asserts each fixture validates / rejects as expected.
• examples/ — 2 valid + 4 invalid ServerCard fixtures and 1 valid Server fixture covering required-field omission, name pattern, schema URL form, and a templated remote with header variables.
• .github/workflows/ci.yml — runs npm run check (regen + tsc) and npm run validate and npm run format:check on every PR.
• README.md — replaces the empty stub with status, layout, schema-URL conventions (/v1/ form), and a graduation plan back into schema/draft/schema.ts of the main spec.

Schema URL conventions

The $schema field on every Server Card / Server document is required and constrained to:

^https://static\.modelcontextprotocol\.io/schemas/v1/[^/]+\.schema\.json$

Schema URLs are versioned by their vN segment rather than by date so additive revisions of the v1 shape don't bump every published document's $schema.

Graduation plan

When SEP-2127 is accepted, the contents of schema.ts here move directly into schema/draft/schema.ts of modelcontextprotocol/modelcontextprotocol. The inlined MetaObject / Icon definitions are dropped during migration since they already exist in the main spec. Documents update their $schema to point at the main spec's hosted schema URL, and this repository is archived.

Verification

• npm run generate produced schema.json from schema.ts (2020-12, $defs, draft 2020-12 $schema URL).
• npm run check passes (regenerated schema matches checked-in schema.json; tsc --noEmit clean).
• npm run validate passes — 7/7 fixtures behave as expected (2 valid ServerCard, 4 invalid ServerCard rejected, 1 valid Server):

  ✓ ServerCard/valid/minimal.json — validated cleanly
  ✓ ServerCard/valid/templated-remote.json — validated cleanly
  ✓ ServerCard/invalid/bad-name-pattern.json — rejected (1 error(s))
  ✓ ServerCard/invalid/date-versioned-schema.json — rejected (1 error(s))
  ✓ ServerCard/invalid/missing-name.json — rejected (1 error(s))
  ✓ ServerCard/invalid/missing-schema.json — rejected (1 error(s))
  ✓ Server/valid/with-package.json — validated cleanly
  

• npm run format:check passes — all files conform to Prettier defaults.

🤖 Generated with Claude Code