v2: move registered primitives to classes

docs/migration-SKILL.md

@@ -424,11 +424,42 @@ const tool = await client.callTool({ name: 'my-tool', arguments: {} });
 
 Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
 
-## 12. Client Behavioral Changes
+## 12. Registered Primitives API Changes
+
+`RegisteredTool`, `RegisteredPrompt`, `RegisteredResource`, `RegisteredResourceTemplate` are now proper classes. The `update()` method signature changed:
+
+| v1 (update field) | v2 (update field) | Applies to                                                                   |
+| ----------------- | ----------------- | ---------------------------------------------------------------------------- |
+| `paramsSchema`    | `inputSchema`     | RegisteredTool                                                               |
+| `callback`        | `handler`         | RegisteredTool                                                               |
+| `callback`        | `callback`        | RegisteredPrompt, RegisteredResource, RegisteredResourceTemplate (unchanged) |
+
+```typescript
+// v1
+tool.update({ paramsSchema: { name: z.string() }, callback: handler });
+
+// v2
+tool.update({ inputSchema: { name: z.string() }, handler: handler });
+```
+
+**Note:** In v1, `paramsSchema` inconsistently differed from `inputSchema` used in `registerTool()`. Fixed in v2.
+
+**New:** `RegisteredTool` now supports `icons` field (parity with protocol `Tool` type).
+
+New getter methods on `McpServer`:
+
+| Getter | Returns |
+|--------|---------|
+| `mcpServer.tools` | `ReadonlyMap<string, RegisteredTool>` |
+| `mcpServer.prompts` | `ReadonlyMap<string, RegisteredPrompt>` |
+| `mcpServer.resources` | `ReadonlyMap<string, RegisteredResource>` |
+| `mcpServer.resourceTemplates` | `ReadonlyMap<string, RegisteredResourceTemplate>` |
+
+## 13. Client Behavioral Changes
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, `listTools()` now return empty results when the server lacks the corresponding capability (instead of sending the request). Set `enforceStrictCapabilities: true` in `ClientOptions` to throw an error instead.
 
-## 13. Runtime-Specific JSON Schema Validators (Enhancement)
+## 14. Runtime-Specific JSON Schema Validators (Enhancement)
 
 The SDK now auto-selects the appropriate JSON Schema validator based on runtime:
 - Node.js → `AjvJsonSchemaValidator` (no change from v1)
@@ -448,7 +479,7 @@ new McpServer({ name: 'server', version: '1.0.0' }, {});
 
 Access validators via `_shims` export: `import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';`
 
-## 14. Migration Steps (apply in this order)
+## 15. Migration Steps (apply in this order)
 
 1. Update `package.json`: `npm uninstall @modelcontextprotocol/sdk`, install the appropriate v2 packages
 2. Replace all imports from `@modelcontextprotocol/sdk/...` using the import mapping tables (sections 3-4), including `StreamableHTTPServerTransport` → `NodeStreamableHTTPServerTransport`

docs/migration.md

@@ -404,6 +404,56 @@ const result = await client.callTool({ name: 'my-tool', arguments: {} });
 
 The return type is now inferred from the method name via `ResultTypeMap`. For example, `client.request({ method: 'tools/call', ... })` returns `Promise<CallToolResult | CreateTaskResult>`.
 
+### Registered primitives are now classes
+
+`RegisteredTool`, `RegisteredPrompt`, `RegisteredResource`, and `RegisteredResourceTemplate` are now proper classes instead of plain object types. They are exported from `@modelcontextprotocol/server`.
+
+The `update()` method now uses `inputSchema` and `handler` instead of `paramsSchema` and `callback`:
+
+**Before (v1):**
+
+```typescript
+const tool = server.registerTool('my-tool', { inputSchema: { name: z.string() } }, handler);
+
+tool.update({
+    paramsSchema: { name: z.string(), value: z.number() },
+    callback: newHandler
+});
+```
+
+**After (v2):**
+
+```typescript
+const tool = server.registerTool('my-tool', { inputSchema: { name: z.string() } }, handler);
+
+tool.update({
+    inputSchema: { name: z.string(), value: z.number() },
+    handler: newHandler
+});
+```
+
+**Note:** In v1, `RegisteredTool.update()` used `paramsSchema` which inconsistently differed from the `inputSchema` field used in `registerTool()`. This has been fixed in v2.
+
+**New:** `RegisteredTool` now supports the `icons` field for parity with the protocol `Tool` type:
+
+```typescript
+tool.update({ icons: [{ type: 'base64', mediaType: 'image/png', data: '...' }] });
+```
+
+New getter methods are available on `McpServer` to access all registered items:
+
+```typescript
+// Get all registered tools
+for (const [name, tool] of mcpServer.tools) {
+    console.log(name, tool.description, tool.enabled);
+}
+
+// Similarly for prompts, resources, resourceTemplates
+mcpServer.prompts;
+mcpServer.resources;
+mcpServer.resourceTemplates;
+```
+
 ### Client list methods return empty results for missing capabilities
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, and `listTools()` now return empty results when the server didn't advertise the corresponding capability, instead of sending the request. This respects the MCP spec's capability negotiation.

docs/server.md

@@ -199,7 +199,7 @@ server.registerResource(
 );
 ```
 
-Dynamic resources use {@linkcode @modelcontextprotocol/server!server/mcp.ResourceTemplate | ResourceTemplate} and can support completions on path parameters:
+Dynamic resources use {@linkcode @modelcontextprotocol/server!server/primitives/resourceTemplate.ResourceTemplate | ResourceTemplate} and can support completions on path parameters:
 
 ```ts source="../examples/server/src/serverGuide.examples.ts#registerResource_template"
 server.registerResource(

packages/server/src/experimental/tasks/interfaces.ts

@@ -13,7 +13,7 @@ import type {
     TaskServerContext
 } from '@modelcontextprotocol/core';
 
-import type { BaseToolCallback } from '../../server/mcp.js';
+import type { BaseToolCallback } from '../../server/primitives/index.js';
 
 // ============================================================================
 // Task Handler Types (for registerToolTask)

packages/server/src/experimental/tasks/mcpServer.ts

@@ -7,7 +7,8 @@
 
 import type { AnySchema, TaskToolExecution, ToolAnnotations, ToolExecution } from '@modelcontextprotocol/core';
 
-import type { AnyToolHandler, McpServer, RegisteredTool } from '../../server/mcp.js';
+import type { McpServer } from '../../server/mcp.js';
+import type { AnyToolHandler, RegisteredTool } from '../../server/primitives/index.js';
 import type { ToolTaskHandler } from './interfaces.js';
 
 /**
@@ -72,7 +73,7 @@ export class ExperimentalMcpServerTasks {
      * @param name - The tool name
      * @param config - Tool configuration (description, schemas, etc.)
      * @param handler - Task handler with {@linkcode ToolTaskHandler.createTask | createTask}, {@linkcode ToolTaskHandler.getTask | getTask}, {@linkcode ToolTaskHandler.getTaskResult | getTaskResult} methods
-     * @returns {@linkcode server/mcp.RegisteredTool | RegisteredTool} for managing the tool's lifecycle
+     * @returns {@linkcode server/primitives/tool.RegisteredTool | RegisteredTool} for managing the tool's lifecycle
      *
      * @experimental
      */

packages/server/src/index.ts

@@ -1,6 +1,7 @@
 export * from './server/completable.js';
 export * from './server/mcp.js';
 export * from './server/middleware/hostHeaderValidation.js';
+export * from './server/primitives/index.js';
 export * from './server/server.js';
 export * from './server/stdio.js';
 export * from './server/streamableHttp.js';