Add Server Cards example (SEP-2127)#2692
Draft
dsp-ant wants to merge 1 commit into
Draft
Conversation
Adds a self-contained example package under examples/server-card showing how clients can consume and validate an MCP Server Card and how servers can generate and publish one. - mcp_server_card/types.py: Pydantic port of the Server Card / Server schema, following mcp.types conventions (camelCase wire format, reuses Icon). - mcp_server_card/validation.py: JSON Schema validation against the bundled schema plus semantic guards (e.g. rejecting version ranges). - mcp_server_card/client.py: fetch/load + validate a card from the conventional .well-known location. - mcp_server_card/server.py: build a card and either write it to a file or serve it from a Starlette app / MCPServer. - mcp_server_card/cli.py: validate, fetch, and print the schema. - examples/ and tests/ covering both the client and server flows.
| for header in remote.headers or []: | ||
| flags = "required" if header.is_required else "optional" | ||
| secret = ", secret" if header.is_secret else "" | ||
| print(f" header {header.name} ({flags}{secret})") |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a self-contained example package under
examples/server-card/demonstratingMCP Server Cards (SEP-2127)
in Python: clients consuming and validating a card, and servers generating and
publishing one. It ports the TypeScript source of truth in
experimental-ext-server-cardand follows
mcp.typesconventions, so themcp_server_card/library could laterbe lifted into
mcp/experimental/server_card/largely unchanged.A Server Card is a static metadata document (typically at
https://<host>/.well-known/mcp/server-card) describing a remote server'sidentity, transport endpoints, and supported protocol versions, so a client can
discover and connect to it before initialization.
Layout
mcp_server_card/types.pyServerCard/Serverschema (camelCase wire format, reusesIcon)mcp_server_card/schema.jsonmcp_server_card/validation.pymcp_server_card/client.pyfetch_server_card/load_server_card/well_known_urlmcp_server_card/server.pybuild_server_card/write_server_card/mount_server_card/add_server_card_routemcp_server_card/cli.pymcp-server-card—validate/fetch/schemaexamples/,tests/Design
types.pyis the only place the schema is expressed;Iconis reused frommcp.types(already in the core spec).parse_server_card/parse_server: JSON Schema (authoritative structure) + Pydantic constraints and semantic guards JSON Schema can't express. Failures raiseServerCardValidationErrorcarrying every problem at once.server_card_from_implementation(...)to derive identity from anMCPServer), then eitherwrite_server_card(...)a static file or serve it from the.well-knownpath on a Starlette app /MCPServer.Validation
pytest: 10 passing (round-trip, discriminated transport/argument unions, camelCase serialization, invalid-card rejection).experimental-ext-server-card/examples/— all valid cards parse, all invalid ones are rejected.serve_card.py serveexposes the card over HTTP andconsume_card.pyfetches + validates it; bare-Starlettemount_server_cardalso verified.ruffclean; package builds and installs withuv(bundledschema.jsonships in the wheel;mcp-server-cardentry point works).Open questions
/.well-known/mcp/server-cardper the experimental repo README;schema.tscomment saysmcp-server-card(no subpath) — worth reconciling upstream. Parameterized everywhere.schema.jsonis bundled for offline validation; a real SDK integration would track the version published atstatic.modelcontextprotocol.io.