v2: move registered primitives to classes

docs/migration-SKILL.md

@@ -356,11 +356,42 @@ Schema to method string mapping:
 
 Request/notification params remain fully typed. Remove unused schema imports after migration.
 
-## 10. Client Behavioral Changes
+## 10. 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>` |
+
+## 11. 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.
 
-## 11. Migration Steps (apply in this order)
+## 12. 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

@@ -300,6 +300,56 @@ Common method string replacements:
 | `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
 | `PromptListChangedNotificationSchema`   | `'notifications/prompts/list_changed'`   |
 
+### 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.

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

@@ -14,7 +14,7 @@ import type {
     ZodRawShapeCompat
 } 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, ZodRawShapeCompat } 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';
 
 /**

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';