Add server instructions, progress, and roots sections to

`docs/server.md`

Three gaps identified in the server how-to guide, each with a
type-checked example in `serverGuide.examples.ts`:

- **Server instructions** — `McpServer` constructor `instructions`
  option for cross-tool relationships, workflow patterns, and
  constraints. Placed between Transports and Tools.
- **Progress** — sending `notifications/progress` via
  `ctx.mcpReq.notify()` during long-running tool execution, guarded by
  `progressToken`. Placed between Logging and Server-initiated requests.
- **Roots** — calling `server.server.listRoots()` to discover the
  client's workspace directories. Placed under Server-initiated requests
  alongside Sampling and Elicitation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jonathanhefner

docs/server.md

@@ -61,6 +61,20 @@ const transport = new StdioServerTransport();
 await server.connect(transport);
 ```
 
+## Server instructions
+
+Instructions describe how to use the server and its features — cross-tool relationships, workflow patterns, and constraints (see [Instructions](https://modelcontextprotocol.io/specification/latest/basic/lifecycle#instructions) in the MCP specification). Clients may add them to the system prompt. Instructions should not duplicate information already in tool descriptions.
+
+```ts source="../examples/server/src/serverGuide.examples.ts#instructions_basic"
+const server = new McpServer(
+    { name: 'db-server', version: '1.0.0' },
+    {
+        instructions:
+            'Always call list_tables before running queries. Use validate_schema before migrate_schema for safe migrations. Results are limited to 1000 rows.'
+    }
+);
+```
+
 ## Tools
 
 Tools let clients invoke actions on your server — they are usually the main way LLMs call into your application (see [Tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools) in the MCP overview).
@@ -324,6 +338,45 @@ server.registerTool(
 );
 ```
 
+## Progress
+
+Progress notifications let a tool report incremental status updates during long-running operations (see [Progress](https://modelcontextprotocol.io/specification/latest/basic/utilities/progress) in the MCP specification).
+
+If the client includes a `progressToken` in the request `_meta`, send `notifications/progress` via `ctx.mcpReq.notify()` (from {@linkcode @modelcontextprotocol/server!index.BaseContext | BaseContext}):
+
+```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_progress"
+server.registerTool(
+    'process-files',
+    {
+        description: 'Process files with progress updates',
+        inputSchema: z.object({ files: z.array(z.string()) })
+    },
+    async ({ files }, ctx): Promise<CallToolResult> => {
+        const progressToken = ctx.mcpReq._meta?.progressToken;
+
+        for (let i = 0; i < files.length; i++) {
+            // ... process files[i] ...
+
+            if (progressToken !== undefined) {
+                await ctx.mcpReq.notify({
+                    method: 'notifications/progress',
+                    params: {
+                        progressToken,
+                        progress: i + 1,
+                        total: files.length,
+                        message: `Processed ${files[i]}`
+                    }
+                });
+            }
+        }
+
+        return { content: [{ type: 'text', text: `Processed ${files.length} files` }] };
+    }
+);
+```
+
+`progress` must increase on each call. `total` and `message` are optional. If the client does not provide a `progressToken`, skip the notification.
+
 ## Server-initiated requests
 
 MCP is bidirectional — servers can send requests *to* the client during tool execution, as long as the client declares matching capabilities (see [Architecture](https://modelcontextprotocol.io/docs/learn/architecture) in the MCP overview).
@@ -422,6 +475,25 @@ server.registerTool(
 
 For runnable examples, see [`elicitationFormExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts) (form) and [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationUrlExample.ts) (URL).
 
+### Roots
+
+Roots let a tool handler discover the client's workspace directories — for example, to scope a file search or identify project boundaries (see [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) in the MCP overview). Call {@linkcode @modelcontextprotocol/server!server/server.Server#listRoots | server.server.listRoots()} (requires the client to declare the `roots` capability):
+
+```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_roots"
+server.registerTool(
+    'list-workspace-files',
+    {
+        description: 'List files across all workspace roots',
+        inputSchema: z.object({})
+    },
+    async (_args, _ctx): Promise<CallToolResult> => {
+        const { roots } = await server.server.listRoots();
+        const summary = roots.map(r => `${r.name ?? r.uri}: ${r.uri}`).join('\n');
+        return { content: [{ type: 'text', text: summary }] };
+    }
+);
+```
+
 ## Tasks (experimental)
 
 > [!WARNING]
@@ -474,7 +546,7 @@ For a complete multi-session server with shutdown handling, see [`simpleStreamab
 
 Under normal circumstances, cross-origin browser restrictions limit what a malicious website can do to your localhost server. [DNS rebinding attacks](https://en.wikipedia.org/wiki/DNS_rebinding) get around those restrictions entirely by making the requests appear as same-origin, since the attacking domain resolves to localhost. Validating the host header on the server side protects against this scenario.  **All localhost MCP servers should use DNS rebinding protection.**
 
-The recommended approach is to use {@linkcode @modelcontextprotocol/express!express.createMcpExpressApp | createMcpExpressApp()} (from `@modelcontextprotocol/express`) or `createMcpHonoApp()` (from `@modelcontextprotocol/hono`), which enable Host header validation by default:
+The recommended approach is to use {@linkcode @modelcontextprotocol/express!express.createMcpExpressApp | createMcpExpressApp()} (from `@modelcontextprotocol/express`) or {@linkcode @modelcontextprotocol/hono!hono.createMcpHonoApp | createMcpHonoApp()} (from `@modelcontextprotocol/hono`), which enable Host header validation by default:
 
 ```ts source="../examples/server/src/serverGuide.examples.ts#dnsRebinding_basic"
 // Default: DNS rebinding protection auto-enabled (host is 127.0.0.1)

examples/server/src/serverGuide.examples.ts

@@ -18,20 +18,17 @@ import * as z from 'zod/v4';
 //#endregion imports
 
 // ---------------------------------------------------------------------------
-// Instructions
+// Server instructions
 // ---------------------------------------------------------------------------
 
-/** Example: Providing server instructions to guide LLM usage. */
+/** Example: McpServer with instructions for LLM guidance. */
 function instructions_basic() {
     //#region instructions_basic
     const server = new McpServer(
+        { name: 'db-server', version: '1.0.0' },
         {
-            name: 'multi-tool-server',
-            version: '1.0.0'
-        },
-        {
-            instructions: `This server provides data-pipeline tools. Always call "validate-schema"
-before calling "transform-data" to avoid runtime errors.`
+            instructions:
+                'Always call list_tables before running queries. Use validate_schema before migrate_schema for safe migrations. Results are limited to 1000 rows.'
         }
     );
     //#endregion instructions_basic
@@ -283,6 +280,44 @@ function registerTool_logging() {
     return server;
 }
 
+// ---------------------------------------------------------------------------
+// Progress
+// ---------------------------------------------------------------------------
+
+/** Example: Tool that sends progress notifications during a long-running operation. */
+function registerTool_progress(server: McpServer) {
+    //#region registerTool_progress
+    server.registerTool(
+        'process-files',
+        {
+            description: 'Process files with progress updates',
+            inputSchema: z.object({ files: z.array(z.string()) })
+        },
+        async ({ files }, ctx): Promise<CallToolResult> => {
+            const progressToken = ctx.mcpReq._meta?.progressToken;
+
+            for (let i = 0; i < files.length; i++) {
+                // ... process files[i] ...
+
+                if (progressToken !== undefined) {
+                    await ctx.mcpReq.notify({
+                        method: 'notifications/progress',
+                        params: {
+                            progressToken,
+                            progress: i + 1,
+                            total: files.length,
+                            message: `Processed ${files[i]}`
+                        }
+                    });
+                }
+            }
+
+            return { content: [{ type: 'text', text: `Processed ${files.length} files` }] };
+        }
+    );
+    //#endregion registerTool_progress
+}
+
 // ---------------------------------------------------------------------------
 // Server-initiated requests
 // ---------------------------------------------------------------------------
@@ -365,6 +400,24 @@ function registerTool_elicitation(server: McpServer) {
     //#endregion registerTool_elicitation
 }
 
+/** Example: Tool that requests the client's filesystem roots. */
+function registerTool_roots(server: McpServer) {
+    //#region registerTool_roots
+    server.registerTool(
+        'list-workspace-files',
+        {
+            description: 'List files across all workspace roots',
+            inputSchema: z.object({})
+        },
+        async (_args, _ctx): Promise<CallToolResult> => {
+            const { roots } = await server.server.listRoots();
+            const summary = roots.map(r => `${r.name ?? r.uri}: ${r.uri}`).join('\n');
+            return { content: [{ type: 'text', text: summary }] };
+        }
+    );
+    //#endregion registerTool_roots
+}
+
 // ---------------------------------------------------------------------------
 // Transports
 // ---------------------------------------------------------------------------
@@ -488,8 +541,10 @@ void registerTool_resourceLink;
 void registerTool_errorHandling;
 void registerTool_annotations;
 void registerTool_logging;
+void registerTool_progress;
 void registerTool_sampling;
 void registerTool_elicitation;
+void registerTool_roots;
 void registerResource_static;
 void registerResource_template;
 void registerPrompt_basic;