modelcontextprotocol/ext-server-card
Watch
1
0
Fork
You've already forked ext-server-card
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Mirror of https://github.com/modelcontextprotocol/ext-server-card
22 commits 1 branch 0 tags 122 KiB
  • TypeScript 100%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Tadas Antanavicius 9222cf6527
 docs: require Server Card to be consistent with runtime behavior (#25) 
Closes #23.

## What

Adds the missing normative requirement that a Server Card's declared
values must not contradict the server's actual runtime behavior. The
schema already encodes the *omission* half of the threat model
(primitives are deliberately excluded because a static manifest drifts
from runtime); this adds the *complementary* requirement for the fields
the card **does** declare.

### `docs/discovery.md`

- **New "Consistency with Runtime Behavior" subsection** under "MCP
Server Cards":
- A Server Card SHOULD accurately reflect the server's actual runtime
behavior. The `serverInfo` (`name`, `version`) and `supportedVersions`
returned by
[`server/discover`](https://modelcontextprotocol.io/specification/draft/server/discover),
plus the transport actually served at each `remotes[]` endpoint (and
descriptive `title`/`description`/`icons`), SHOULD NOT contradict the
equivalent values declared in the Server Card.
- Clients MUST NOT treat Server Card contents as authoritative for
security or access-control decisions, and SHOULD verify claims against
the live connection — the same posture the spec takes toward primitives,
generalized to the declared fields.
- **New "Server Card Accuracy" subsection** under "Security
Considerations": frames an inaccurate (stale or crafted) card as a mild
confusion/downgrade vector, so the consistency requirement is partly a
security property, not just correctness. It is explanatory and points
back to the single normative statement above rather than re-asserting
the MUST NOT.

### `schema.ts`

- Short pointer comment in the `ServerCard` JSDoc referencing the
discovery-doc requirement, complementing the existing
primitives-omission rationale. `schema.json` regenerated via `npm run
generate` in the same commit (CI `check` enforces sync).

RFC 2119 keywords are used consistently with the rest of
`docs/discovery.md`. The runtime reference is phrased around the draft
spec's
[`server/discover`](https://modelcontextprotocol.io/specification/draft/server/discover)
operation — the pre-`initialize` exchange that actually returns
`serverInfo`/`supportedVersions` — rather than SEP-2127's
`DiscoverResultResponse`, which has no term in this repo.

## Security rationale

Because a Server Card is consumed *before* the client connects, an
inaccurate card can steer a client toward a weaker configuration
(downgrade) or a misidentified server (confusion) before it has observed
the server's actual `server/discover` response. Treating the card as
advisory rather than authoritative contains this risk.

## Scope

Small and focused strictly on the card-vs-runtime consistency
requirement. Distinct from #10 (the inverse — primitives the card omits)
and #13/#9/#11/#12/#14/#21 (none touch card-vs-runtime consistency). No
unrelated changes.

## Verification

- [x] `npm run check` passes — `schema.json` is in sync with `schema.ts`
and `tsc --noEmit` is clean
- [x] `npm run validate` passes — all 7 examples validate against the
regenerated schema
- [x] `npm run format` clean — no formatting changes left
- [x] `schema.json` regenerated and committed alongside the `schema.ts`
change (CI `check` enforces this)
- [x] Fresh-eyes review by a separate agent — feedback addressed
(full-term "Server Card" wording for consistency with the rest of the
doc; de-duplicated the MUST NOT so the security section is explanatory
and points to the single normative statement)
- [x] Maintainer review (Sam) — substance approved; applied the
requested brevity pass, tightening both new subsections with no change
to any normative statement
- [x] `server/discover` spec link verified to resolve to a real
draft-spec page documenting `serverInfo` / `supportedVersions`
- [x] CI green on the final commit (`0d0389b`) — build, Analyze
(actions), and CodeQL all pass

This is a docs/comment-only change (no runtime code paths), so the
verification is the build/schema toolchain rather than e2e tests. Local
toolchain output:

```
✓ Generated schema.json
✓ schema.json is up to date    (npm run check)
All 7 example(s) passed.        (npm run validate)
```

Opened for human review — **not** merged, per repo policy.

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 13:36:19 -07:00
.github/workflows Bootstrap repo with TypeScript source-of-truth and generated JSON Schema 2026-04-27 19:47:01 +00:00
docs docs: require Server Card to be consistent with runtime behavior (#25) 2026-06-08 13:36:19 -07:00
examples Bootstrap repo with TypeScript source-of-truth and generated JSON Schema 2026-04-27 19:47:01 +00:00
scripts chore: format schema.json with prettier in generator 2026-05-18 15:50:17 +02:00
.gitignore Bootstrap repo with TypeScript source-of-truth and generated JSON Schema 2026-04-27 19:47:01 +00:00
AGENTS.md docs: add AGENTS.md (CLAUDE.md symlink) for AI coding agents (#20) 2026-06-08 08:16:20 -07:00
CLAUDE.md docs: add AGENTS.md (CLAUDE.md symlink) for AI coding agents (#20) 2026-06-08 08:16:20 -07:00
LICENSE Initial commit 2026-04-27 21:19:27 +02:00
package-lock.json Bump vm2 in the npm_and_yarn group across 1 directory 2026-05-08 14:45:46 +00:00
package.json Bootstrap repo with TypeScript source-of-truth and generated JSON Schema 2026-04-27 19:47:01 +00:00
README.md Server Cards: recommend /server-card over .well-known (resolves #12) (#22) 2026-06-08 12:40:51 -07:00
schema.json docs: require Server Card to be consistent with runtime behavior (#25) 2026-06-08 13:36:19 -07:00
schema.ts docs: require Server Card to be consistent with runtime behavior (#25) 2026-06-08 13:36:19 -07:00
tsconfig.json Bootstrap repo with TypeScript source-of-truth and generated JSON Schema 2026-04-27 19:47:01 +00:00

README.md

MCP Server Cards (Experimental Extension)

Status: Experimental. This work is for prototyping and feedback only, and is not an accepted or official MCP extension.

This repository defines a TypeScript source-of-truth and generated JSON Schema for MCP Server Cards — a static metadata document that describes a remote MCP server enough for clients to discover and connect to it before initialization.

It tracks SEP-2127 and is intended to be lifted directly into the main spec when Server Cards graduate (see Graduation plan below).

A prior attempt to land these types directly in the core spec (modelcontextprotocol#2652) is being relaunched here as an experimental extension while the SEP itself is still under review.

What is a Server Card?

A Server Card is a JSON document — hosted at any unreserved URI, with GET <streamable-http-url>/server-card reserved as the recommended location (see discovery.md) — describing:

  • The server's identity (name, version, description, optional title / icons / repository / websiteUrl)
  • Its remote transport endpoints (URLs, headers, variable templates, supported protocol versions)
  • Optional registry-style extension metadata (_meta)

The companion Server document is a strict superset that adds locally-runnable packages — it is the shape the MCP Registry uses for server.json.

Server Cards intentionally omit primitive listings (tools, resources, prompts) — those remain subject to runtime listing via the protocol's standard list operations.

Layout

schema.ts                    # TypeScript source of truth (single file)
schema.json                  # Generated JSON Schema 2020-12 (do not edit by hand)
scripts/
  generate-schema.ts         # Generates schema.json from schema.ts
  validate-examples.ts       # Validates examples/ against the generated schema
examples/
  ServerCard/{valid,invalid} # Example Server Card documents
  Server/{valid,invalid}     # Example Server (registry-shaped) documents

The generated schema.json is checked into the repo so consumers can grab it without running the toolchain.

Working on the schema

npm install
npm run generate         # regenerates schema.json from schema.ts
npm run validate         # runs all examples through ajv against schema.json
npm run check            # asserts schema.json is in sync with schema.ts and tsc passes
npm run format           # prettier write

When you change schema.ts, always run npm run generate and commit the updated schema.json in the same commit. CI runs npm run check and will fail if they drift.

Schema URL conventions

The $schema field on every document MUST be a URL of the form:

https://static.modelcontextprotocol.io/schemas/v1/<name>.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. Breaking changes would publish a v2 family.

Graduation plan

When the SEP is accepted and Server Cards graduate from this experimental extension:

  1. The contents of schema.ts in this repo move into schema/draft/schema.ts of modelcontextprotocol/modelcontextprotocol. The two MetaObject and Icon definitions inlined here at the bottom of schema.ts already exist in the main spec and are dropped from the migration.
  2. The main spec's existing scripts/generate-schemas.ts regenerates schema/draft/schema.json (and downstream docs/specification/draft/schema.mdx) — no per-extension generator is required there.
  3. Published documents update their $schema to point at the main spec's hosted schema URL (e.g., https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json served from modelcontextprotocol/static).
  4. This repository is archived with a pointer to the relevant section of schema/draft/schema.ts in the main spec.

The schema.ts in this repo is deliberately structured to be copy-pasted into the main spec's schema/draft/schema.ts with no transformation other than removing the inlined MetaObject / Icon definitions.

References