## What & why
Adds an **`AGENTS.md`** (with a **`CLAUDE.md` symlink**) at the repo
root — a concise operating manual for AI coding agents contributing to
this repository.
It is deliberately **minimal and non-duplicative**:
[`README.md`](./README.md) remains the source of truth for everything
mechanical (what a Server Card is, the layout, the `npm run
generate`/`check`/`validate`/`format` workflow, the
`schema.ts`→`schema.json` regeneration rule, the `$schema` URL
convention, the graduation plan), and `AGENTS.md` points to it rather
than restating it. `AGENTS.md` adds only the **contribution conduct the
README doesn't cover**:
- **Open PRs for human review — do not self-merge AI-generated
changes**, even with merge permissions.
- Keep changes small and scoped; one coherent change per PR; link the
relevant SEP/issue.
- Respect the experimental, SEP-2127-tracked nature; don't pre-empt
unresolved spec discussion; keep the graduation path intact.
- Treat the schema as a public contract; flag breaking changes
explicitly.
`AGENTS.md` is the portable, tool-agnostic entry point; `CLAUDE.md` is a
symlink to it so Claude Code loads it automatically — one file, two
entry points, zero duplication.
## Verification
- [x] **`npm run check` passes** (schema.json in sync, `tsc --noEmit`
clean): `✓ schema.json is up to date`
- [x] **`npm run validate` passes**: `All 7 example(s) passed.`
- [x] **`npm run format:check` passes** (the new `AGENTS.md` is
Prettier-clean): `All matched files use Prettier code style!`
- [x] **Change is docs-only** — adds `AGENTS.md` + `CLAUDE.md` symlink;
no `schema.ts`/`schema.json`/examples touched
- [x] **`CLAUDE.md` is a symlink to `AGENTS.md`** (verified `ls -l`:
`CLAUDE.md -> AGENTS.md`), no content duplication
- [x] **No README duplication** — `AGENTS.md` references `README.md` for
all mechanics and only adds contribution conduct (verified by re-reading
both files side by side after a fresh-eyes review)
- [x] **CI green on this PR**: `build`, `CodeQL`, and `Analyze
(actions)` all pass (re-confirmed after each revision)
---
🤖 Opened by an AI coding agent for human review — **not** to be
self-merged (per the contribution norms in this very PR). Please review
and merge if it looks good.
The 'A Server Card includes:' list in docs/discovery.md mentioned
'Capabilities — Tools, resources, and prompts the server offers',
which contradicts schema.ts and SEP-2127: Server Cards do not
enumerate primitives. Primitives remain subject to runtime listing
via the protocol's standard list operations.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace application/mcp-server+json with application/mcp-server-card+json
in docs/discovery.md to match the AI Catalog specification, which
discovery.md cites as the standard MCP Catalog entries are a subset of.
Fixes#9
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replaces the prior reconstruction with the canonical content from commit
bb3bd697 on SamMorrowDrums/modelcontextprotocol@sammorrowdrums/mcp-catalog-specification,
adapted from .mdx to plain .md (frontmatter and Mintlify components stripped,
content preserved verbatim).
Covers all of tadasant's review feedback: internal MCP Server Cards subsection,
.json well-known path, reverse-DNS identifiers, identifier MUST constraint,
cross-domain advertising language, SHOULD-publish recommendation.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add MCP Server Card subsection defining application/mcp-server+json
and link 'MCP Server Cards' references internally rather than to SEP-2127
- Reframe domain hosting language to support cross-host advertising
(catalog MAY reference servers on different web hosts)
- Switch well-known URI to /.well-known/mcp/catalog.json
- Add SHOULD-publish recommendation for organizations offering MCP services
- Make specVersion OPTIONAL with note about pushing AI Catalog to align
- Tighten identifier definition: MUST begin with urn:mcp:server: and the
remainder MUST exactly match the server card's name
- Update all examples to use reverse-DNS identifiers
- Keep Content-Type: application/json for the catalog itself
- Add cross-host advertising example and trust considerations
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add docs/discovery.md defining the MCP Catalog format for config-free
auto-discovery of MCP server cards via a well-known URI. The catalog is
a minimal, MCP-scoped subset of the AI Catalog specification.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Wire prettier into scripts/generate-schema.ts so the generated schema.json
matches the repo's prettier config, fixing the failing `format:check` CI job.
Regenerated schema.json to apply the formatting.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The committed schema.json had drifted from schema.ts, causing
`npm run check` (and therefore the `build` CI job) to fail on
every PR. Regenerated via `npm run generate`.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Tracks SEP-2127 (MCP Server Cards) as an experimental extension while the SEP
itself is under review. The schema.ts is structured to be lifted directly into
schema/draft/schema.ts of the main spec when Server Cards graduate -- only the
inlined MetaObject and Icon definitions need to be removed during migration.
- schema.ts: ServerCard, Server, Repository, Remote, Package, Argument, Input,
KeyValueInput, etc. plus inlined MetaObject and Icon
- scripts/generate-schema.ts: typescript-json-schema with 2020-12 transforms
- scripts/validate-examples.ts: ajv validator over examples/{ServerCard,Server}/
- examples/: 2 valid + 4 invalid Server Card cases, 1 valid Server case
- README: status, layout, schema URL conventions, graduation plan
- CI workflow: check + validate + format on every PR
