From efdab92c94d8b4490507c821ac5238845307b4d7 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Mon, 8 Jun 2026 00:10:06 +0000 Subject: [PATCH 1/3] docs: add AGENTS.md (CLAUDE.md symlink) for AI coding agents Adds a concise operating manual for AI coding agents contributing to this repo. It references README.md for domain context rather than duplicating it, and codifies the contribution norms: schema.ts is the source of truth and schema.json is regenerated (never hand-edited) in the same commit; keep changes small and scoped; open PRs for human review rather than self-merging agent-generated changes; respect the experimental/SEP-2127 status; treat the schema as a public contract. CLAUDE.md is a symlink to AGENTS.md so Claude Code loads it automatically while AGENTS.md stays the portable, tool-agnostic entry point. --- AGENTS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 56 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dddd8b6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,55 @@ +# AGENTS.md — MCP Server Cards (Experimental Extension) + +Operating manual for AI coding agents working in this repository. For full domain context (what a Server Card is, the Server superset, the graduation plan, and references), read [`README.md`](./README.md) first — this file does not repeat it. + +## What this repo is, in one line + +The TypeScript source-of-truth (`schema.ts`) and generated JSON Schema 2020-12 (`schema.json`) for **MCP Server Cards**, an **experimental** extension tracking [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127). It is a temporary incubator: when the SEP is accepted, the schema migrates into the main `modelcontextprotocol/modelcontextprotocol` repo and this repo is archived (see the README's "Graduation plan"). + +## Layout + +See [`README.md` → Layout](./README.md#layout). The essentials: `schema.ts` is the only place to make schema changes; `schema.json` is **generated** and checked in; `scripts/` holds the generator and the example validator; `examples/` holds valid/invalid `ServerCard` and `Server` documents that double as the test suite. + +## Working in this repo + +Follow the README's "Working on the schema" section. The non-negotiables: + +- **`schema.ts` is the source of truth. Never hand-edit `schema.json`** — regenerate it with `npm run generate` and commit the result **in the same commit** as the `schema.ts` change. CI runs `npm run check` and fails on drift. +- **Cover behavior changes with examples.** Add/update documents under `examples/ServerCard/{valid,invalid}` (and `examples/Server/...` where relevant) so `npm run validate` exercises the change. +- **Match conventions.** The `$schema` field on documents follows the versioned `https://static.modelcontextprotocol.io/schemas/v1/.schema.json` pattern (README → "Schema URL conventions"). Run `npm run format` before committing. +- Before pushing, run `npm run check` and `npm run validate` locally to reproduce CI. + +## Core principles + +Ordered most-important first. + +### 1. Open PRs for human review — do not self-merge agent-generated changes + +Agent-driven work here opens a pull request and hands it back to a human maintainer to review and merge. Even when the account running the agent has merge permissions, **do not merge your own AI-generated PRs** (and do not enable auto-merge). The decision to merge belongs to a human. + +### 2. Stay small, scoped, and conservative + +This is an active, spec-tracked, community project. Make one coherent change per PR; don't bundle unrelated refactors or repo-wide reformatting into a feature/fix. Write clear PR descriptions that link the relevant SEP/issue and explain how you verified the change. Match existing style and layout, and defer to maintainers on direction. For anything larger than a self-contained change, prefer opening an issue or a draft PR for discussion over a large unilateral edit. + +### 3. Respect the experimental, spec-tracked nature + +Schema decisions here feed SEP-2127 and, eventually, the core MCP spec. Don't make changes that pre-empt or contradict unresolved spec discussion. "Experimental" means provisional, not low-stakes — keep the migration path in the README's "Graduation plan" intact (e.g., keep `schema.ts` structured so it can be lifted into the main spec). + +### 4. Treat the schema as a public contract + +`schema.json` is consumed by external tools and published documents. If a change is breaking for consumers (removing/renaming fields, tightening required-ness), call it out explicitly in the PR description rather than shipping it silently. + +## What NOT to do + +- Do **not** merge your own AI-generated PR, even with permission (Principle 1). +- Do **not** hand-edit `schema.json` — regenerate it from `schema.ts`. +- Do **not** bundle unrelated changes, reformat the whole repo, or do sweeping renames in a feature/fix PR. +- Do **not** make schema changes that pre-empt unresolved SEP-2127 / core-spec discussion. + +## FAQ + +- **Q: CI fails on a `schema.json` mismatch — what happened?** + A: `schema.ts` changed without regenerating. Run `npm run generate` and commit the updated `schema.json` in the same commit. `npm run check` reproduces the CI assertion locally. + +- **Q: It's just an experimental repo — can I restructure boldly?** + A: No. It tracks an active SEP and feeds the core spec. Stay small and scoped (Principle 2); raise larger ideas via an issue or draft PR first. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 9d3b18f048537dae2b4cb62dd4da9772a2526fba Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Mon, 8 Jun 2026 00:13:08 +0000 Subject: [PATCH 2/3] docs: address review feedback on AGENTS.md - Mention npm run format:check in the local pre-push checks - Don't imply an examples/Server/invalid dir exists; reference parallel dirs - Soften graduation/archival to conditional framing matching the README - Phrase the open-PR-for-review guidance neutrally --- AGENTS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dddd8b6..07688f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,20 +4,20 @@ Operating manual for AI coding agents working in this repository. For full domai ## What this repo is, in one line -The TypeScript source-of-truth (`schema.ts`) and generated JSON Schema 2020-12 (`schema.json`) for **MCP Server Cards**, an **experimental** extension tracking [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127). It is a temporary incubator: when the SEP is accepted, the schema migrates into the main `modelcontextprotocol/modelcontextprotocol` repo and this repo is archived (see the README's "Graduation plan"). +The TypeScript source-of-truth (`schema.ts`) and generated JSON Schema 2020-12 (`schema.json`) for **MCP Server Cards**, an **experimental** extension tracking [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127). It is a temporary incubator: when the SEP is accepted, the schema is expected to migrate into the main `modelcontextprotocol/modelcontextprotocol` repo and this repo to be archived (see the README's "Graduation plan"). ## Layout -See [`README.md` → Layout](./README.md#layout). The essentials: `schema.ts` is the only place to make schema changes; `schema.json` is **generated** and checked in; `scripts/` holds the generator and the example validator; `examples/` holds valid/invalid `ServerCard` and `Server` documents that double as the test suite. +See [`README.md` → Layout](./README.md#layout). The essentials: `schema.ts` is the only place to make schema changes; `schema.json` is **generated** and checked in; `scripts/` holds the generator and the example validator; `examples/` holds `ServerCard` and `Server` example documents (valid and invalid) that double as the test suite. ## Working in this repo Follow the README's "Working on the schema" section. The non-negotiables: - **`schema.ts` is the source of truth. Never hand-edit `schema.json`** — regenerate it with `npm run generate` and commit the result **in the same commit** as the `schema.ts` change. CI runs `npm run check` and fails on drift. -- **Cover behavior changes with examples.** Add/update documents under `examples/ServerCard/{valid,invalid}` (and `examples/Server/...` where relevant) so `npm run validate` exercises the change. +- **Cover behavior changes with examples.** Add/update documents under `examples/ServerCard/{valid,invalid}` (and the parallel `examples/Server/` directories where relevant) so `npm run validate` exercises the change. - **Match conventions.** The `$schema` field on documents follows the versioned `https://static.modelcontextprotocol.io/schemas/v1/.schema.json` pattern (README → "Schema URL conventions"). Run `npm run format` before committing. -- Before pushing, run `npm run check` and `npm run validate` locally to reproduce CI. +- Before pushing, run `npm run check`, `npm run validate`, and `npm run format:check` locally to reproduce CI. ## Core principles @@ -25,7 +25,7 @@ Ordered most-important first. ### 1. Open PRs for human review — do not self-merge agent-generated changes -Agent-driven work here opens a pull request and hands it back to a human maintainer to review and merge. Even when the account running the agent has merge permissions, **do not merge your own AI-generated PRs** (and do not enable auto-merge). The decision to merge belongs to a human. +Agent-driven changes should be opened as a pull request for a human maintainer to review and merge. Even when the account running the agent has merge permissions, **do not merge your own AI-generated PRs** (and do not enable auto-merge). The decision to merge belongs to a human. ### 2. Stay small, scoped, and conservative From a9375d4f1fa23d90b270e1decf7328b20c28f0ec Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Mon, 8 Jun 2026 00:49:53 +0000 Subject: [PATCH 3/3] docs: trim AGENTS.md to remove README duplication Drop the What-this-repo-is, Layout, and Working-in-this-repo sections and the FAQ -- they restated the README (domain, layout, schema build/validate workflow, $schema convention, graduation plan). AGENTS.md now points to the README for all mechanics and keeps only the contribution conduct the README doesn't cover (open PRs for human review, stay small/scoped, respect the experimental spec-tracked status, treat the schema as a public contract). --- AGENTS.md | 34 +++++----------------------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 07688f9..9fda002 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,10 @@ # AGENTS.md — MCP Server Cards (Experimental Extension) -Operating manual for AI coding agents working in this repository. For full domain context (what a Server Card is, the Server superset, the graduation plan, and references), read [`README.md`](./README.md) first — this file does not repeat it. +Operating manual for AI coding agents working in this repository. -## What this repo is, in one line +**Read [`README.md`](./README.md) first.** It is the source of truth for everything mechanical — what a Server Card is, the repo layout, the schema build/validate workflow (`npm run generate` / `check` / `validate` / `format`), the rule that `schema.ts` is authoritative and `schema.json` is generated (never hand-edited, regenerated in the same commit, enforced by CI), the `$schema` URL convention, and the graduation plan. This file does **not** repeat any of that; it only adds the contribution conduct the README doesn't cover. -The TypeScript source-of-truth (`schema.ts`) and generated JSON Schema 2020-12 (`schema.json`) for **MCP Server Cards**, an **experimental** extension tracking [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127). It is a temporary incubator: when the SEP is accepted, the schema is expected to migrate into the main `modelcontextprotocol/modelcontextprotocol` repo and this repo to be archived (see the README's "Graduation plan"). - -## Layout - -See [`README.md` → Layout](./README.md#layout). The essentials: `schema.ts` is the only place to make schema changes; `schema.json` is **generated** and checked in; `scripts/` holds the generator and the example validator; `examples/` holds `ServerCard` and `Server` example documents (valid and invalid) that double as the test suite. - -## Working in this repo - -Follow the README's "Working on the schema" section. The non-negotiables: - -- **`schema.ts` is the source of truth. Never hand-edit `schema.json`** — regenerate it with `npm run generate` and commit the result **in the same commit** as the `schema.ts` change. CI runs `npm run check` and fails on drift. -- **Cover behavior changes with examples.** Add/update documents under `examples/ServerCard/{valid,invalid}` (and the parallel `examples/Server/` directories where relevant) so `npm run validate` exercises the change. -- **Match conventions.** The `$schema` field on documents follows the versioned `https://static.modelcontextprotocol.io/schemas/v1/.schema.json` pattern (README → "Schema URL conventions"). Run `npm run format` before committing. -- Before pushing, run `npm run check`, `npm run validate`, and `npm run format:check` locally to reproduce CI. - -## Core principles +## Contribution principles Ordered most-important first. @@ -29,11 +14,11 @@ Agent-driven changes should be opened as a pull request for a human maintainer t ### 2. Stay small, scoped, and conservative -This is an active, spec-tracked, community project. Make one coherent change per PR; don't bundle unrelated refactors or repo-wide reformatting into a feature/fix. Write clear PR descriptions that link the relevant SEP/issue and explain how you verified the change. Match existing style and layout, and defer to maintainers on direction. For anything larger than a self-contained change, prefer opening an issue or a draft PR for discussion over a large unilateral edit. +This is an active, spec-tracked, community project. Make one coherent change per PR; don't bundle unrelated refactors or repo-wide reformatting into a feature/fix. Write clear PR descriptions that link the relevant SEP/issue and explain how you verified the change. Match existing conventions and defer to maintainers on direction. For anything larger than a self-contained change, prefer opening an issue or a draft PR for discussion over a large unilateral edit. ### 3. Respect the experimental, spec-tracked nature -Schema decisions here feed SEP-2127 and, eventually, the core MCP spec. Don't make changes that pre-empt or contradict unresolved spec discussion. "Experimental" means provisional, not low-stakes — keep the migration path in the README's "Graduation plan" intact (e.g., keep `schema.ts` structured so it can be lifted into the main spec). +Schema decisions here feed SEP-2127 and, eventually, the core MCP spec. Don't make changes that pre-empt or contradict unresolved spec discussion, and keep the README's "Graduation plan" migration path intact. "Experimental" means provisional, not low-stakes. ### 4. Treat the schema as a public contract @@ -42,14 +27,5 @@ Schema decisions here feed SEP-2127 and, eventually, the core MCP spec. Don't ma ## What NOT to do - Do **not** merge your own AI-generated PR, even with permission (Principle 1). -- Do **not** hand-edit `schema.json` — regenerate it from `schema.ts`. - Do **not** bundle unrelated changes, reformat the whole repo, or do sweeping renames in a feature/fix PR. - Do **not** make schema changes that pre-empt unresolved SEP-2127 / core-spec discussion. - -## FAQ - -- **Q: CI fails on a `schema.json` mismatch — what happened?** - A: `schema.ts` changed without regenerating. Run `npm run generate` and commit the updated `schema.json` in the same commit. `npm run check` reproduces the CI assertion locally. - -- **Q: It's just an experimental repo — can I restructure boldly?** - A: No. It tracks an active SEP and feeds the core spec. Stay small and scoped (Principle 2); raise larger ideas via an issue or draft PR first.