Merge branch 'main' into meta-on-resources

Author: mbleigh

.github/workflows/main.yml

@@ -18,8 +18,8 @@ jobs:
 
       - run: npm ci
 
-      - run: npm run validate:schema
+      - name: Check TypeScript definitions
+        run: npm run check:schema:ts
 
-      - run: npm run generate:json
       - name: Verify that `npm run generate:json` did not change outputs (if it did, please re-run it and re-commit!)
-        run: git diff --exit-code
+        run: npm run check:schema:json

.github/workflows/markdown-format.yml

@@ -25,4 +25,7 @@ jobs:
         run: npm ci
 
       - name: Check markdown formatting
-        run: npm run format:check
+        run: npm run check:docs:format
+
+      - name: Check markdown links
+        run: npm run check:docs:links

CONTRIBUTING.md

@@ -33,39 +33,34 @@ npm install  # install dependencies
 ## Making Changes
 
 Note that schema changes are made to `schema.ts`, and `schema.json` is generated from
-`schema.ts`. You should validate your `schema.ts` changes first and then generate the
-`schema.json`.
+`schema.ts`.
 
 1. Create a new branch:
 
 ```bash
 git checkout -b feature/your-feature-name
 ```
 
-2. Make your changes
-3. Validate your changes:
+2. Make your changes.
 
-```bash
-npm run validate:schema    # validate schema
-```
-
-4. Generate the `schema.json`:
+3. Validate schema changes and generate `schema.json`:
 
 ```bash
-npm run generate:json      # generate JSON schema
+npm run check:schema:ts
+npm run generate:json
 ```
 
-5. Run docs locally (optional):
+4. Validate documentation changes and apply formatting:
 
 ```bash
-npm run serve:docs
+npm run check:docs
+npm run format
 ```
 
-6. Format/lint your changes:
+5. Preview documentation locally (optional):
 
 ```bash
-npm run format:check   # check formatting
-npm run format         # apply formatting
+npm run serve:docs
 ```
 
 ### Documentation Guidelines
@@ -77,7 +72,7 @@ When contributing to the documentation:
 - Include code examples where appropriate
 - Use proper MDX formatting and components
 - Test all links and code samples
-  - You may run `npm run check-links` to look for broken internal links.
+  - You may run `npm run check:docs:links` to look for broken internal links.
 - Use appropriate headings: "When to use", "Steps", and "Tips" for tutorials
 - Place new pages in appropriate sections (concepts, tutorials, etc.)
 - Update `docs.json` when adding new pages

docs/sdk/java/mcp-server.mdx

@@ -42,11 +42,11 @@ The server supports both synchronous and asynchronous APIs, allowing for flexibl
 McpSyncServer syncServer = McpServer.sync(transportProvider)
     .serverInfo("my-server", "1.0.0")
     .capabilities(ServerCapabilities.builder()
-        .resources(true)     // Enable resource support
-        .tools(true)         // Enable tool support
-        .prompts(true)       // Enable prompt support
-        .logging()           // Enable logging support
-        .completions()      // Enable completions support
+        .resources(false, true)  // Enable resource support
+        .tools(true)             // Enable tool support
+        .prompts(true)           // Enable prompt support
+        .logging()               // Enable logging support
+        .completions()           // Enable completions support
         .build())
     .build();
 
@@ -68,10 +68,11 @@ syncServer.close();
 McpAsyncServer asyncServer = McpServer.async(transportProvider)
     .serverInfo("my-server", "1.0.0")
     .capabilities(ServerCapabilities.builder()
-        .resources(true)     // Enable resource support
-        .tools(true)         // Enable tool support
-        .prompts(true)       // Enable prompt support
-        .logging()           // Enable logging support
+        .resources(false, true)     // Enable resource support
+        .tools(true)                // Enable tool support
+        .prompts(true)              // Enable prompt support
+        .logging()                  // Enable logging support
+        .completions()              // Enable completions support
         .build())
     .build();
 

docs/specification/2025-03-26/basic/lifecycle.mdx

@@ -144,17 +144,17 @@ available during the session.
 
 Key capabilities include:
 
-| Category | Capability     | Description                                                                              |
-| -------- | -------------- | ---------------------------------------------------------------------------------------- |
-| Client   | `roots`        | Ability to provide filesystem [roots](/specification/2025-03-26/client/roots)            |
-| Client   | `sampling`     | Support for LLM [sampling](/specification/2025-03-26/client/sampling) requests           |
-| Client   | `experimental` | Describes support for non-standard experimental features                                 |
-| Server   | `prompts`      | Offers [prompt templates](/specification/2025-03-26/server/prompts)                      |
-| Server   | `resources`    | Provides readable [resources](/specification/2025-03-26/server/resources)                |
-| Server   | `tools`        | Exposes callable [tools](/specification/2025-03-26/server/tools)                         |
-| Server   | `logging`      | Emits structured [log messages](/specification/2025-03-26/server/utilities/logging)      |
-| Server   | `completions`  | Supports argument [autocompletion](/specification/2025-03-26/server/utilites/completion) |
-| Server   | `experimental` | Describes support for non-standard experimental features                                 |
+| Category | Capability     | Description                                                                               |
+| -------- | -------------- | ----------------------------------------------------------------------------------------- |
+| Client   | `roots`        | Ability to provide filesystem [roots](/specification/2025-03-26/client/roots)             |
+| Client   | `sampling`     | Support for LLM [sampling](/specification/2025-03-26/client/sampling) requests            |
+| Client   | `experimental` | Describes support for non-standard experimental features                                  |
+| Server   | `prompts`      | Offers [prompt templates](/specification/2025-03-26/server/prompts)                       |
+| Server   | `resources`    | Provides readable [resources](/specification/2025-03-26/server/resources)                 |
+| Server   | `tools`        | Exposes callable [tools](/specification/2025-03-26/server/tools)                          |
+| Server   | `logging`      | Emits structured [log messages](/specification/2025-03-26/server/utilities/logging)       |
+| Server   | `completions`  | Supports argument [autocompletion](/specification/2025-03-26/server/utilities/completion) |
+| Server   | `experimental` | Describes support for non-standard experimental features                                  |
 
 Capability objects can describe sub-capabilities like:
 

docs/specification/draft/basic/authorization.mdx

@@ -257,7 +257,7 @@ requests that appear legitimate to resource servers.
 Clients and servers **MUST** implement secure token storage and follow OAuth best practices,
 as outlined in [OAuth 2.1, Section 7.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-7.1).
 
-MCP authorization servers SHOULD issue short-lived access tokens token to reduce the impact of leaked tokens.
+MCP authorization servers SHOULD issue short-lived access tokens to reduce the impact of leaked tokens.
 For public clients, MCP authorization servers **MUST** rotate refresh tokens as described in [OAuth 2.1 Section 4.3.1 "Refresh Token Grant"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-4.3.1).
 
 ### Communication Security

docs/specification/draft/changelog.mdx

@@ -11,14 +11,14 @@ the previous revision, [2025-03-26](/specification/2025-03-26).
 
 1. Removed support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)**
    (PR [#416](https://github.com/modelcontextprotocol/specification/pull/416))
-2. Added support for [structured tool output](server/tools#structured-content)
+2. Added support for [structured tool output](/specification/draft/server/tools#structured-content)
    (PR [#371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/371))
-3. Classified MCP servers as [OAuth Resource Servers](basic/authorization#authorization-server-discovery),
+3. Classified MCP servers as [OAuth Resource Servers](/specification/draft/basic/authorization#authorization-server-discovery),
    adding protected resource metadata to discover the corresponding Authorization server.
    (PR [#338](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/338))
-4. Clarified [security considerations](basic/authorization#security-considerations) and best practices
-   in the authorization spec and in a new [security best practices page](basic/security_best_practices).
-5. Added support for **[elicitation](client/elicitation)**, enabling servers to request additional
+4. Clarified [security considerations](/specification/draft/basic/authorization#security-considerations) and best practices
+   in the authorization spec and in a new [security best practices page](/specification/draft/basic/security_best_practices).
+5. Added support for **[elicitation](/specification/draft/client/elicitation)**, enabling servers to request additional
    information from users during interactions.
    (PR [#382](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/382))
 6. Added support for **[resource links](/specification/draft/server/tools#resource-links)** in

docs/specification/draft/server/tools.mdx

@@ -252,7 +252,7 @@ or data. In this case, the tool will return a URI that can be subscribed to or f
 
 #### Embedded Resources
 
-[Resources](resources) **MAY** be embedded to provide additional context
+[Resources](/specification/draft/server/resources) **MAY** be embedded to provide additional context
 or data using a suitable [URI scheme](./resources#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
 
 ```json

package.json

@@ -21,12 +21,16 @@
     ]
   },
   "scripts": {
-    "validate:schema": "tsc",
+    "check": "npm run check:schema && npm run check:docs",
+    "check:schema": "npm run check:schema:ts && npm run check:schema:json",
+    "check:schema:ts": "tsc",
+    "check:schema:json": "for f in schema/*/schema.ts; do typescript-json-schema --defaultNumberType integer --required --skipLibCheck \"$f\" \"*\" | cat | cmp \"${f%ts}json\" - || exit 1; done",
+    "check:docs": "npm run check:docs:format && npm run check:docs:links",
+    "check:docs:format": "prettier --check \"**/*.{md,mdx}\"",
+    "check:docs:links": "cd docs && mintlify broken-links",
     "generate:json": "for f in schema/*/schema.ts; do typescript-json-schema --defaultNumberType integer --required --skipLibCheck \"$f\" \"*\" -o \"${f%ts}json\"; done",
-    "serve:docs": "cd docs && mintlify dev",
     "format": "prettier --write \"**/*.{md,mdx}\"",
-    "format:check": "prettier --check \"**/*.{md,mdx}\"",
-    "check-links": "cd docs && mintlify broken-links"
+    "serve:docs": "cd docs && mintlify dev"
   },
   "devDependencies": {
     "ajv": "^8.17.1",