docs: add a starter docs surface for schema and TypeScript reference

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 *.tsbuildinfo
 .plans/
+.sourcey/

docs/changelog.md

@@ -0,0 +1,37 @@
+---
+title: Changelog
+description: Release history for mcp-schema.
+---
+
+# Changelog
+
+All notable changes to `mcp-schema` are documented here. Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org).
+
+## [0.3.1] - 2026-04-21
+
+### Changed
+- Bump `typescript` to `^5.9.0` and `vitest` to `^3.2.0`.
+- `MCP_SPEC_VERSION` advanced to `"0.3.1"` to match the package.
+
+### Fixed
+- Stale `mcp-spec` package-name references in doc comments and README examples carried over from the pre-rename package.
+
+## [0.3.0] - 2026-04-06
+
+### Added
+- `McpIcon` type and `icons` field on tools, resources, resource templates, prompts, and server info.
+- Optional `description` on `McpServerInfo` for human-readable server metadata.
+
+## [0.2.0] - 2026-04-06
+
+### Added
+- Test suite (14 tests) and GitHub Actions CI matrix (Node 20, 22, 24).
+- Badges and protocol-version compatibility table in the README.
+
+### Changed
+- Renamed from `mcp-spec` to `mcp-schema`.
+
+## [0.1.0] - 2026-04-02
+
+### Added
+- Initial release: TypeScript types and JSON Schema for the `mcp.json` format — tools, resources, resource templates, prompts, server info, capabilities, and transports (stdio, SSE, streamable HTTP).

docs/getting-started.md

@@ -0,0 +1,84 @@
+---
+title: Getting Started
+description: Install mcp-schema and use its types or JSON Schema in a first validation workflow.
+---
+
+## Install
+
+```bash
+npm install mcp-schema
+```
+
+## Choose the package surface you need
+
+Most consumers start in one of two places:
+
+1. Import TypeScript types from `mcp-schema`
+2. Import the JSON Schema from `mcp-schema/schema`
+
+Use the TypeScript entrypoint when you are creating or manipulating MCP server specifications in code. Use the schema entrypoint when you need validator-based checks, including build-time or test-time validation.
+
+## First TypeScript example
+
+```ts
+import type { McpSpec, McpTool, McpResource } from "mcp-schema";
+
+const spec: McpSpec = {
+  mcpSpec: "0.3.1",
+  mcpVersion: "2025-11-25",
+  server: { name: "weather-server", version: "1.0.0" },
+  description: "Real-time weather data for any city.",
+  tools: [
+    {
+      name: "get_weather",
+      description: "Get current weather for a location",
+      inputSchema: {
+        type: "object",
+        properties: {
+          city: { type: "string", description: "City name" },
+        },
+        required: ["city"],
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          temperature: { type: "number" },
+          conditions: { type: "string" },
+        },
+      },
+      annotations: { readOnlyHint: true },
+    },
+  ],
+  resources: [
+    {
+      uri: "weather://cities",
+      name: "Supported Cities",
+      description: "List of cities with weather data",
+      mimeType: "application/json",
+    },
+  ],
+};
+```
+
+## First validation example
+
+```ts
+import Ajv from "ajv";
+import { mcpSpecSchema } from "mcp-schema/schema";
+
+const ajv = new Ajv();
+const validate = ajv.compile(mcpSpecSchema);
+
+const valid = validate(spec);
+if (!valid) {
+  console.error(validate.errors);
+}
+```
+
+This validator workflow is intentionally validator-agnostic at the package level. The repository README shows Ajv, but the exported schema can be used anywhere a compatible JSON Schema validator fits your workflow.
+
+## What to read next
+
+- Go to **Schema Reference** for the `mcp.json` document shape.
+- Go to **TypeScript** for the exported type surface.
+- Go to **Usage** for common package-level workflows.

docs/index.md

@@ -0,0 +1,54 @@
+---
+title: mcp-schema
+description: TypeScript types and JSON Schema for MCP server specifications.
+---
+
+`mcp-schema` provides TypeScript types and JSON Schema for MCP server specifications.
+
+The package is designed for projects that need to define, validate, and share static snapshots of MCP servers. It stays focused on the package surface evidenced in this repository: schema definitions, exported types, protocol-version compatibility, and the `mcp.json` document shape.
+
+## What it provides
+
+- TypeScript types for MCP server specifications
+- JSON Schema for validator-based checks
+- Coverage for tools, resources, resource templates, prompts, capabilities, and transports
+- A versioned package surface for sharing static MCP server snapshots
+
+## Protocol compatibility
+
+Built against the MCP specification and documented support matrix in the repository README.
+
+| Protocol Version | Status |
+| --- | --- |
+| `2025-11-25` | Current stable |
+| `2025-06-18` | Supported |
+| `2025-03-26` | Supported |
+| `2024-11-05` | Supported |
+
+## Package boundaries
+
+`mcp-schema` describes the static shape of an MCP server specification. It does not replace an MCP server runtime or SDK. Instead, it gives downstream consumers a shared contract for:
+
+- authoring `mcp.json`
+- validating specs with a JSON Schema validator
+- importing typed structures in TypeScript
+- documenting or generating from a stable snapshot of server capabilities
+
+## Main entrypoints
+
+| Entry point | Purpose |
+| --- | --- |
+| `mcp-schema` | TypeScript types such as `McpSpec`, `McpTool`, and `McpResource` |
+| `mcp-schema/schema` | JSON Schema export for validation workflows |
+
+## In this documentation
+
+- **Getting Started** covers installation and the fastest path to first use.
+- **Schema Reference** explains the `mcp.json` root document and its main sections.
+- **TypeScript** focuses on the typed package surface for downstream consumers.
+- **Usage** shows package-level workflows grounded in the repository examples.
+- **Changelog** keeps release history visible in the docs surface.
+
+## Related project entrypoints
+
+The repository README remains the canonical front door for badges, quick package context, and upstream links. The changelog remains the release-history source.

docs/readme.md

@@ -0,0 +1,205 @@
+---
+title: README
+description: Repository README for mcp-schema.
+---
+
+# mcp-schema
+
+[![CI](https://github.com/sourcey/mcp-schema/actions/workflows/ci.yml/badge.svg)](https://github.com/sourcey/mcp-schema/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/mcp-schema)](https://www.npmjs.com/package/mcp-schema)
+[![license](https://img.shields.io/npm/l/mcp-schema)](https://github.com/sourcey/mcp-schema/blob/main/LICENSE)
+
+TypeScript types and JSON Schema for [Model Context Protocol](https://modelcontextprotocol.io) server specifications.
+
+Define, validate, and share static snapshots of MCP servers.
+
+## MCP Protocol Compatibility
+
+Built against the [MCP specification](https://github.com/modelcontextprotocol/specification). Supports protocol versions:
+
+| Protocol Version | Status |
+|------------------|--------|
+| [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25) | Current stable |
+| [`2025-06-18`](https://modelcontextprotocol.io/specification/2025-06-18) | Supported |
+| [`2025-03-26`](https://modelcontextprotocol.io/specification/2025-03-26) | Supported |
+| [`2024-11-05`](https://modelcontextprotocol.io/specification/2024-11-05) | Supported |
+
+Types cover tools (with `inputSchema`, `outputSchema`, and [annotations](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#annotations)), resources, resource templates, prompts, server capabilities, and all three transports (stdio, SSE, streamable HTTP).
+
+## Install
+
+```bash
+npm install mcp-schema
+```
+
+## Usage
+
+### TypeScript types
+
+```typescript
+import type { McpSpec, McpTool, McpResource } from "mcp-schema";
+
+const spec: McpSpec = {
+  mcpSpec: "0.3.1",
+  mcpVersion: "2025-11-25",
+  server: { name: "weather-server", version: "1.0.0" },
+  description: "Real-time weather data for any city.",
+  tools: [
+    {
+      name: "get_weather",
+      description: "Get current weather for a location",
+      inputSchema: {
+        type: "object",
+        properties: {
+          city: { type: "string", description: "City name" },
+        },
+        required: ["city"],
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          temperature: { type: "number" },
+          conditions: { type: "string" },
+        },
+      },
+      annotations: { readOnlyHint: true },
+    },
+  ],
+  resources: [
+    {
+      uri: "weather://cities",
+      name: "Supported Cities",
+      description: "List of cities with weather data",
+      mimeType: "application/json",
+    },
+  ],
+};
+```
+
+### JSON Schema validation
+
+```typescript
+import { mcpSpecSchema } from "mcp-schema/schema";
+
+// Use with any JSON Schema validator
+import Ajv from "ajv";
+
+const ajv = new Ajv();
+const validate = ajv.compile(mcpSpecSchema);
+
+const valid = validate(spec);
+if (!valid) {
+  console.error(validate.errors);
+}
+```
+
+## What is mcp.json?
+
+An MCP spec (`mcp.json`) is a static snapshot of an MCP server's capabilities; its tools, resources, and prompts. Think of it as `openapi.json` for MCP servers.
+
+MCP servers describe themselves at runtime via [`tools/list`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools), [`resources/list`](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#listing-resources), and [`prompts/list`](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts#listing-prompts). An MCP spec captures that information in a versionable, shareable file that can be used for documentation, validation, and code generation.
+
+## mcp.json Format
+
+The root document:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `mcpSpec` | `string` | yes | Format version (semver) |
+| `mcpVersion` | `string` | no | MCP protocol version (e.g., `2025-11-25`) |
+| `server` | `object` | yes | Server name and version |
+| `description` | `string` | no | Extended description (markdown) |
+| `capabilities` | `object` | no | Declared server capabilities |
+| `transport` | `object` | no | Transport config hints |
+| `tools` | `McpTool[]` | no | Tools the server exposes |
+| `resources` | `McpResource[]` | no | Concrete resources |
+| `resourceTemplates` | `McpResourceTemplate[]` | no | Parameterized resource templates |
+| `prompts` | `McpPrompt[]` | no | Prompt templates |
+| `$defs` | `object` | no | Shared schema definitions |
+
+### Tools
+
+```json
+{
+  "name": "search_docs",
+  "description": "Search documentation by query",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string" },
+      "limit": { "type": "number", "default": 10 }
+    },
+    "required": ["query"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "results": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string" },
+            "url": { "type": "string" }
+          }
+        }
+      }
+    }
+  },
+  "annotations": {
+    "readOnlyHint": true,
+    "openWorldHint": true
+  }
+}
+```
+
+### Resources
+
+```json
+{
+  "uri": "docs://index",
+  "name": "Documentation Index",
+  "description": "Top-level index of all documentation pages",
+  "mimeType": "application/json"
+}
+```
+
+### Resource Templates
+
+```json
+{
+  "uriTemplate": "docs://pages/{slug}",
+  "name": "Documentation Page",
+  "description": "A single documentation page by slug",
+  "mimeType": "text/markdown"
+}
+```
+
+### Prompts
+
+```json
+{
+  "name": "summarize_page",
+  "description": "Summarize a documentation page",
+  "arguments": [
+    { "name": "url", "description": "Page URL to summarize", "required": true },
+    { "name": "style", "description": "Summary style (brief, detailed)", "required": false }
+  ]
+}
+```
+
+## MCP Specification Resources
+
+- [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25) (current stable)
+- [Specification repo](https://github.com/modelcontextprotocol/specification) (includes JSON Schema for each protocol version)
+- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) (`@modelcontextprotocol/sdk`)
+- [Python SDK](https://github.com/modelcontextprotocol/python-sdk) (`mcp` on PyPI)
+
+## Related
+
+- [mcp-parser](https://github.com/sourcey/mcp-parser): parse, validate, snapshot, and generate from MCP specs
+- [sourcey](https://github.com/sourcey/sourcey): generate documentation from MCP specs, OpenAPI, and markdown
+
+## License
+
+MIT